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.

index: Index into the export module list, 0 ... n.
Returns :Static pointer to a vbi_export_info structure (no need to be freed), NULL if the index is out of bounds.


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.

keyword: Export module identifier as in vbi_export_info and vbi_export_new().
Returns :Static pointer to a vbi_export_info structure, NULL if the named export module has not been found.


vbi_export_info_export ()

vbi_export_info* vbi_export_info_export     (vbi_export *export);

Returns the export module info for the given export object.

export: Pointer to a vbi_export object previously allocated with vbi_export_new().
Returns : A static vbi_export_info pointer or NULL if export is NULL.


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_new("keyword; quality=75.5, comment=\"example\"");  

keyword: Export module identifier as in vbi_export_info.
errstr: If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
Returns :Pointer to a newly allocated vbi_export object which must be freed by calling vbi_export_delete(). NULL is returned and the errstr may be set (or NULL) if some problem occurred.


vbi_export_delete ()

void        vbi_export_delete               (vbi_export *export);

This function frees all resources associated with the vbi_export object.

export: Pointer to a vbi_export object previously allocated with vbi_export_new(). Can be NULL.


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_BOOLA boolean value, either TRUE (1) or FALSE (0).

Type:int
Default:def.num
Bounds:min.num (0) ... max.num (1), step.num (1)
Menu:NULL

VBI_OPTION_INTA signed integer value. When only a few discrete values rather than a range are permitted menu points to a vector of integers. Note the option is still set by value, not by menu index, which may be rejected or replaced by the closest possible.

Type:int
Default:def.num or menu.num[def.num]
Bounds:min.num ... max.num, step.num or menu
Menu:NULL or menu.num[min.num ... max.num], step.num (1)

VBI_OPTION_REALA real value, optional a vector of possible values.

Type:double
Default:def.dbl or menu.dbl[def.num]
Bounds:min.dbl ... max.dbl, step.dbl or menu
Menu:NULL or menu.dbl[min.num ... max.num], step.num (1)

VBI_OPTION_STRINGA null terminated string. Note the menu version differs from VBI_OPTION_MENU in its argument, which is the string itself. For example:
menu.str[0] = "red"
menu.str[1] = "blue"
... and perhaps other colors not explicitely listed

Type:char *
Default:def.str or menu.str[def.num]
Bounds:not applicable
Menu:NULL or menu.str[min.num ... max.num], step.num (1)

VBI_OPTION_MENUChoice between a number of named options. For example:
menu.str[0] = "up"
menu.str[1] = "down"
menu.str[2] = "strange"

Type:int
Default:def.num
Bounds:min.num ... max.num, step.num (1)
Menu:menu.str[min.num ... max.num], step.num (1). These strings are gettext'ized N_(), see the gettext() manuals for details.


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.

export: Pointer to a initialized vbi_export object.
index: Index in the option table 0 ... n.
Returns : Static pointer to a vbi_option_info structure, NULL if index is out of bounds.


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.

export: Pointer to a initialized vbi_export object.
keyword: Keyword of the option as in vbi_option_info.
Returns : Static pointer to a vbi_option_info structure, NULL if the keyword wasn't found.


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.

export: Pointer to a initialized vbi_export object.
keyword: Keyword identifying the option, as in vbi_option_info.
value: A place to store the current option value.
Returns :TRUE on success, otherwise value remained unchanged.


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:

vbi_export_option_set(export, "quality", 75.5);

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.

export: Pointer to a initialized vbi_export object.
keyword: Keyword identifying the option, as in vbi_option_info.
...: New value to set.
Returns :TRUE on success, otherwise the option is not changed.


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.

export: Pointer to a initialized vbi_export object.
keyword: Keyword identifying the option, as in vbi_option_info.
entry: A place to store the current menu entry.
Returns : TRUE on success, otherwise value remained unchanged.


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.

export: Pointer to a initialized vbi_export object.
keyword: Keyword identifying the option, as in vbi_option_info.
entry: Menu entry to be selected.
Returns : TRUE on success, otherwise the option is not changed.


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.

export: Pointer to a initialized vbi_export object.
fp: Buffered i/o stream to write to.
pg: Page to be exported.
Returns : TRUE on success.


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.

export: Pointer to a initialized vbi_export object.
name: File to be created.
pg: Page to be exported.
Returns : TRUE on success.


vbi_export_errstr ()

char*       vbi_export_errstr               (vbi_export *export);

export: Pointer to a initialized vbi_export object.
Returns : After an export function failed, this function returns a pointer to a more detailed error description. Do not free this string. It remains valid until the next call of an export function.


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.

pg: Source page.
fmt: Target format. For now only VBI_PIXFMT_RGBA32_LE (vbi_rgba) permitted.
canvas: Pointer to destination image (currently an array of vbi_rgba), this must be at least rowstride * height * 10 bytes large.
rowstride: canvas byte distance from line to line. If this is -1, pg->columns * 12 * sizeof(vbi_rgba) bytes will be assumed.
column: First source column, 0 ... pg->columns - 1.
row: First source row, 0 ... pg->rows - 1.
width: Number of columns to draw, 1 ... pg->columns.
height: Number of rows to draw, 1 ... pg->rows.
reveal: If FALSE, draw characters flagged 'concealed' (see vbi_char) as space (U+0020).
flash_on: If FALSE, draw characters flagged 'blink' (see vbi_char) as space (U+0020).


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.

pg: Source page.
fmt: Target format. For now only VBI_PIXFMT_RGBA32_LE (vbi_rgba) permitted.
canvas: Pointer to destination image (currently an array of vbi_rgba). This must be at least pg->columns * pg->rows * 12 * 10 * pixels large, without padding between lines.
reveal: If FALSE, draw characters flagged 'concealed' (see vbi_char) as space (U+0020).
flash_on: If FALSE, draw characters flagged 'blink' (see vbi_char) as space (U+0020).


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.

pg: Source page.
fmt: Target format. For now only VBI_PIXFMT_RGBA32_LE (vbi_rgba) permitted.
canvas: Pointer to destination image (currently an array of vbi_rgba), this must be at least rowstride * height * 26 bytes large.
rowstride: canvas byte distance from line to line. If this is -1, pg->columns * 16 * sizeof(vbi_rgba) bytes will be assumed.
column: First source column, 0 ... pg->columns - 1.
row: First source row, 0 ... pg->rows - 1.
width: Number of columns to draw, 1 ... pg->columns.
height: Number of rows to draw, 1 ... pg->rows.


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.

pg: Source page.
fmt: Target format. For now only VBI_PIXFMT_RGBA32_LE (vbi_rgba) permitted.
canvas: Pointer to destination image (currently an array of vbi_rgba). This must be at least pg->columns * pg->rows * 16 * 26 * pixels large, without padding between lines.


vbi_get_max_rendered_size ()

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

Deprecated, will be removed.

w: 
h: 


vbi_get_vt_cell_size ()

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

Deprecated, will be removed.

w: 
h: 


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.

pg: Source page.
buf: Memory location to hold the ouput.
size: Size of the buffer in bytes. The function fails before the data exceeds the buffer capacity.
format: Character set name for iconv() conversion, for example "ISO-8859-1".
table: Scan page in table mode, printing all characters within the source rectangle. Otherwise scan all characters from column, row to column + width - 1, row + height - 1 and all intermediate rows to their full pg->columns width. Table mode also preserves runs of spaces at the start and end of rows.
ltr: 
column: First source column, 0 ... pg->columns - 1.
row: First source row, 0 ... pg->rows - 1.
width: Number of columns to print, 1 ... pg->columns.
height: Number of rows to print, 1 ... pg->rows.
Returns :Number of bytes written into buf, a value of zero when some error occurred. In this case buf may contain incomplete data. Note this function does not append a terminating null character.


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.

pg: Source page.
buf: Memory location to hold the ouput.
size: Size of the buffer in bytes. The function fails before the data exceeds the buffer capacity.
format: Character set name for iconv() conversion, for example "ISO-8859-1".
table: When FALSE, runs of spaces at the start and end of rows will be collapsed into single spaces.
ltr: Currently ignored, please set to FALSE.
Returns :Number of bytes written into buf, a value of zero when some error occurred. In this case buf may contain incomplete data. Note this function does not append a terminating null character.