Main Page   Modules   Data Structures   Data Fields   Related Pages   Examples  

Data Service Decoder


Modules

BCD arithmetic for Teletext page numbers
Page cache
Events
Exporting formatted Teletext and Closed Caption pages
Formatted text page

Defines

#define VBI_ANY_SUBNO   0x3F7F
#define VBI_NO_SUBNO   0x3F7F

Typedefs

typedef int vbi_pgno
typedef int vbi_subno

Enumerations

enum  vbi_page_type {
  VBI_NO_PAGE = 0x00,
  VBI_NORMAL_PAGE = 0x01,
  VBI_SUBTITLE_PAGE = 0x70,
  VBI_SUBTITLE_INDEX = 0x78,
  VBI_NONSTD_SUBPAGES = 0x79,
  VBI_PROGR_WARNING = 0x7A,
  VBI_CURRENT_PROGR = 0x7C,
  VBI_NOW_AND_NEXT = 0x7D,
  VBI_PROGR_INDEX = 0x7F,
  VBI_PROGR_SCHEDULE = 0x81,
  VBI_UNKNOWN_PAGE = 0xFF
}
 Page classification. More...

enum  vbi_wst_level {
  VBI_WST_LEVEL_1,
  VBI_WST_LEVEL_1p5,
  VBI_WST_LEVEL_2p5,
  VBI_WST_LEVEL_3p5
}
 Teletext implementation level. More...


Functions

vbi_decoder * vbi_decoder_new (void)
 Allocate a new data service decoder instance. More...

void vbi_decoder_delete (vbi_decoder *vbi)
 Delete a data service decoder instance. More...

void vbi_decode (vbi_decoder *vbi, vbi_sliced *sliced, int lines, double timestamp)
 Main function of the data service decoder. More...

void vbi_channel_switched (vbi_decoder *vbi, vbi_nuid nuid)
vbi_page_type vbi_classify_page (vbi_decoder *vbi, vbi_pgno pgno, vbi_subno *subno, char **language)
void vbi_teletext_set_default_region (vbi_decoder *vbi, int default_region)
void vbi_teletext_set_level (vbi_decoder *vbi, int level)

Typedef Documentation

typedef int vbi_pgno
 

Teletext or Closed Caption page number. For Teletext pages this is a bcd number in range 0x100 ... 0x8FF. Page numbers containing digits 0xA to 0xF are reserved for various system purposes, these pages are not intended for display.

Closed Caption page numbers between 1 ... 8 correspond to the four Caption and Text channels:
1Caption 1 "Primary synchronous caption service [English]"
2Caption 2 "Special non-synchronous data that is intended to augment information carried in the program"
3Caption 3 "Secondary synchronous caption service, usually second language [Spanish, French]"
4Caption 4 "Special non-synchronous data similar to Caption 2"
5Text 1 "First text service, data usually not program related"
6Text 2 "Second text service, additional data usually not program related [ITV data]"
7Text 3 "Additional text channel"
8Text 4 "Additional text channel"

typedef int vbi_subno
 

This is the subpage number only applicable to Teletext pages, a BCD number in range 0x00 ... 0x99. On special 'clock' pages (for example listing the current time in different time zones) it can assume values between 0x0000 ... 0x2359 expressing local time. These are not actually subpages.


Enumeration Type Documentation

enum vbi_page_type
 

Page classification.

See vbi_classify_page().

enum vbi_wst_level
 

Teletext implementation level.

Enumeration values:
VBI_WST_LEVEL_1  1 - Basic Teletext pages
VBI_WST_LEVEL_1p5  1.5 - Additional national and graphics characters
VBI_WST_LEVEL_2p5  2.5 - Additional text styles, more colors and DRCS. You should enable Level 2.5 only if you can render and/or export such pages.
VBI_WST_LEVEL_3p5  3.5 - Multicolor DRCS, proportional script


Function Documentation

vbi_decoder* vbi_decoder_new void   
 

Allocate a new data service decoder instance.

Returns:
vbi_decoder pointer or NULL on failure, probably due to lack of memory.

void vbi_decoder_delete vbi_decoder *    vbi
 

Delete a data service decoder instance.

Parameters:
vbi  Decoder structure allocated with vbi_decoder_new().

void vbi_decode vbi_decoder *    vbi,
vbi_sliced   sliced,
int    lines,
double    time
 

Main function of the data service decoder.

Parameters:
vbi  Initialized vbi decoding context as returned by vbi_decoder_new().
sliced  Array of vbi_sliced data packets to be decoded.
lines  Number of vbi_sliced data packets, i. e. VBI lines.
time  Timestamp associated with all sliced data packets. This is the time in seconds and fractions since 1970-01-01 00:00, for example from function gettimeofday(). time should only increment, the latest time entered is considered the current time for activity calculation.

Decodes zero or more lines of sliced VBI data from the same video frame, updates the decoder state and calls event handlers.

timestamp shall advance by 1/30 to 1/25 seconds whenever calling this function. Failure to do so will be interpreted as frame dropping, which starts a resynchronization cycle, eventually a channel switch may be assumed which resets even more decoder state. So even if a frame did not contain any useful data this function must be called, with lines set to zero.

Note:
This is one of the few not reentrant libzvbi functions. If multiple threads call this with the same vbi context you must implement your own locking mechanism. Never call this function from an event handler.

void vbi_channel_switched vbi_decoder *    vbi,
vbi_nuid    nuid
 

Parameters:
vbi  VBI decoding context.
nuid  Set to zero for now.
Call this after switching away from the channel (RF channel, video input line, precisely: the network) from which this context used to receive vbi data, to reset the decoding context accordingly. This includes deletion of all cached Teletext and Closed Caption pages.

The decoder attempts to detect channel switches automatically, but this is not 100 % reliable, especially without receiving and decoding Teletext or VPS which frequently transmit network identifiers.

Note the reset is not executed until the next frame is about to be decoded, so you may still receive "old" events after calling this. You may also receive blank events (e. g. unknown network, unknown aspect ratio) revoking a previously sent event, until new information becomes available.

vbi_page_type vbi_classify_page vbi_decoder *    vbi,
vbi_pgno    pgno,
vbi_subno   subno,
char **    language
 

Parameters:
vbi  Initialized vbi decoding context.
pgno  Teletext or Closed Caption page to examine, see vbi_pgno.
subno  The highest subpage number of this page will be stored here. subno can be NULL.
language  If it is possible to determine the language a page is written in, a pointer to the language name (Latin-1) will be stored here, NULL if the language is unknown. language can be NULL if this information is not needed.
Returns information about the page.

For Closed Caption pages (pgno 1 ... 8) subno will always be zero, language set or NULL. The return value will be VBI_SUBTITLE_PAGE for page 1 ... 4 (Closed Caption channel 1 ... 4), VBI_NORMAL_PAGE for page 5 ... 8 (Text channel 1 ... 4), or VBI_NO_PAGE if no data is currently transmitted on the channel.

For Teletext pages (pgno 0x100 ... 0x8FF) subno returns the highest subpage number used. Note this number can be larger (but not smaller) than the number of subpages actually received and cached. Still there is no guarantee the advertised subpages will ever appear or stay in cache.

subnomeaning
0single page, no subpages
1never
2 ... 0x3F7Fhas subpages 1 ... subno
0xFFFEhas unknown number (two or more) of subpages
0xFFFFpresence of subpages unknown

language currently returns the language of subtitle pages, NULL if unknown or the page is not classified as VBI_SUBTITLE_PAGE.

Other page types are:

VBI_NO_PAGEPage is not in transmission
VBI_NORMAL_PAGE 
VBI_SUBTITLE_PAGE 
VBI_SUBTITLE_INDEXList of subtitle pages
VBI_NONSTD_SUBPAGESFor example a world time page
VBI_PROGR_WARNINGProgram related warning (perhaps schedule change anouncements, the Teletext specification does not elaborate on this)
VBI_CURRENT_PROGRInformation about the current program
VBI_NOW_AND_NEXTBrief information about the current and next program
VBI_PROGR_INDEXProgram index page (perhaps the front page of all program related pages)
VBI_PROGR_SCHEDULEProgram schedule page
VBI_UNKNOWN_PAGE 

Note:
The results of this function are volatile: As more information becomes available and pages are edited (e. g. activation of subtitles, news updates, program related pages) subpage numbers can grow, page types, subno 0xFFFE and 0xFFFF and languages can change.
Returns:
Page type.

void vbi_teletext_set_default_region vbi_decoder *    vbi,
int    default_region
 

Parameters:
vbi  Initialized vbi decoding context.
default_region  A value between 0 ... 80, index into the Teletext character set table according to ETS 300 706, Section 15 (or libzvbi source file lang.c). The three last significant bits will be replaced.
The original Teletext specification distinguished between eight national character sets. When more countries started to broadcast Teletext the three bit character set id was locally redefined and later extended to seven bits grouping the regional variants. Since some stations still transmit only the legacy three bit id and we don't ship regional variants of this decoder as TV manufacturers do, this function can be used to set a default for the extended bits. The "factory default" is 16.

void vbi_teletext_set_level vbi_decoder *    vbi,
int    level
 

Parameters:
vbi  Initialized vbi decoding context.
level 
Deprecated:
This became a parameter of vbi_fetch_vt_page().


Generated on Thu Mar 20 20:43:47 2003 for ZVBI Library by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002