Main Page | Modules | Data Structures | Data Fields | Related Pages | Examples

Data Service Decoder
[High Level Decoding]


Functions

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

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

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

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_version (unsigned int *major, unsigned int *minor, unsigned int *micro)
void vbi_set_log_fn (vbi_log_mask mask, vbi_log_fn *log_fn, void *user_data)

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_version unsigned int *  major,
unsigned int *  minor,
unsigned int *  micro
 

Parameters:
major Store major number here, can be NULL.
minor Store minor number here, can be NULL.
micro Store micro number here, can be NULL.
Returns the library version defined in the libzvbi.h header file when the library was compiled.

Since:
0.2.5

void vbi_set_log_fn vbi_log_mask  mask,
vbi_log_fn *  log_fn,
void *  user_data
 

Parameters:
mask Which kind of information to log. Can be 0.
log_fn This function is called with log messages. Consider vbi_log_on_stderr(). Can be NULL to disable logging.
user_data User pointer passed through to the log_fn function.
Various functions can print warnings, errors and information useful to debug the library. With this function you can enable these messages and determine a function to print them.

Note:
The kind and contents of messages logged by particular functions may change in the future.
Since:
0.2.22


Generated on Mon Jun 9 21:44:14 2008 for ZVBI Library by doxygen 1.3.5