ZVBI Library  0.2.33
Data Fields
vbi_page Struct Reference

Formatted Teletext or Closed Caption page. More...

Data Fields

vbi_decodervbi
vbi_nuid nuid
int pgno
int subno
int rows
int columns
vbi_char text [1056]
struct {
   int   y0
   int   y1
   int   roll
dirty
vbi_color screen_color
vbi_opacity screen_opacity
vbi_rgba color_map [40]
uint8_t * drcs_clut
uint8_t * drcs [32]
struct {
   int   pgno
   int   subno
nav_link [6]
char nav_index [64]
struct vbi_font_descrfont [2]
unsigned int double_height_lower
vbi_opacity page_opacity [2]
vbi_opacity boxed_opacity [2]

Detailed Description

Formatted Teletext or Closed Caption page.

Clients can fetch pages from the respective cache using vbi_fetch_vt_page() or vbi_fetch_cc_page() for evaluation, display or output. Since the page may reference other objects in cache which are locked by the fetch functions, vbi_unref_page() must be called when done. Note this structure is large, some 10 KB.

Examples:
src/exp-templ.c.

Field Documentation

vbi_decoder* vbi_page::vbi

Points back to the source context.

vbi_nuid vbi_page::nuid

Identifies the network broadcasting this page.

int vbi_page::pgno

Page number, see vbi_pgno.

Examples:
src/exp-templ.c.
int vbi_page::subno

Subpage number, see vbi_subno.

Examples:
src/exp-templ.c.
int vbi_page::rows

Number of character rows in the page.

int vbi_page::columns

Number of character columns in the page.

vbi_char vbi_page::text[1056]

The page contents, these are rows x columns without padding between the rows. See vbi_char for details.

struct { ... } vbi_page::dirty

To speed up rendering these variables mark the rows which actually changed since the page has been last fetched from cache. y0 ... y1 are the first to last row changed, inclusive, in range 0 ... rows - 1. roll indicates the page has been vertically scrolled this number of rows, negative numbers up (towards lower row numbers), positive numbers down. For example -1 means row y0 + 1 ... y1 moved to y0 ... y1 - 1, erasing row y1 to all spaces.

Practically this is only used in Closed Caption roll-up mode, otherwise all rows are always marked dirty. Clients are free to ignore this information.

vbi_color vbi_page::screen_color

When a TV displays Teletext or Closed Caption pages, only a section in the center of the screen is actually covered by characters. The remaining space is referred to here as 'border', which can have a color different from the typical black. (In the Teletext specs this is referred to as the screen color, hence the field name.) This is a vbi_color index into the color_map.

vbi_opacity vbi_page::screen_opacity

The 'border' can also have a distinguished opacity. Typically this will be VBI_OPAQUE, but pages intended for overlay onto video (Teletext subtitles, newsflash, Caption pages) will have a screen_opacity of VBI_TRANSPARENT_SPACE. See vbi_opacity for details.

vbi_rgba vbi_page::color_map[40]

This is the color palette indexed by vbi_color in vbi_char and elsewhere, colors defined as vbi_rgba. Note this palette may not correspond to the vbi_color enumeration since Teletext allows editors to redefine the entire palette. Closed Caption and Teletext Level 1.0/1.5 pages use entries 0 ... 7. Teletext Level 2.5/3.5 pages use entries 0 ... 31. Navigation related text (TOP, FLOF) added by libzvbi uses entries 32 ... 39 which are not subject to redefinition.

uint8_t* vbi_page::drcs_clut

DRCS (dynamically redefinable characters) can have two, four or sixteen different colors. Without further details, the effective color of each pixel is given by

whereby drcs_clut[0] shall be replaced by vbi_char->foreground, drcs_clut[1] by vbi_char->background. (Renderers are supposed to convert the drcs_clut into a private color map of the desired pixel format.)

Practically vbi_char->drcs_clut_offs encodes the DRCS color depth and selects between the vbi_char colors and one of two 4- or 16-entry Color Look-Up Tables. Also the different resolution of DRCS and the bitplane color coding is hidden to speed up rendering.

uint8_t* vbi_page::drcs[32]

Pointer to DRCS data. Per definition the maximum number of DRCS usable at the same time, i. e. on one page, is limited to 96. However the number of DRCS defined in a Teletext data stream can be much larger. The 32 pointers here correspond to the 32 DRCS character planes mentioned in the vbi_char description. Each of them points to an array of character definitions, a DRCS font. One character occupies 60 bytes or 12 x 10 pixels, stored left to right and top to bottom. The color of each pixel (index into drcs_clut) is coded in four bits stored in little endian order, first pixel 0x0F, second pixel 0xF0 and so on. For example the first, top/leftmost pixel can be found at

vbi_page->drcs[(unicode >> 6) & 0x1F][(unicode & 0x3F) * 60]

Do not access DRCS data unless referenced by a vbi_char in text, a segfault may result. Do not access DRCS data after calling vbi_unref_page(), it may not be cached anymore.