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

DVB VBI multiplexer
[Low Level Decoding]

Converting VBI data to a DVB PES or TS stream. More...

Typedefs

typedef _vbi_dvb_mux vbi_dvb_mux
 DVB VBI multiplexer context.

typedef vbi_bool vbi_dvb_mux_cb (vbi_dvb_mux *mx, void *user_data, const uint8_t *packet, unsigned int packet_size)

Functions

vbi_bool vbi_dvb_multiplex_sliced (uint8_t **packet, unsigned int *packet_left, const vbi_sliced **sliced, unsigned int *sliced_left, vbi_service_set service_mask, unsigned int data_identifier, vbi_bool stuffing)
vbi_bool vbi_dvb_multiplex_raw (uint8_t **packet, unsigned int *packet_left, const uint8_t **raw, unsigned int *raw_left, unsigned int data_identifier, vbi_videostd_set videostd_set, unsigned int line, unsigned int first_pixel_position, unsigned int n_pixels_total, vbi_bool stuffing)
void vbi_dvb_mux_reset (vbi_dvb_mux *mx) _vbi_nonnull((1))
vbi_bool vbi_dvb_mux_cor (vbi_dvb_mux *mx, uint8_t **buffer, unsigned int *buffer_left, const vbi_sliced **sliced, unsigned int *sliced_lines, vbi_service_set service_mask, const uint8_t *raw, const vbi_sampling_par *sampling_par, int64_t pts)
vbi_bool vbi_dvb_mux_feed (vbi_dvb_mux *mx, const vbi_sliced *sliced, unsigned int sliced_lines, vbi_service_set service_mask, const uint8_t *raw, const vbi_sampling_par *sampling_par, int64_t pts) _vbi_nonnull((1))
unsigned int vbi_dvb_mux_get_data_identifier (const vbi_dvb_mux *mx) _vbi_nonnull((1))
vbi_bool vbi_dvb_mux_set_data_identifier (vbi_dvb_mux *mx, unsigned int data_identifier) _vbi_nonnull((1))
unsigned int vbi_dvb_mux_get_min_pes_packet_size (vbi_dvb_mux *mx) _vbi_nonnull((1))
unsigned int vbi_dvb_mux_get_max_pes_packet_size (vbi_dvb_mux *mx) _vbi_nonnull((1))
vbi_bool vbi_dvb_mux_set_pes_packet_size (vbi_dvb_mux *mx, unsigned int min_size, unsigned int max_size) _vbi_nonnull((1))
void vbi_dvb_mux_delete (vbi_dvb_mux *mx)
vbi_dvb_muxvbi_dvb_pes_mux_new (vbi_dvb_mux_cb *callback, void *user_data) _vbi_alloc
vbi_dvb_muxvbi_dvb_ts_mux_new (unsigned int pid, vbi_dvb_mux_cb *callback, void *user_data) _vbi_alloc

Detailed Description

Converting VBI data to a DVB PES or TS stream.

These functions convert raw and/or sliced VBI data to a DVB Packetized Elementary Stream or Transport Stream as defined in EN 300 472 "Digital Video Broadcasting (DVB); Specification for conveying ITU-R System B Teletext in DVB bitstreams" and EN 301 775 "Digital Video Broadcasting (DVB); Specification for the carriage of Vertical Blanking Information (VBI) data in DVB bitstreams".

Note EN 300 468 "Digital Video Broadcasting (DVB); Specification for Service Information (SI) in DVB systems" defines another method to transmit VPS data in DVB streams. Libzvbi does not provide functions to generate SI tables but the vbi_encode_dvb_pdc_descriptor() function is available to convert a VPS PIL to a PDC descriptor.


Typedef Documentation

typedef struct _vbi_dvb_mux vbi_dvb_mux
 

DVB VBI multiplexer context.

The contents of this structure are private.

Call vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new() to allocate a DVB VBI multiplexer context.


Function Documentation

vbi_bool vbi_dvb_multiplex_sliced uint8_t **  packet,
unsigned int *  packet_left,
const vbi_sliced **  sliced,
unsigned int *  sliced_left,
vbi_service_set  service_mask,
unsigned int  data_identifier,
vbi_bool  stuffing
 

Parameters:
packet *packet must point at the output buffer where the data units will be stored. Initially this should be the position of the first data unit in a PES packet, immediately after the data_indentifier byte. *packet will be incremented by the cumulative size of the successfully stored data units.
packet_left *packet_left must contain the number of bytes available in the packet buffer. It will be decremented by the cumulative size of the successfully stored data units.
sliced *sliced shall point at the sliced VBI data to be converted, or it can be a NULL pointer. All data in this array must belong to the same video frame. The pointer will be advanced by the number of successfully converted structures. On failure it will point at the offending vbi_sliced structure.
sliced_left *sliced_left shall contain the number of vbi_sliced structures in the sliced array, or it can be zero. It will be decremented by the number of successfully converted structures.
service_mask Only data services in this set will be encoded. Other data services in the *sliced array will be discarded without further checks. Create a set by ORing VBI_SLICED_ values.
data_identifier When the data_indentifier lies in range 0x10 to 0x1F inclusive, the encoded data units will be padded to data_unit_length 0x2C for compatibility with EN 300 472 compliant decoders. The data_identifier itself will NOT be stored in the output buffer.
stuffing If TRUE, and space remains in the output buffer after all data has been successfully converted, or when *sliced is NULL or *sliced_left is zero, the function fills the buffer up with stuffing data units.
Converts the sliced VBI data in the sliced array to VBI data units as defined in EN 300 472 and EN 301 775 and stores them in the packet buffer.

Returns:
FALSE on failure.
  • *packet is NULL or *packet_left is less than two (the minimum data unit size is two bytes). The output buffer remains unchanged in this case.
  • The data_identifier is in range 0x10 to 0x1F inclusive and *packet_left is not a multiple of 46. The output buffer remains unchanged in this case.
  • The sliced array is not sorted by ascending line number, except for elements with line number 0 (undefined).
  • Only the following data services can be encoded:
    • VBI_SLICED_TELETEXT_B on lines 7 to 22 and 320 to 335 inclusive, or with line number 0 (undefined). All Teletext lines will be encoded with data_unit_id 0x02 ("EBU Teletext non-subtitle data").
    • VBI_SLICED_VPS on line 16.
    • VBI_SLICED_CAPTION_625 on line 22.
    • VBI_SLICED_WSS_625 on line 23.
  • A vbi_sliced structure contains a line number outside the valid range specified above.
All errors are recoverable. Just call the function again, possibly after skipping the offending sliced VBI data structure, to continue where it left off. Note *packet_left must be >= 2 (or a multiple of 46) in each call.

Note:
According to EN 300 472 and EN 301 775 all lines stored in one PES packet must belong to the same video frame (but the data of one frame may be transmitted in several successive PES packets). They must be encoded in the same order as they would be transmitted in the VBI, no line more than once. The function cannot enforce this if multiple calls are necessary to encode all data.
Since:
0.2.26

vbi_bool vbi_dvb_multiplex_raw uint8_t **  packet,
unsigned int *  packet_left,
const uint8_t **  raw,
unsigned int *  raw_left,
unsigned int  data_identifier,
vbi_videostd_set  videostd_set,
unsigned int  line,
unsigned int  first_pixel_position,
unsigned int  n_pixels_total,
vbi_bool  stuffing
 

Parameters:
packet *packet must point to the output buffer where the data units will be stored. Initially this should be the position of the first data unit in a PES packet, immediately after the data_indentifier byte. *packet will be incremented by the size of the successfully stored data units.
packet_left *packet_left must contain the number of bytes available in the packet buffer. It will be decremented by the cumulative size of the successfully stored data units.
raw *raw must point at the raw VBI data to be converted, namely luminance samples as defined in ITU-R BT.601 with 8 bits per sample. *raw will be incremented by the number of successfully converted samples.
raw_left *raw_left must contain the number of samples left to be encoded in the raw buffer. It will be decremented by the number of successfully converted samples.
data_identifier When the data_indentifier lies in range 0x10 to 0x1F inclusive, the encoded data units will be padded to data_unit_length 0x2C for compatibility with EN 300 472 compliant decoders. The data_identifier itself will NOT be stored in the output buffer.
videostd_set The line parameter will be interpreted according to this set of video standards. It must not change until all samples have been encoded. In libzvbi 0.2.x only one of two values are permitted: VBI_VIDEOSTD_SET_625_50 or VBI_VIDEOSTD_SET_525_60.
line The ITU-R line number to be encoded in the data units. It must not change until all samples have been encoded.
first_pixel_position The horizontal offset where decoders shall insert the first sample in the VBI, counting samples from the start of the digital active line as defined in ITU-R BT.601. Usually first_pixel_position is zero and n_pixels_total is 720. first_pixel_position + n_pixels_total must not be greater than 720. This parameter must not change until all samples have been encoded.
n_pixels_total Total size of the raw buffer in bytes, and the total number of samples to be encoded. Initially this value must be equal to *raw_left, and it must not change until all samples have been encoded.
stuffing If TRUE, and space remains in the output buffer after all samples have been successfully converted, the function fills up the buffer with stuffing data units.
Converts one line of raw VBI samples to one or more "monochrome 4:2:2 samples" data units as defined in EN 301 775, and stores them in the packet buffer.

Returns:
FALSE on failure:
  • *packet is NULL or *packet_left is less than two (the minimum data unit size is two bytes).
  • *raw is NULL or *raw_left is zero.
  • The data_identifier is in range 0x10 to 0x1F inclusive and *packet_left is not a multiple of 46.
  • The videostd_set is ambiguous.
  • The line parameter is outside the valid range, that is 7 to 23 and 270 to 286 for 525 line standards, 7 to 23 and 320 to 336 for 625 line standards. All numbers inclusive.
  • *raw_left is greater than n_pixels_total.
  • first_pixel_position + n_pixels_total is greater than 720.
The output buffer remains unchanged on all errors.

Note:
According to EN 301 775 all lines stored in one PES packet must belong to the same video frame (but the data of one frame may be transmitted in several successive PES packets). They must be encoded in the same order as they would be transmitted in the VBI, no line more than once. Samples may have to be split into multiple segments and they must be contiguously encoded into adjacent data units. The function cannot enforce this if multiple calls are necessary to encode all samples.
Since:
0.2.26

void vbi_dvb_mux_reset vbi_dvb_mux mx  ) 
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
Clears the internal buffers of the DVB VBI multiplexer.

After a vbi_dvb_mux_reset() call the vbi_dvb_mux_cor() function will encode a new PES packet, discarding any data of the previous packet which has not been consumed by the application.

Since:
0.2.26

vbi_bool vbi_dvb_mux_cor vbi_dvb_mux mx,
uint8_t **  buffer,
unsigned int *  buffer_left,
const vbi_sliced **  sliced,
unsigned int *  sliced_left,
vbi_service_set  service_mask,
const uint8_t *  raw,
const vbi_sampling_par *  sp,
int64_t  pts
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
buffer *buffer must point at the output buffer where the converted data will be stored, and will be incremented by the number of bytes stored there.
buffer_left *buffer_left must contain the number of bytes available in the buffer, and will be decremented by number of bytes stored there.
sliced *sliced must point at the sliced VBI data to be converted. All data must belong to the same video frame. The pointer will be advanced by the number of successfully converted structures. On failure it will point at the offending vbi_sliced structure.
sliced_left *sliced_left must contain the number of vbi_sliced structures in the sliced array. It will be decremented by the number of successfully converted structures.
service_mask Only data services in this set will be encoded. Other data services in the sliced array will be discarded without further checks. Create a set by ORing VBI_SLICED_ values.
raw Shall point at a raw VBI frame of (sp->count[0] + sp->count[1]) lines times sp->bytes_per_line. The function encodes only those lines which have been selected by vbi_sliced structures in the sliced array with id VBI_SLICED_VBI_625. The data field of these structures is ignored. When the sliced array does not contain such structures raw can be NULL.
sp Describes the data in the raw buffer. When raw is NULL, sp can be NULL too. Otherwise all fields must be valid, with the following additional constraints:
  • .videostd_set must contain one or more bits from the VBI_VIDEOSTD_SET_625_50. In libzvbi 0.2.x .scanning must be 625.
  • .sampling_format must be VBI_PIXFMT_Y8 or VBI_PIXFMT_YUV420. Chrominance samples are ignored.
  • .sampling_rate must be 13500000.
  • .offset must be >= 132, and the value must not change until all samples have been encoded.
  • .samples_per_line (.bytes_per_line in libzvbi 0.2.x) must be >= 1, and the value must not change until all samples have been encoded.
  • .offset + .samples_per_line must be <= 132 + 720.
  • .synchronous must be TRUE.
pts This Presentation Time Stamp will be encoded into the PES packet. Bits 33 ... 63 are discarded.
This function converts raw and/or sliced VBI data to one DVB VBI PES packet or one or more TS packets as defined in EN 300 472 and EN 301 775, and stores them in the output buffer.

If the returned *buffer_left value is zero and the returned *sliced_left value is greater than zero another call will be necessary to convert the remaining data.

After a vbi_dvb_mux_reset() call the vbi_dvb_mux_cor() function will encode a new PES packet, discarding any data of the previous packet which has not been consumed by the application.

Returns:
FALSE on failure:
  • *buffer is NULL or *buffer_left is zero.
  • *sliced in NULL or *sliced_left is zero.
  • The maximum PES packet size, or the value selected with vbi_dvb_mux_set_pes_packet_size(), is too small to contain all the sliced and raw VBI data.
  • The sliced array is not sorted by ascending line number, except for elements with line number 0 (undefined).
  • Only the following data services can be encoded:
    • VBI_SLICED_TELETEXT_B on lines 7 to 22 and 320 to 335 inclusive, or with line number 0 (undefined). All Teletext lines will be encoded with data_unit_id 0x02 ("EBU Teletext non-subtitle data").
    • VBI_SLICED_VPS on line 16.
    • VBI_SLICED_CAPTION_625 on line 22.
    • VBI_SLICED_WSS_625 on line 23.
    • Raw VBI data with id VBI_SLICED_VBI_625 can be encoded on lines 7 to 23 and 320 to 336 inclusive. Note for compliance with the Teletext buffer model defined in EN 300 472, EN 301 775 recommends to encode at most one raw and one sliced, or two raw VBI lines per frame.
  • A vbi_sliced structure contains a line number outside the valid range specified above.
  • raw is NULL although the *sliced array contains a structure with id VBI_SLICED_VBI_625.
  • sp is NULL although the *sliced array contains a structure with id VBI_SLICED_VBI_625.
  • One or more fields of the sp structure are invalid.
  • A vbi_sliced structure with id VBI_SLICED_VBI_625 contains a line number outside the ranges defined by sp->start[] and sp->count[] (i.e. the line is not in the raw buffer).
On all errors *sliced will point at the offending vbi_sliced structure and the output buffer remains unchanged.

Since:
0.2.26

vbi_bool vbi_dvb_mux_feed vbi_dvb_mux mx,
const vbi_sliced sliced,
unsigned int  sliced_lines,
vbi_service_set  service_mask,
const uint8_t *  raw,
const vbi_sampling_par *  sp,
int64_t  pts
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
sliced Pointer to the sliced VBI data to be converted. All data must belong to the same video frame.
sliced_lines The number of vbi_sliced structures in the sliced array.
service_mask Only data services in this set will be encoded. Other data services in the sliced array will be discarded without further checks. Create a set by ORing VBI_SLICED_ values.
raw Shall point at a raw VBI frame of (sp->count[0] + sp->count[1]) lines times sp->bytes_per_line. The function encodes only those lines which have been selected by vbi_sliced structures in the sliced array with id VBI_SLICED_VBI_625. The data field of these structures is ignored. When the sliced array does not contain such structures raw can be NULL.
sp Describes the data in the raw buffer. When raw is NULL, sp can be NULL too. Otherwise all fields must be valid, with the following additional constraints:
  • .videostd_set must contain one or more bits from the VBI_VIDEOSTD_SET_625_50. In libzvbi 0.2.x .scanning must be 625.
  • .sampling_format must be VBI_PIXFMT_Y8 or VBI_PIXFMT_YUV420. Chrominance samples are ignored.
  • .sampling_rate must be 13500000.
  • .offset must be >= 132.
  • .samples_per_line (in libzvbi 0.2.x .bytes_per_line) must be >= 1.
  • .offset + .samples_per_line must be <= 132 + 720.
  • .synchronous must be TRUE.
pts This Presentation Time Stamp will be encoded into the PES packet. Bits 33 ... 63 are discarded.
This function converts raw and/or sliced VBI data to one DVB VBI PES packet or one or more TS packets as defined in EN 300 472 and EN 301 775. For output it calls the callback function passed to vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new() once for each PES or TS packet.

Returns:
FALSE on failure.
  • No callback function was selected with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
  • The callback function returned FALSE. Any remaining TS packets which have not been output yet are discarded.
  • The maximum PES packet size, or the value selected with vbi_dvb_mux_set_pes_packet_size(), is too small to contain all the sliced and raw VBI data.
  • The sliced array is not sorted by ascending line number, except for elements with line number 0 (undefined).
  • Only the following data services can be encoded:
    • VBI_SLICED_TELETEXT_B on lines 7 to 22 and 320 to 335 inclusive, or with line number 0 (undefined). All Teletext lines will be encoded with data_unit_id 0x02 ("EBU Teletext non-subtitle data").
    • VBI_SLICED_VPS on line 16.
    • VBI_SLICED_CAPTION_625 on line 22.
    • VBI_SLICED_WSS_625 on line 23.
    • Raw VBI data with id VBI_SLICED_VBI_625 can be encoded on lines 7 to 23 and 320 to 336 inclusive.
  • A vbi_sliced structure contains a line number outside the valid range specified above.
  • raw is NULL although the sliced array contains a structure with id VBI_SLICED_VBI_625.
  • sp is NULL although the sliced array contains a structure with id VBI_SLICED_VBI_625.
  • One or more fields of the sp structure are invalid.
  • A vbi_sliced structure with id VBI_SLICED_VBI_625 contains a line number outside the ranges defined by sp->start[] and sp->count[] (i.e. the line is not in the raw buffer).
The function does not call the callback function on failure.

Since:
0.2.26

unsigned int vbi_dvb_mux_get_data_identifier const vbi_dvb_mux mx  ) 
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
Returns the data_identifier the multiplexer encodes into PES packets.

Since:
0.2.26

vbi_bool vbi_dvb_mux_set_data_identifier vbi_dvb_mux mx,
unsigned int  data_identifier
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
data_identifier The data_identifier byte to be stored in PES packets.
Determines the data_identifier byte to be stored in PES packets. For compatibility with decoders compliant to EN 300 472 this should be a value in the range 0x10 to 0x1F inclusive. The values 0x99 to 0x9B inclusive as defined in EN 301 775 are also permitted.

The default data_identifier is 0x10.

Returns:
FALSE if the data_identifier is outside the valid ranges specified above.
Since:
0.2.26

unsigned int vbi_dvb_mux_get_min_pes_packet_size vbi_dvb_mux mx  ) 
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
Returns the maximum size of PES packets the multiplexer generates.

Since:
0.2.26

unsigned int vbi_dvb_mux_get_max_pes_packet_size vbi_dvb_mux mx  ) 
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
Returns the minimum size of PES packets the multiplexer generates.

Since:
0.2.26

vbi_bool vbi_dvb_mux_set_pes_packet_size vbi_dvb_mux mx,
unsigned int  min_size,
unsigned int  max_size
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new().
min_size Minimum PES packet size.
max_size Maximum PES packet size.
Determines the minimum and maximum total size of PES packets generated by the multiplexer, including all header bytes. When the data to be stored in a packet is smaller than the minimum size, the multiplexer will fill the packet up with stuffing bytes. When the data is larger than the maximum size the vbi_dvb_mux_feed() and vbi_dvb_mux_cor() functions will fail.

The PES packet size must be a multiple of 184 bytes, in the range 184 to 65504 bytes inclusive, and this function will round min_size up and max_size down accordingly. If after rounding the maximum size is lower than the minimum, it will be set to the same value as the minimum size.

The default minimum size is 184, the default maximum 65504 bytes. For compatibility with decoders compliant to the Teletext buffer model defined in EN 300 472 the maximum should not exceed 1472 bytes.

Returns:
FALSE on failure (out of memory).
Since:
0.2.26

void vbi_dvb_mux_delete vbi_dvb_mux mx  ) 
 

Parameters:
mx DVB VBI multiplexer context allocated with vbi_dvb_pes_mux_new() or vbi_dvb_ts_mux_new(). Can be NULL.
Frees all resources associated with mx.

Since:
0.2.26

vbi_dvb_mux* vbi_dvb_pes_mux_new vbi_dvb_mux_cb *  callback,
void *  user_data
 

Parameters:
callback Function to be called by vbi_dvb_mux_feed() when a new packet is available. Can be NULL if you want to use the vbi_dvb_mux_cor() coroutine instead.
user_data User pointer passed through to the callback function.
Allocates a new DVB VBI multiplexer converting raw and/or sliced VBI data to MPEG-2 Packetized Elementary Stream (PES) packets as defined in the standards EN 300 472 and EN 301 775.

Returns:
Pointer to newly allocated DVB VBI multiplexer context, which must be freed with vbi_dvb_mux_delete() when done. NULL on failure (out of memory).
Since:
0.2.26

vbi_dvb_mux* vbi_dvb_ts_mux_new unsigned int  pid,
vbi_dvb_mux_cb *  callback,
void *  user_data
 

Parameters:
pid This Program ID will be stored in the header of the generated TS packets. The pid must be in range 0x0010 to 0x1FFE inclusive.
callback Function to be called by vbi_dvb_mux_feed() when a new packet is available. Can be NULL if you want to use the vbi_dvb_mux_cor() coroutine instead.
user_data User pointer passed through to the callback function.
Allocates a new DVB VBI multiplexer converting raw and/or sliced VBI data to MPEG-2 Transport Stream (TS) packets as defined in the standards EN 300 472 and EN 301 775.

Returns:
Pointer to newly allocated DVB VBI multiplexer context, which must be freed with vbi_dvb_mux_delete() when done. NULL on failure (out of memory or invalid pid).
Since:
0.2.26


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