Raw vbi decoder

Name

Raw vbi decoder -- Converting raw vbi samples into bits and bytes.

Synopsis




enum        vbi_pixfmt;
#define     VBI_PIXFMT_ARGB32_LE
#define     VBI_PIXFMT_ABGR32_LE
#define     VBI_PIXFMT_ABGR32_BE
#define     VBI_PIXFMT_ARGB32_BE
enum        vbi_modulation;
typedef     vbi_bit_slicer;
void        vbi_bit_slicer_init             (vbi_bit_slicer *slicer,
                                             int raw_samples,
                                             int sampling_rate,
                                             int cri_rate,
                                             int bit_rate,
                                             unsigned int cri_frc,
                                             unsigned int cri_mask,
                                             int cri_bits,
                                             int frc_bits,
                                             int payload,
                                             vbi_modulation modulation,
                                             vbi_pixfmt fmt);
vbi_bool    vbi_bit_slice                   (vbi_bit_slicer *slicer,
                                             uint8_t *raw,
                                             uint8_t *buf);

typedef     vbi_raw_decoder;
void        vbi_raw_decoder_init            (vbi_raw_decoder *rd);
void        vbi_raw_decoder_destroy         (vbi_raw_decoder *rd);
unsigned int vbi_raw_decoder_parameters     (vbi_raw_decoder *rd,
                                             unsigned int services,
                                             int scanning,
                                             int *max_rate);
unsigned int vbi_raw_decoder_add_services   (vbi_raw_decoder *rd,
                                             unsigned int services,
                                             int strict);
unsigned int vbi_raw_decoder_remove_services
                                            (vbi_raw_decoder *rd,
                                             unsigned int services);
void        vbi_raw_decoder_reset           (vbi_raw_decoder *rd);
int         vbi_raw_decode                  (vbi_raw_decoder *rd,
                                             uint8_t *raw,
                                             vbi_sliced *out);

Description

The libvbi already offers hardware interfaces to obtain sliced vbi data for further processing. However if you want to write your own interface or decode data services not covered by libvbi you will welcome these functions.

Details

enum vbi_pixfmt

typedef enum {
  VBI_PIXFMT_YUV420 = 1,
  VBI_PIXFMT_YUYV,
  VBI_PIXFMT_YVYU,
  VBI_PIXFMT_UYVY,
  VBI_PIXFMT_VYUY,
  VBI_PIXFMT_RGBA32_LE = 32,
  VBI_PIXFMT_RGBA32_BE,
  VBI_PIXFMT_BGRA32_LE,
  VBI_PIXFMT_BGRA32_BE,
  VBI_PIXFMT_RGB24,
  VBI_PIXFMT_BGR24,
  VBI_PIXFMT_RGB16_LE,
  VBI_PIXFMT_RGB16_BE,
  VBI_PIXFMT_BGR16_LE,
  VBI_PIXFMT_BGR16_BE,
  VBI_PIXFMT_RGBA15_LE,
  VBI_PIXFMT_RGBA15_BE,
  VBI_PIXFMT_BGRA15_LE,
  VBI_PIXFMT_BGRA15_BE,
  VBI_PIXFMT_ARGB15_LE,
  VBI_PIXFMT_ARGB15_BE,
  VBI_PIXFMT_ABGR15_LE,
  VBI_PIXFMT_ABGR15_BE
} vbi_pixfmt;

Raw vbi data sample format, this enumeration corresponds to librte rte_pixfmt.

Table 1. Sample formats

SymbolByte 0Byte 1Byte 2Byte 3
Planar YUV 4:2:0 data. Only the luminance bytes are evaluated. This is the format in which raw vbi data is usually captured by hardware.
VBI_PIXFMT_YUV420Y0Y1Y2Y3
Packed YUV 4:2:2 data. Only the luminance bytes are evaluated.
VBI_PIXFMT_YUYVY0CbY1Cr
VBI_PIXFMT_YVYUY0CrY1Cb
VBI_PIXFMT_UYVYCbY0CrY1
VBI_PIXFMT_VYUYCrY0CbY1
Packed 32 bit RGB data. Only the g bits are evaluated.
VBI_PIXFMT_RGBA32_LE VBI_PIXFMT_ARGB32_BEr7 ... r0g7 ... g0b7 ... b0a7 ... a0
VBI_PIXFMT_BGRA32_LE VBI_PIXFMT_ARGB32_BEb7 ... b0g7 ... g0r7 ... r0a7 ... a0
VBI_PIXFMT_ARGB32_LE VBI_PIXFMT_BGRA32_BEa7 ... a0r7 ... r0g7 ... g0b7 ... b0
VBI_PIXFMT_ABGR32_LE VBI_PIXFMT_RGBA32_BEa7 ... a0b7 ... b0g7 ... g0r7 ... r0
Packed 24 bit RGB data. Only the g bits are evaluated.
VBI_PIXFMT_RGBA24r7 ... r0g7 ... g0b7 ... b0 
VBI_PIXFMT_BGRA24b7 ... b0g7 ... g0r7 ... r0 
Packed 16 bit RGB data. Only the g bits are evaluated.
VBI_PIXFMT_RGB16_LEg2 g1 g0 r4 r3 r2 r1 r0b4 b3 b2 b1 b0 g5 g4 g3  
VBI_PIXFMT_BGR16_LEg2 g1 g0 b4 b3 b2 b1 b0r4 r3 r2 r1 r0 g5 g4 g3  
VBI_PIXFMT_RGB16_BEb4 b3 b2 b1 b0 g5 g4 g3g2 g1 g0 r4 r3 r2 r1 r0  
VBI_PIXFMT_BGR16_BEr4 r3 r2 r1 r0 g5 g4 g3g2 g1 g0 b4 b3 b2 b1 b0  
Packed 15 bit RGB data. Only the g bits are evaluated.
VBI_PIXFMT_RGBA15_LEg2 g1 g0 r4 r3 r2 r1 r0a0 b4 b3 b2 b1 b0 g4 g3  
VBI_PIXFMT_BGRA15_LEg2 g1 g0 b4 b3 b2 b1 b0a0 r4 r3 r2 r1 r0 g4 g3  
VBI_PIXFMT_ARGB15_LEg1 g0 r4 r3 r2 r1 r0 a0b4 b3 b2 b1 b0 g4 g3 g2  
VBI_PIXFMT_ABGR15_LEg1 g0 b4 b3 b2 b1 b0 a0r4 r3 r2 r1 r0 g4 g3 g2  
VBI_PIXFMT_RGBA15_BEa0 b4 b3 b2 b1 b0 g4 g3g2 g1 g0 r4 r3 r2 r1 r0  
VBI_PIXFMT_BGRA15_BEa0 r4 r3 r2 r1 r0 g4 g3g2 g1 g0 b4 b3 b2 b1 b0  
VBI_PIXFMT_ARGB15_BEb4 b3 b2 b1 b0 g4 g3 g2g1 g0 r4 r3 r2 r1 r0 a0  
VBI_PIXFMT_ABGR15_BEr4 r3 r2 r1 r0 g4 g3 g2g1 g0 b4 b3 b2 b1 b0 a0  


VBI_PIXFMT_ARGB32_LE

#define VBI_PIXFMT_ARGB32_LE VBI_PIXFMT_BGRA32_BE


VBI_PIXFMT_ABGR32_LE

#define VBI_PIXFMT_ABGR32_LE VBI_PIXFMT_RGBA32_BE


VBI_PIXFMT_ABGR32_BE

#define VBI_PIXFMT_ABGR32_BE VBI_PIXFMT_RGBA32_LE


VBI_PIXFMT_ARGB32_BE

#define VBI_PIXFMT_ARGB32_BE VBI_PIXFMT_BGRA32_LE


enum vbi_modulation

typedef enum {
	VBI_MODULATION_NRZ_LSB,
	VBI_MODULATION_NRZ_MSB,
	VBI_MODULATION_BIPHASE_LSB,
	VBI_MODULATION_BIPHASE_MSB
} vbi_modulation;

Modulation of the vbi data.


vbi_bit_slicer

typedef struct vbi_bit_slicer {
	/*< private >*/
	vbi_bool	(* func)(struct vbi_bit_slicer *slicer,
				 uint8_t *raw, uint8_t *buf);
	unsigned int	cri;
	unsigned int	cri_mask;
	int		thresh;
	int		cri_bytes;
	int		cri_rate;
	int		oversampling_rate;
	int		phase_shift;
	int		step;
	unsigned int	frc;
	int		frc_bits;
	int		payload;
	int		endian;
	int		skip;
} vbi_bit_slicer;

Bit slicer context. The contents of the vbi_bit_slicer structure are private, use vbi_bit_slicer_init() to initialize.


vbi_bit_slicer_init ()

void        vbi_bit_slicer_init             (vbi_bit_slicer *slicer,
                                             int raw_samples,
                                             int sampling_rate,
                                             int cri_rate,
                                             int bit_rate,
                                             unsigned int cri_frc,
                                             unsigned int cri_mask,
                                             int cri_bits,
                                             int frc_bits,
                                             int payload,
                                             vbi_modulation modulation,
                                             vbi_pixfmt fmt);

Initializes vbi_bit_slicer object. Usually you will not use this function, but the raw vbi decoder which handles all these details.

slicer : Pointer to vbi_bit_slicer object to be initialized.
raw_samples : Number of samples or pixels in one raw vbi line later passed to vbi_bit_slice(). This sets a scan limit.
sampling_rate : Raw vbi sampling rate in Hz, that is the number of samples or pixels sampled per second by the hardware.
cri_rate : The Clock Run In is a NRZ modulated sequence of '0' and '1' bits prepending most data transmissions to synchronize data acquisition circuits. This parameter gives the CRI bit rate in Hz, that is the number of CRI bits transmitted per second.
bit_rate : The transmission bit rate of all data bits following the CRI in Hz.
cri_frc : The FRaming Code usually following the CRI is a bit sequence identifying the data service, and per libzvbi definition modulated and transmitted at the same bit rate as the payload (however nothing stops you from counting all nominal CRI and FRC bits as CRI). The bit slicer compares the bits in this word, lsb last transmitted, against the transmitted CRI and FRC. Decoding of payload starts with the next bit after a match.
cri_mask : Of the CRI bits in cri_frc, only these bits are actually significant for a match. For instance it is wise not to rely on the very first CRI bits transmitted. Note this mask is not shifted left by frc_bits.
cri_bits : 
frc_bits : Number of CRI and FRC bits in cri_frc, respectively. Their sum is limited to 32.
payload : Number of payload bits. Only this data will be stored in the vbi_bit_slice() output. If this number is no multiple of eight, the most significant bits of the last byte are undefined.
modulation : Modulation of the vbi data, see vbi_modulation.
fmt : Format of the raw data, see vbi_pixfmt.


vbi_bit_slice ()

vbi_bool    vbi_bit_slice                   (vbi_bit_slicer *slicer,
                                             uint8_t *raw,
                                             uint8_t *buf);

Decode one scan line of raw vbi data. Note the bit slicer tries to adapt to the average signal amplitude, you should avoid using the same vbi_bit_slicer object for data from different devices.

This is one of the few not reentrant libzvbi functions. When you want to share one vbi_bit_slicer object between multiple threads you must implement your own locking mechanism.


vbi_raw_decoder

typedef struct vbi_raw_decoder {
	/*< public >*/

	/* Sampling parameters */

	int			scanning;
	vbi_pixfmt		sampling_format;
	int			sampling_rate;		/* Hz */
	int			bytes_per_line;
	int			offset;			/* 0H, samples */
	int			start[2];		/* ITU-R numbering */
	int			count[2];		/* field lines */
	vbi_bool		interlaced;
	vbi_bool		synchronous;

	/*< private >*/

	pthread_mutex_t		mutex;

	unsigned int		services;
	int			num_jobs;

	int8_t *		pattern;
	struct _vbi_raw_decoder_job {
		unsigned int		id;
		int			offset;
		vbi_bit_slicer		slicer;
	}			jobs[8];
} vbi_raw_decoder;

Raw vbi decoder object. Only the sampling parameters are public, see vbi_raw_decoder_parameters() and vbi_raw_decoder_add_services() for usage instructions.

scanning: Either 525 (NTSC) or 625 (PAL, SECAM), describing the scan line system all line numbers refer to.

sampling_format: See vbi_pixfmt.

sampling_rate: Sampling rate in Hz, the number of samples or pixels captured per second.

bytes_per_line: Number of samples or pixels captured per scan line, in bytes. This determines the raw vbi image width and has to be large enough to cover all data transmitted in the line (with headroom).

offset: The distance from 0H (leading edge hsync, half amplitude point) to the first sample/pixel captured, in samples/pixels. This has to be small enough to pick up the data header.

start: First scan line to be captured, first and second field respectively, according to the ITU-R line numbering scheme (see vbi_sliced). Set to zero if the exact line number isn't known.

count: Number of scan lines captured, first and second field respectively. This can be zero if only data from one field is required. The sum count[0] + count[1] determines the raw vbi image height.

interlaced: In the raw vbi image, normally all lines of the second field are supposed to follow all lines of the first field. When this flag is set, the scan lines of first and second field will be interleaved in memory. This implies count[0] and count[1] are equal.

synchronous: Fields must be stored in temporal order, i. e. as the lines have been captured. It is assumed that the first field is also stored first in memory, however if the hardware cannot reliable distinguish fields this flag shall be cleared, which disables decoding of data services depending on the field number.


vbi_raw_decoder_init ()

void        vbi_raw_decoder_init            (vbi_raw_decoder *rd);

Initializes a vbi_raw_decoder structure.


vbi_raw_decoder_destroy ()

void        vbi_raw_decoder_destroy         (vbi_raw_decoder *rd);

Free all resources associated with rd.


vbi_raw_decoder_parameters ()

unsigned int vbi_raw_decoder_parameters     (vbi_raw_decoder *rd,
                                             unsigned int services,
                                             int scanning,
                                             int *max_rate);

Calculate the sampling parameters in rd required to receive and decode the requested data services. rd->sampling_format will be VBI_PIXFMT_YUV420, rd->bytes_per_line set accordingly to a reasonable minimum. This function can be used to initialize hardware prior to calling vbi_raw_decoder_add_service().


vbi_raw_decoder_add_services ()

unsigned int vbi_raw_decoder_add_services   (vbi_raw_decoder *rd,
                                             unsigned int services,
                                             int strict);

After you initialized the sampling parameters in rd (according to the abilities of your raw vbi source), this function adds one or more data services to be decoded. The libzvbi raw vbi decoder can decode up to eight data services in parallel. You can call this function while already decoding, it does not change sampling parameters and you must not change them either after calling this.


vbi_raw_decoder_remove_services ()

unsigned int vbi_raw_decoder_remove_services
                                            (vbi_raw_decoder *rd,
                                             unsigned int services);

Removes one or more data services to be decoded from the vbi_raw_decoder structure. This function can be called at any time and does not touch sampling parameters.


vbi_raw_decoder_reset ()

void        vbi_raw_decoder_reset           (vbi_raw_decoder *rd);

Reset a vbi_raw_decoder structure. This removes all previously added services to be decoded (if any) but does not touch the sampling parameters. You are free to change the sampling parameters after calling this.


vbi_raw_decode ()

int         vbi_raw_decode                  (vbi_raw_decoder *rd,
                                             uint8_t *raw,
                                             vbi_sliced *out);

Decode a raw vbi image, consisting of several scan lines of raw vbi data, into sliced vbi data. The output is sorted by line number.

Note this function attempts to learn which lines carry which data service, or none, to speed up decoding. You should avoid using the same vbi_raw_decoder structure for different sources.