ZVBI Library Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up |
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); |
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); } |
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* 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* 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* 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* 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:
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. |
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. |
typedef enum { VBI_OPTION_BOOL = 1, VBI_OPTION_INT, VBI_OPTION_REAL, VBI_OPTION_STRING, VBI_OPTION_MENU } vbi_option_type; |
VBI_OPTION_BOOL | A boolean value, either TRUE (1) or FALSE (0). | |
VBI_OPTION_INT | A 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. | |
VBI_OPTION_REAL | A real value, optional a vector of possible values. | |
VBI_OPTION_STRING | A null terminated string. Note the menu version differs from
VBI_OPTION_MENU in its argument, which is the string itself. For example:
| |
VBI_OPTION_MENU | Choice between a number of named options. For example:
|
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_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_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_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_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.
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_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_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_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_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.
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). |
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). |
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. |
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.
void vbi_get_max_rendered_size (int *w, int *h); |
Deprecated, will be removed.
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. |
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. |