Page export

Name

Page export -- Exporting formatted Teletext and Closed Caption pages.

Synopsis




typedef     vbi_export_info;
vbi_export_info* vbi_export_info_enum       (int index);
vbi_export_info* vbi_export_info_keyword    (const char *keyword);
vbi_export_info* vbi_export_info_export     (vbi_export *export);
vbi_export* vbi_export_new                  (const char *keyword,
                                             char **errstr);
void        vbi_export_delete               (vbi_export *export);

enum        vbi_option_type;
typedef     vbi_option_info;

vbi_option_info* vbi_export_option_info_enum
                                            (vbi_export *export,
                                             int index);
vbi_option_info* vbi_export_option_info_keyword
                                            (vbi_export *export,
                                             const char *keyword);
vbi_bool    vbi_export_option_get           (vbi_export *export,
                                             const char *keyword,
                                             vbi_option_value *value);
vbi_bool    vbi_export_option_set           (vbi_export *export,
                                             const char *keyword,
                                             ...);
vbi_bool    vbi_export_option_menu_get      (vbi_export *export,
                                             const char *keyword,
                                             int *entry);
vbi_bool    vbi_export_option_menu_set      (vbi_export *export,
                                             const char *keyword,
                                             int entry);

vbi_bool    vbi_export_stdio                (vbi_export *export,
                                             FILE *fp,
                                             vbi_page *pg);
vbi_bool    vbi_export_file                 (vbi_export *export,
                                             const char *name,
                                             vbi_page *pg);

char*       vbi_export_errstr               (vbi_export *export);

void        vbi_draw_vt_page_region         (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int rowstride,
                                             int column,
                                             int row,
                                             int width,
                                             int height,
                                             int reveal,
                                             int flash_on);
void        vbi_draw_vt_page                (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int reveal,
                                             int flash_on);
void        vbi_draw_cc_page_region         (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int rowstride,
                                             int column,
                                             int row,
                                             int width,
                                             int height);
void        vbi_draw_cc_page                (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas);
void        vbi_get_max_rendered_size       (int *w,
                                             int *h);
void        vbi_get_vt_cell_size            (int *w,
                                             int *h);

int         vbi_print_page_region           (vbi_page *pg,
                                             char *buf,
                                             int size,
                                             const char *format,
                                             vbi_bool table,
                                             vbi_bool ltr,
                                             int column,
                                             int row,
                                             int width,
                                             int height);
int         vbi_print_page                  (vbi_page *pg,
                                             char *buf,
                                             int size,
                                             const char *format,
                                             vbi_bool table,
                                             vbi_bool ltr);

Description

Once libvbi received, decoded and formatted a Teletext or Closed Caption page you will want to render it on screen, print it as text or store it in various formats. Luckily you don't have to do it all by yourself, libvbi provides export modules converting a vbi_page into the desired format or rendering directly into memory.

Example 1. A minimalistic export example

static void
export_my_page(vbi_page *pg)
{
	vbi_export *ex;

	if (!(ex = vbi_export_new("html"))) {
		puts("Cannot export as HTML");
		return;
	}

	if (!vbi_export_file(ex, "my_page.html", pg))
		puts(vbi_export_errstr(ex));

	vbi_export_delete(ex);
}

Details

vbi_export_info

typedef struct vbi_export_info {
	char *			keyword;
	char *			label;		/* or NULL, gettext()ized N_() */
	char *			tooltip;	/* or NULL, gettext()ized N_() */

	char *			mime_type;	/* or NULL */
	char *			extension;	/* or NULL */
} vbi_export_info;

Although export modules can be accessed by a static keyword (see vbi_export_new()) they are by definition opaque. The client can list export modules for the user and manipulate them without knowing about their presence or purpose. To do so, some amount of information about the module is necessary, given in this structure.

You can obtain this information with vbi_export_info_enum().

keyword: Unique (within this library) keyword to identify this export module. Can be stored in configuration files. label: Name of the export module to be shown to the user. This can be NULL to indicate this module shall not be listed. tooltip: A brief description (or NULL) for the user. mime_type: Description of the export format as MIME type, for example "text/html". May be NULL. extension: Suggested filename extension. Multiple strings are possible, separated by comma. The first string is preferred. Example: "html,htm". May be NULL.


vbi_export_info_enum ()

vbi_export_info* vbi_export_info_enum       (int index);

Enumerates all available export modules. You should start at index 0, incrementing.

Some modules may depend on machine features or the presence of certain libraries, thus the list can vary from session to session.


vbi_export_info_keyword ()

vbi_export_info* vbi_export_info_keyword    (const char *keyword);

Similar to vbi_export_info_enum(), but this function attempts to find an export module by keyword.


vbi_export_info_export ()

vbi_export_info* vbi_export_info_export     (vbi_export *export);

Returns the export module info for the given export object.


vbi_export_new ()

vbi_export* vbi_export_new                  (const char *keyword,
                                             char **errstr);

Creates a new export module instance to export a vbi_page in the respective module format. As a special service you can initialize options by appending to the keyword like this:


vbi_export_delete ()

void        vbi_export_delete               (vbi_export *export);

This function frees all resources associated with the vbi_export object.


enum vbi_option_type

typedef enum {
	VBI_OPTION_BOOL = 1,
	VBI_OPTION_INT,
	VBI_OPTION_REAL,
	VBI_OPTION_STRING,
	VBI_OPTION_MENU
} vbi_option_type;


vbi_option_info

typedef struct vbi_option_info {
	vbi_option_type		type;
	char *			keyword;
	char *			label;
	vbi_option_value	def;
	vbi_option_value	min;
	vbi_option_value	max;
	vbi_option_value	step;
	vbi_option_value_ptr	menu;
	char *			tooltip;
} vbi_option_info;

Although export options can be accessed by a static keyword (see vbi_export_option_set()) they are by definition opaque. The client can present them to the user and manipulate them without knowing about their presence or purpose. To do so, some amount of information about the option is necessary, given in this structure.

You can obtain this information with vbi_export_option_info_enum().

type: Type of the option, see vbi_option_type for details.

keyword: Unique (within this export module) keyword to identify this option. Can be stored in configuration files.

label: Name of the option to be shown to the user. This can be NULL to indicate this option shall not be listed. gettext()ized N_(), see the gettext manual.

def, min, max, step, menu: See vbi_option_type for details.

tooltip: A brief description (or NULL) for the user. gettext()ized N_(), see the gettext manual.


vbi_export_option_info_enum ()

vbi_option_info* vbi_export_option_info_enum
                                            (vbi_export *export,
                                             int index);

Enumerates the options available for the given export module. You should start at index 0, incrementing.


vbi_export_option_info_keyword ()

vbi_option_info* vbi_export_option_info_keyword
                                            (vbi_export *export,
                                             const char *keyword);

Similar to vbi_export_option_info_enum(), but tries to find the option info based on the given keyword.


vbi_export_option_get ()

vbi_bool    vbi_export_option_get           (vbi_export *export,
                                             const char *keyword,
                                             vbi_option_value *value);

This function queries the current value of the named option. When the option is of type VBI_OPTION_STRING value.str must be freed with free() when you don't need it any longer. When the option is of type VBI_OPTION_MENU then value.num contains the selected entry.


vbi_export_option_set ()

vbi_bool    vbi_export_option_set           (vbi_export *export,
                                             const char *keyword,
                                             ...);

Sets the value of the named option. Make sure the value is casted to the correct type (int, double, char *). Typical usage may be:

Mind that options of type VBI_OPTION_MENU must be set by menu entry (int), all other options by value. If necessary this will be replaced by the closest value possible. Use function vbi_export_option_menu_set() to set all menu options by menu entry.


vbi_export_option_menu_get ()

vbi_bool    vbi_export_option_menu_get      (vbi_export *export,
                                             const char *keyword,
                                             int *entry);

Similar to vbi_export_option_get() this function queries the current value of the named option, but returns this value as number of the corresponding menu entry. Naturally this must be an option with menu.


vbi_export_option_menu_set ()

vbi_bool    vbi_export_option_menu_set      (vbi_export *export,
                                             const char *keyword,
                                             int entry);

Similar to vbi_export_option_set() this function sets the value of the named option, however it does so by number of the corresponding menu entry. Naturally this must be an option with menu.


vbi_export_stdio ()

vbi_bool    vbi_export_stdio                (vbi_export *export,
                                             FILE *fp,
                                             vbi_page *pg);

This function writes the pg contents, converted to the respective export module format, to the stream fp. You are responsible for opening and closing the stream, don't forget to check for i/o errors after closing. Note this function may write incomplete files when an error occurs.

You can call this function as many times as you want, it does not change vbi_export state or the vbi_page.


vbi_export_file ()

vbi_bool    vbi_export_file                 (vbi_export *export,
                                             const char *name,
                                             vbi_page *pg);

This function writes the pg contents, converted to the respective export module format, into a newly created file (as with fopen()) of the given name. When an error occured the incomplete file will be deleted.

You can call this function as many times as you want, it does not change vbi_export state or the vbi_page.


vbi_export_errstr ()

char*       vbi_export_errstr               (vbi_export *export);


vbi_draw_vt_page_region ()

void        vbi_draw_vt_page_region         (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int rowstride,
                                             int column,
                                             int row,
                                             int width,
                                             int height,
                                             int reveal,
                                             int flash_on);

Draw a subsection of a Teletext vbi_page. In this mode one character occupies 12 x 10 pixels.


vbi_draw_vt_page ()

void        vbi_draw_vt_page                (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int reveal,
                                             int flash_on);

Draw a Teletext vbi_page. In this mode one character occupies 12 x 10 pixels.


vbi_draw_cc_page_region ()

void        vbi_draw_cc_page_region         (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas,
                                             int rowstride,
                                             int column,
                                             int row,
                                             int width,
                                             int height);

Draw a subsection of a Closed Caption vbi_page. In this mode one character occupies 16 x 26 pixels.


vbi_draw_cc_page ()

void        vbi_draw_cc_page                (vbi_page *pg,
                                             vbi_pixfmt fmt,
                                             void *canvas);

Draw a Closed Caption vbi_page. In this mode one character occupies 16 x 26 pixels.


vbi_get_max_rendered_size ()

void        vbi_get_max_rendered_size       (int *w,
                                             int *h);

Deprecated, will be removed.


vbi_get_vt_cell_size ()

void        vbi_get_vt_cell_size            (int *w,
                                             int *h);

Deprecated, will be removed.


vbi_print_page_region ()

int         vbi_print_page_region           (vbi_page *pg,
                                             char *buf,
                                             int size,
                                             const char *format,
                                             vbi_bool table,
                                             vbi_bool ltr,
                                             int column,
                                             int row,
                                             int width,
                                             int height);

Print a subsection of a Teletext or Closed Caption vbi_page, rows separated by linefeeds "\n", in the desired format. All character attributes and colors will be lost. Graphics characters, DRCS and all characters not representable in the target format will be replaced by spaces.


vbi_print_page ()

int         vbi_print_page                  (vbi_page *pg,
                                             char *buf,
                                             int size,
                                             const char *format,
                                             vbi_bool table,
                                             vbi_bool ltr);

Print a Teletext or Closed Caption vbi_page, rows separated by linefeeds "\n", in the desired format. All character attributes and colors will be lost. Graphics characters, DRCS and all characters not representable in the target format will be replaced by spaces.