Main Page   Modules   Data Structures   Data Fields   Related Pages   Examples  

VBI capture device interface

Platform independent interface to VBI capture device drivers. More...

Data Structures

struct  vbi_capture_buffer

Typedefs

typedef struct vbi_capture_buffer  vbi_capture_buffer
typedef struct vbi_capture vbi_capture
 Opaque device interface handle.


Enumerations

enum  VBI_CAPTURE_FD_FLAGS {
  VBI_FD_HAS_SELECT = 1<<0,
  VBI_FD_HAS_MMAP = 1<<1,
  VBI_FD_IS_DEVICE = 1<<2
}
 Properties of capture file handle. More...


Functions

vbi_capturevbi_capture_v4l2_new (const char *dev_name, int buffers, unsigned int *services, int strict, char **errorstr, vbi_bool trace)
vbi_capturevbi_capture_v4l2k_new (const char *dev_name, int fd, int buffers, unsigned int *services, int strict, char **errorstr, vbi_bool trace)
vbi_capturevbi_capture_v4l_new (const char *dev_name, int scanning, unsigned int *services, int strict, char **errorstr, vbi_bool trace)
vbi_capturevbi_capture_v4l_sidecar_new (const char *dev_name, int given_fd, unsigned int *services, int strict, char **errorstr, vbi_bool trace)
vbi_capturevbi_capture_bktr_new (const char *dev_name, int scanning, unsigned int *services, int strict, char **errstr, vbi_bool trace)
int vbi_capture_dvb_filter (vbi_capture *cap, int pid)
vbi_capturevbi_capture_dvb_new (char *dev, int scanning, unsigned int *services, int strict, char **errstr, vbi_bool trace)
int64_t vbi_capture_dvb_last_pts (const vbi_capture *cap)
vbi_capturevbi_capture_dvb_new2 (const char *device_name, unsigned int pid, char **errstr, vbi_bool trace)
vbi_capturevbi_capture_proxy_new (struct vbi_proxy_client *vpc, int buffers, int scanning, unsigned int *p_services, int strict, char **pp_errorstr)
int vbi_capture_read_raw (vbi_capture *capture, void *data, double *timestamp, struct timeval *timeout)
int vbi_capture_read_sliced (vbi_capture *capture, vbi_sliced *data, int *lines, double *timestamp, struct timeval *timeout)
int vbi_capture_read (vbi_capture *capture, void *raw_data, vbi_sliced *sliced_data, int *lines, double *timestamp, struct timeval *timeout)
int vbi_capture_pull_raw (vbi_capture *capture, vbi_capture_buffer **buffer, struct timeval *timeout)
int vbi_capture_pull_sliced (vbi_capture *capture, vbi_capture_buffer **buffer, struct timeval *timeout)
int vbi_capture_pull (vbi_capture *capture, vbi_capture_buffer **raw_buffer, vbi_capture_buffer **sliced_buffer, struct timeval *timeout)
vbi_raw_decodervbi_capture_parameters (vbi_capture *capture)
int vbi_capture_fd (vbi_capture *capture)
unsigned int vbi_capture_update_services (vbi_capture *capture, vbi_bool reset, vbi_bool commit, unsigned int services, int strict, char **errorstr)
int vbi_capture_get_scanning (vbi_capture *capture)
 Queries the capture device for the current norm. More...

void vbi_capture_flush (vbi_capture *capture)
void vbi_capture_delete (vbi_capture *capture)
vbi_bool vbi_capture_set_video_path (vbi_capture *capture, const char *p_dev_video)
 Set path to video device for TV norm queries. More...

VBI_CAPTURE_FD_FLAGS vbi_capture_get_fd_flags (vbi_capture *capture)
 Query properties of the capture device file handle. More...


Detailed Description

Platform independent interface to VBI capture device drivers.


Enumeration Type Documentation

enum VBI_CAPTURE_FD_FLAGS
 

Properties of capture file handle.

Enumeration values:
VBI_FD_HAS_SELECT   Is set when select(2) can be used to wait for new data on the capture device file handle.
VBI_FD_HAS_MMAP   Is set when the capture device supports "user-space DMA". In this case it's more efficient to use one of the "pull" functions to read raw data because otherwise the data has to be copied once more into the passed buffer.
VBI_FD_IS_DEVICE   Is not set when the capture device file handle is not the actual device. In this case it can only be used for select(2) and not for ioctl(2)


Function Documentation

vbi_capture* vbi_capture_v4l2_new ( const char * dev_name,
int buffers,
unsigned int * services,
int strict,
char ** errorstr,
vbi_bool trace )
 

Parameters:
dev_name   Name of the device to open, usually one of /dev/vbi or /dev/vbi0 and up.
buffers   Number of device buffers for raw vbi data, when the driver supports streaming. Otherwise one bounce buffer is allocated for vbi_capture_pull().
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both. If this parameter is NULL, no services will be installed. You can do so later with vbi_capture_update_services(); note the reset parameter must be set to TRUE in this case.
strict   Will be passed to vbi_raw_decoder_add().
errstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress messages on stderr.

Note: Starting with libzvbi 0.2.9 the V4L2 0.20 API is no longer supported. The function still recognizes V4L2 0.20 drivers for debugging purposes and supports Linux 2.6 V4L2 drivers.

Returns:
Initialized vbi_capture context, NULL on failure.

vbi_capture* vbi_capture_v4l2k_new ( const char * dev_name,
int fd,
int buffers,
unsigned int * services,
int strict,
char ** errorstr,
vbi_bool trace )
 

Parameters:
dev_name   Name of the device to open, usually one of /dev/vbi or /dev/vbi0 and up.
fd   File handle of VBI device if already opened by caller, else value -1.
buffers   Number of device buffers for raw vbi data, when the driver supports streaming. Otherwise one bounce buffer is allocated for vbi_capture_pull().
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both. If this parameter is NULL, no services will be installed. You can do so later with vbi_capture_update_services(); note the reset parameter must be set to TRUE in this case.
strict   Will be passed to vbi_raw_decoder_add().
errstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress messages on stderr.

Returns:
Initialized vbi_capture context, NULL on failure.

vbi_capture* vbi_capture_v4l_new ( const char * dev_name,
int scanning,
unsigned int * services,
int strict,
char ** errorstr,
vbi_bool trace )
 

Parameters:
dev_name   Name of the device to open, usually one of /dev/vbi or /dev/vbi0 and up.
scanning   Can be used to specify the current TV norm for old drivers which don't support ioctls to query the current norm. Value is 625 (PAL/SECAM family) or 525 (NTSC family). Set to 0 if you don't know the norm.
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both. If this parameter is NULL, no services will be installed. You can do so later with vbi_capture_update_services(); note the reset parameter must be set to TRUE in this case.
strict   Will be passed to vbi_raw_decoder_add().
errstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress messages on stderr.

Returns:
Initialized vbi_capture context, NULL on failure.

vbi_capture* vbi_capture_v4l_sidecar_new ( const char * dev_name,
int given_fd,
unsigned int * services,
int strict,
char ** errorstr,
vbi_bool trace )
 

Parameters:
dev_name   Name of the device to open, usually one of /dev/vbi or /dev/vbi0 and up.
given_fd   File handle of an already open video device, usually one of /dev/video or /dev/video0 and up. Must be assorted with the named vbi device, i.e. refer to the same driver instance and hardware.
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both. If this parameter is NULL, no services will be installed. You can do so later with vbi_capture_update_services(); note the reset parameter must be set to TRUE in this case.
strict   Will be passed to vbi_raw_decoder_add().
errstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress messages on stderr.

This functions behaves much like vbi_capture_v4l_new, with the sole difference that it uses the given file handle to determine the current video standard if such queries aren't supported by the VBI device.

Returns:
Initialized vbi_capture context, NULL on failure.

vbi_capture* vbi_capture_bktr_new ( const char * dev_name,
int scanning,
unsigned int * services,
int strict,
char ** errstr,
vbi_bool trace )
 

Parameters:
dev_name   Name of the device to open.
scanning   The current video standard. Value is 625 (PAL/SECAM family) or 525 (NTSC family).
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both.
strict   Will be passed to vbi_raw_decoder_add().
errstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress messages on stderr.

Bug:
You must enable continuous video capturing to read VBI data from the bktr driver, using an RGB video format, and the VBI device must be opened before video capturing starts (METEORCAPTUR).

Returns:
Initialized vbi_capture context, NULL on failure.

int vbi_capture_dvb_filter ( vbi_capture * cap,
int pid )
 

Parameters:
cap   Initialized DVB vbi_capture context.
pid   Filter out a stream with this PID.

Programs the DVB device transport stream demultiplexer to filter out PES packets with this PID.

Returns:
-1 on failure, 0 on success.

vbi_capture* vbi_capture_dvb_new ( char * dev,
int scanning,
unsigned int * services,
int strict,
char ** errstr,
vbi_bool trace )
 

Parameters:
dev   Name of the DVB device to open.
scanning   Ignored.
services   Ignored.
strict   Ignored.
errstr   If not NULL the function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress and warning messages on stderr.

Deprecated:
This function is deprecated. Use vbi_capture_dvb_new2() instead.

Initializes a vbi_capture context reading from a Linux DVB device. You must call vbi_capture_dvb_filter() before you can read.

Returns:
Initialized vbi_capture context, NULL on failure.

Bug:
This function ignores the scanning, services and strict parameter. The read method of this DVB capture context returns -1 on timeout instead of 0. It returns 0 when a single read() does not complete a frame, regardless if the timeout expired. (Decoding resumes with the next call.) Older versions pass select or read EINTR errors back to the caller. They may return partial frames when VBI data of one frame is distributed across multiple PES packets. They will not return VPS, CC, or WSS data and can malfunction or segfault given unusual PES streams. On error and select timeout older versions invariably print a warning on stderr.

int64_t vbi_capture_dvb_last_pts ( const vbi_capture * cap )
 

Parameters:
cap   Initialized DVB vbi_capture context.

Returns the presentation time stamp associated with the data last read from the context. The PTS refers to the first sliced VBI line, not the last packet containing data of that frame.

Note timestamps returned by vbi_capture read functions contain the sampling time of the data, that is the time at which the packet containing the first sliced line arrived.

Returns:
Presentation time stamp (33 bits).

Bug:
PTS' should be part of the generic I/O interface.

Since:
0.2.13

vbi_capture* vbi_capture_dvb_new2 ( const char * device_name,
unsigned int pid,
char ** errstr,
vbi_bool trace )
 

Parameters:
device_name   Name of the DVB device to open.
pid   Filter out a stream with this PID. You can pass 0 here and set or change the PID later with vbi_capture_dvb_filter().
errstr   If not NULL the function stores a pointer to an error description here. You must free() this string when no longer needed.
trace   If TRUE print progress and warning messages on stderr.

Initializes a vbi_capture context reading from a Linux DVB device.

Returns:
Initialized vbi_capture context, NULL on failure.

Since:
0.2.13

vbi_capture * vbi_capture_proxy_new ( struct vbi_proxy_client * p_proxy_client,
int buffers,
int scanning,
unsigned int * p_services,
int strict,
char ** pp_errorstr )
 

Parameters:
p_proxy_client   Reference to an initialized proxy client context.
buffers   Number of device buffers for raw vbi data. The same number of buffers is allocated to cache sliced data in the proxy daemon.
scanning   This indicates the current norm: 625 for PAL and 525 for NTSC; set to 0 if you don't know (you should not attempt to query the device for the norm, as this parameter is only required for v4l1 drivers which don't support video standard query ioctls)
p_services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both.
strict   Will be passed to vbi_raw_decoder_add().
pp_errorstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.

Open a new connection to a VBI proxy to open a VBI device for the given services. On side of the proxy one of the regular v4l_new() functions is invoked and if it succeeds, data slicing is started and all captured data forwarded transparently.

Whenever possible the proxy should be used instead of opening the device directly, since it allows the user to start multiple VBI clients in parallel. When this function fails (usually because the user hasn't started the proxy daemon) applications should automatically fall back to opening the device directly.

Returns:
Initialized vbi_capture context, NULL on failure.

Since:
0.2.9

int vbi_capture_read_raw ( vbi_capture * capture,
void * data,
double * timestamp,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi_capture context.
data   Store the raw vbi data here. Use vbi_capture_parameters() to determine the buffer size.
timestamp   On success the capture instant in seconds and fractions since 1970-01-01 00:00 of the video frame will be stored here.
timeout   Wait timeout, will be read only.

Read a raw vbi frame from the capture device.

Returns:
-1 on error, examine errno for details. The function also fails if vbi data is not available in raw format. 0 on timeout, 1 on success.

int vbi_capture_read_sliced ( vbi_capture * capture,
vbi_sliced * data,
int * lines,
double * timestamp,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi capture context.
data   Stores the sliced vbi data here. Use vbi_capture_parameters() to determine the buffer size.
lines   Stores number of vbi lines decoded and stored in data, which can be zero, here.
timestamp   On success the capture instant in seconds and fractions since 1970-01-01 00:00 will be stored here.
timeout   Wait timeout, will be read only.

Read a sliced vbi frame, that is an array of vbi_sliced structures, from the capture device.

Note: it's generally more efficient to use vbi_capture_pull_sliced() instead, as that one may avoid having to copy sliced data into the given buffer (e.g. for the VBI proxy)

Returns:
-1 on error, examine errno for details. 0 on timeout, 1 on success.

int vbi_capture_read ( vbi_capture * capture,
void * raw_data,
vbi_sliced * sliced_data,
int * lines,
double * timestamp,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi capture context.
raw_data   Stores the raw vbi data here. Use vbi_capture_parameters() to determine the buffer size.
sliced_data   Stores the sliced vbi data here. Use vbi_capture_parameters() to determine the buffer size.
lines   Stores number of vbi lines decoded and stored in data, which can be zero, here.
timestamp   On success the capture instant in seconds and fractions since 1970-01-01 00:00 will be stored here.
timeout   Wait timeout, will be read only.

Read a raw vbi frame from the capture device, decode to sliced data and also read the sliced vbi frame, that is an array of vbi_sliced structures, from the capture device.

Note: depending on the driver, captured raw data may have to be copied from the capture buffer into the given buffer (e.g. for v4l2 streams which use memory mapped buffers.) It's generally more efficient to use one of the vbi_capture_pull() interfaces, especially if you don't require access to raw data at all.

Returns:
-1 on error, examine errno for details. The function also fails if vbi data is not available in raw format. 0 on timeout, 1 on success.

int vbi_capture_pull_raw ( vbi_capture * capture,
vbi_capture_buffer ** buffer,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi capture context.
buffer   Store pointer to a vbi_capture_buffer here.
timeout   Wait timeout, will be read only.

Read a raw vbi frame from the capture device, returning a pointer to the image in buffer->data, which has buffer->size. The data remains valid until the next vbi_capture_pull_raw() call and must be read only.

Returns:
-1 on error, examine errno for details. The function also fails if vbi data is not available in raw format. 0 on timeout, 1 on success.

int vbi_capture_pull_sliced ( vbi_capture * capture,
vbi_capture_buffer ** buffer,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi capture context.
buffer   Store pointer to a vbi_capture_buffer here.
timeout   Wait timeout, will be read only.

Read a sliced vbi frame, that is an array of vbi_sliced, from the capture device, returning a pointer to the array as buffer->data. buffer->size is the size of the array, that is the number of lines decoded, which can be zero, times the size of structure vbi_sliced. The data remains valid until the next vbi_capture_pull_sliced() call and must be read only.

Returns:
-1 on error, examine errno for details. 0 on timeout, 1 on success.

int vbi_capture_pull ( vbi_capture * capture,
vbi_capture_buffer ** raw_buffer,
vbi_capture_buffer ** sliced_buffer,
struct timeval * timeout )
 

Parameters:
capture   Initialized vbi capture context.
raw_buffer   Store pointer to a vbi_capture_buffer here.
sliced_buffer   Store pointer to a vbi_capture_buffer here.
timeout   Wait timeout, will be read only.

Read a raw vbi frame from the capture device and decode to sliced data. Both raw and sliced data is returned, a pointer to the raw image as raw_buffer->data and a pointer to an array of vbi_sliced as sliced_buffer->data. Note sliced_buffer->size is the size of the array in bytes. That is the number of lines decoded, which can be zero, times the size of the vbi_sliced structure.

The raw and sliced data remains valid until the next vbi_capture_pull() call and must be read only.

Returns:
-1 on error, examine errno for details. The function also fails if vbi data is not available in raw format. 0 on timeout, 1 on success.

vbi_raw_decoder* vbi_capture_parameters ( vbi_capture * capture )
 

Parameters:
capture   Initialized vbi capture context.

Describe the captured data. Raw vbi frames consist of vbi_raw_decoder.count[0] + vbi_raw_decoder.count[1] lines in vbi_raw_decoder.sampling_format, each vbi_raw_decoder.bytes_per_line. Sliced vbi arrays consist of zero to vbi_raw_decoder.count[0] + vbi_raw_decoder.count[1] vbi_sliced structures.

Returns:
Pointer to a vbi_raw_decoder structure, read only.

int vbi_capture_fd ( vbi_capture * capture )
 

Parameters:
capture   Initialized vbi capture context, can be NULL.

Returns:
The file descriptor used to read from the device. If not applicable (e.g. when using the proxy) or the capture context is invalid -1 will be returned.

unsigned int vbi_capture_update_services ( vbi_capture * capture,
vbi_bool reset,
vbi_bool commit,
unsigned int services,
int strict,
char ** errorstr )
 

Parameters:
capture   Initialized vbi capture context.
reset   TRUE to clear all previous services before adding new ones (by invoking vbi_raw_decoder_reset() at the appropriate time.)
commit   TRUE to apply all previously added services to the device; when doing subsequent calls of this function, commit should be set TRUE for the last call. Reading data cannot continue before changes were commited (because capturing has to be suspended to allow resizing the VBI image.) Note this flag is ignored when using the VBI proxy.
services   This must point to a set of VBI_SLICED_ symbols describing the data services to be decoded. On return the services actually decodable will be stored here. See vbi_raw_decoder_add() for details. If you want to capture raw data only, set to VBI_SLICED_VBI_525, VBI_SLICED_VBI_625 or both.
strict   Will be passed to vbi_raw_decoder_add().
errorstr   If not NULL this function stores a pointer to an error description here. You must free() this string when no longer needed.

Add and/or remove one or more services to an already initialized capture context. Can be used to dynamically change the set of active services. Internally the function will restart parameter negotiation with the VBI device driver and then call vbi_raw_decoder_add_services(). You may call vbi_raw_decoder_reset() before using this function to rebuild your service mask from scratch. Note that the number of VBI lines may change with this call (even if a negative result is returned) so you have to check the size of your buffers.

Returns:
Bitmask of supported services among those requested (not including previously added services), 0 upon errors.

int vbi_capture_get_scanning ( vbi_capture * capture )
 

Queries the capture device for the current norm.

Parameters:
capture   Initialized vbi capture context.

This function is intended to allow the application to check for asynchronous norm changes, i.e. by a different application using the same device.

Returns:
Value 625 for PAL/SECAM norms, 525 for NTSC; 0 if unknown, -1 on error.

void vbi_capture_flush ( vbi_capture * capture )
 

Parameters:
capture   Initialized vbi capture context.

After a channel change this function should be used to discard all VBI data in intermediate buffers which may still originate from the previous channel.

void vbi_capture_delete ( vbi_capture * capture )
 

Parameters:
capture   Initialized vbi capture context, can be NULL.

Free all resources associated with the capture context.

vbi_bool vbi_capture_set_video_path ( vbi_capture * capture,
const char * p_dev_video )
 

Set path to video device for TV norm queries.

Parameters:
capture   Initialized vbi capture context.
p_dev_video   Path to a video device (e.g. /dev/video) which refers to the same hardware as the VBI device which is used for capturing. Note: only useful for old video4linux drivers which don't support norm queries through VBI devices.

Returns:
Returns TRUE if the configuration option and parameters are supported; else FALSE.

VBI_CAPTURE_FD_FLAGS vbi_capture_get_fd_flags ( vbi_capture * capture )
 

Query properties of the capture device file handle.

Parameters:
capture   Initialized vbi capture context.


Generated at Sun May 28 21:44:35 2006 for ZVBI Library by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001