Video for Linux Two - Video Capture API Specification

Bill Dirks - September 9, 2001

Video for Linux Two is a set of APIs and standards for handling video devices on Linux. Video for Linux Two is a replacement for the Video for Linux API that comes with the kernel.

This document is the specification for Video for Linux Two video capture devices.
 
Revisions:
     

 

Multiple Opens per Device

Drivers may support multiple opens on a device. Supporting multiple simultaneous, independent capture operations (separate capture formats) on the same device complicates the specification and is not practical for streaming or frame buffer overlay. This document describes the behavior assuming there is only one open capturing data.

However, capture drivers should support no-I/O (non-capturing) opens on a device concurrent with a (single) capturing open. See the Device document .
 
 

Query Capabilities - VIDIOC_QUERYCAP

This ioctl call is used to obtain the capability information for the device. See the Devices document .

Capture to a frame buffer might not work on every system depending on the capabilities of the graphics card, the graphics mode, the X Windows server, etc.
 
 

Enumerating Supported Image Formats - VIDIOC_ENUM_PIXFMT, VIDIOC_ENUM_FBUFFMT

An application can query the list of supported capture formats or preview frame buffer formats with the VIDIOC_ENUM_PIXFMT or VIDIOC_ENUM_FBUFFMT ioctl respectively. The application fills in the index field of a struct v4l2_fmtdesc, and then passes it to the VIDIOC_ENUM_*FMT ioctl, which fills in the rest of the fields. The application should use index values from 0 on up; the ioctl will return an error when the index goes out of range.

A video overlay device may be independent of any frame buffer format. In that case VIDIOC_ENUM_FBUFFMT should set both the pixelformat and depth fields to zero to indicate that the frame buffer format doesn't matter. A device that does not support video preview should always return an error from VIDIOC_ENUM_FBUFFMT.
 
struct v4l2_fmtdesc
int index   Number of format in the list of supported formats
char description[32]   Description string for this format
__u32 pixelformat   The pixelformat value
__u32 flags   V4L2_FMT_FLAG_COMPRESSED if applicable
__u32 depth   The depth value
__u32 reserved[2]   reserved

 

Capture Image Format - VIDIOC_G_FMT, VIDIOC_S_FMT

Use VIDIOC_S_FMT to set the capture image format. VIDIOC_G_FMT retrieves the current capture format. Both ioctls use a struct v4l2_format to pass the format. See the device document for a description of this structure. The application should set the type field to V4L2_BUF_TYPE_CAPTURE to set the capture image format.

Devices will not be able to support every combination of width and height. Upon a VIDIOC_S_FMT call, the driver will find the width and height compatible with the hardware which are as close as possible to the requested width and height without going over in either dimension. The driver will modify the structure to indicate the granted dimensions, and the resulting size of the image. Applications must make sure they are suitable. It is not considered an error when the dimensions need to be adjusted this way, and the ioctl() call will still return 0 in this case. The driver will also fill in the depth field appropriately for the selected pixel format.

The sizeimage value returned from the driver is the minimum required size of the capture buffer. A capture operation such as read() is allowed to fail if the buffer is smaller than sizeimage since a partial image read may be nonsensical or impractical to implement.

An interlaced image will have "comb" or "feathering" artifacts around moving objects, and an application may wish to prevent the driver from capturing interlaced images. If the V4L2_FMT_FLAG_INTERLACED flag is not set on VIDIOC_S_FMT, then that indicates the driver is not permitted to capture interlaced images. If the flag is set then the driver may (but is not required to) capture interlaced images if the requested vertical resolution is too high for a single field. V4L2_FMT_FLAG_INTERLACED is set on return from VIDIOC_G_FMT only if the driver is actually going to capture interlaced images.

If the application wants to capture both fields, but with the fields in separate buffers alternating, it should set both the V4L2_FMT_FLAG_TOPFIELD and V4L2_FMT_FLAG_BOTFIELD flags, and not set the V4L2_FMT_FLAG_INTERLACED flag. The height should be set to the height of a single field . The sizeimage will be the size of a field image. Once again, this is a request. Upon return the driver will clear the flags if it cannot handle alternating-field capture. The streaming capture mode is required to correctly capture both fields. Calls to read() will return a single field image, and always the same field.
 
 

Compressed Capture Parameters- VIDIOC_G_COMP, VIDIOC_S_COMP

These ioctls set additional capture parameters needed for compressed capture. They both pass the information in a struct v4l2_compression object. The keyframerate field only applies to temporal compression algorithms. The quality factor ranges from 0 to 65535.
 
struct v4l2_compression
int quality   The quality factor
int keyframerate   How often to make a keyframe, in frames
int pframerate   How often to make p-frames
__u32 reserved[5]   reserved for more parameters

 

Reading Captured Images - read()

This capture mode is supported if the V4L2_FLAG_READ flag is set in the struct v4l2_capability. Each call to read() will fill the buffer with a new frame. The driver may fail the read() if the length parameter is less than the required buffer size specified by the VIDIOC_G_FMT ioctl. This is reasonable since each call to read() starts over with a new frame, and a partial frame may be nonsense (e.g. for a compressed image) or impractical or inefficient to implement in the driver.

To get the required buffer size call VIDIOC_G_FMT and look at the sizeimage field. For variable-length compressed formats, each image may be a different size. The sizeimage field will be the upper bound for the image size which is a safe buffer size guaranteed to hold any image. The return value from read() will indicate actual size of each captured image.

Non-blocking read() mode is supported in the usual way. Read() does not work if streaming video capture is active.
 
 

Automatic Preview to a Hardware Frame Buffer - VIDIOC_G_FBUF, VIDIOC_S_FBUF, VIDIOC_G_WIN, VIDIOC_S_WIN, VIDIOC_PREVIEW

This mode is supported if the V4L2_FLAG_PREVIEW flag is set in the struct v4l2_capability. Certain implementation details depend on the hardware and the driver. Read() capture and/or streaming capture may not work simultaneously with frame buffer preview, or it may depend on the capture parameters. When capturing simultaneously with frame buffer preview, frames may be directed away from preview to capture, or one field may be used for preview and the other for capture depending on the capture parameters.

Typically, preview is accomplished by writing data into a frame buffer. VIDIOC_S_FBUF sets the frame buffer parameters. VIDIOC_G_FBUF returns the current parameters. The structure used by these ioctls is a struct v4l2_framebuffer. Ideally the frame buffer would be a YUV 4:2:2 buffer the exact size (or possibly with some line padding) of the capture. It could also be the primary graphics surface, though. When going straight to the primary graphics surface, you must also use VIDIOC_S_WIN to set up the placement of the video window.

Some devices apply the video overlay to the output of the graphics card. In this case the frame buffer is not modified by the video device, and the frame buffer address and format are not needed by the driver. An application can check for this type of device by calling VIDIOC_G_FBUF and examining the flags field. If FBUF_FLAG_EXTERNOVERLAY is set then VIDIOC_S_FBUF is not required.

Note that the fmt field in the v4l2_framebuffer structure only describes the physical layout of the frame buffer which is to receive the preview video frames, and it is not related to and does not affect the format of images captured via the read() call or via the memory-mapped capture buffers. That format is defined by the VIDIOC_S_FMT ioctl.
 
struct v4l2_framebuffer
__u32 capability   Preview capabilities supported
__u32 flags   Frame buffer flags
void *base[3]   Physical base addresses of the frame buffer.
struct v4l2_pix_format fmt   Physical layout of the frame buffer
     
Flags for the struct v4l2_framebufferflags field
V4L2_FBUF_FLAG_PRIMARY   The frame buffer is the primary graphics surface (VIDIOC_S_WIN is required)
V4L2_FBUF_FLAG_OVERLAY   The frame buffer is an overlay surface the same size as the capture
V4L2_FBUF_FLAG_CHROMAKEY   Use chromakey
Flags for the capability field of struct v4l2_framebuffer
V4L2_FBUF_CAP_EXTERNOVERLAY   The video preview is overlayed externally to the graphics card
V4L2_FBUF_CAP_CHROMAKEY   Device supports overlay chromakey
V4L2_FBUF_CAP_CLIPPING   Device supports overlay clipping described by a list of rectangles
V4L2_FBUF_CAP_BITMAP_CLIPPING
Device supports overly clipping area described by a bitmap
V4L2_FBUF_CAP_SCALEUP   The preview window can be scaled up from the capture size
V4L2_FBUF_CAP_SCALEDOWN   The preview window can be scaled down from the capture size

Note that the buffer is often larger than the visible area, and so the fmt.bytesperline field is most likely valid. XFree86 DGA can provide the parameters required to set up this ioctl.

Preview Windows

The preview window is described by a struct v4l2_window. This defines a capture area and the clipping information if relevant. The VIDIOC_G_WIN ioctl recovers the current settings and the VIDIOC_S_WIN sets new values. A successful call to VIDIOC_S_WIN indicates that a suitable set of parameters have been chosen. They do not indicate that exactly what was requested was granted. The program should call VIDIOC_G_WIN to check if the nearest match was suitable. The struct v4l2_window contains the following fields.
 
struct v4l2_window
int x The X co-ordinate specified in X windows format.
int y The Y co-ordinate specified in X windows format.
int width The width of the image capture.
int height The height of the image capture.
__u32 chromakey A host order RGB32 value for the chroma key.
struct v4l2_clip *clips A list of clipping rectangles. (Set only)
int clipcount The number of clipping rectangles. (Set only)
void *bitmap The clipping bitmap (Set only)

Use either a clipping bitmap or a list of clipping rectangles, not both. The clipping bitmap should have be the size of the preview window, with one bit per pixel. Bits of value 1 correspond to the clipped area. Clipping rectangles are passed as an array. Each clip consists of the following fields available to the user.
 
struct v4l2_clip
int x
X co-ordinate of rectangle to skip
int y
Y co-ordinate of rectangle to skip
int width
Width of rectangle to skip
int height
Height of rectangle to skip
struct v4l2_clip *next
Pointer to next clip rectangle

Note the following about video windows:

  1. The width and height fields of the struct v4l2_window reflect the width and height of the image on the screen, not the width and height of the capture. In other words, the captured image may appear stretched on screen.
  2. If the frame buffer is an overlay surface, the video data is always written into the buffer at coordinate 0,0 at the capture dimensions. (And it is up to X Windows and the application to place the overlay on the screen.)
  3. These ioctls only apply to frame buffer preview. The capture dimensions are set with the VIDIOC_S_FMT ioctl.
Merely setting the window does not enable the preview display. Preview is activatied by passing the VIDIOC_PREVIEW ioctl a value of 1, and disabled by passing it a value of 0. The argument to VIDIOC_PREVIEW is a pointer to an int.
 
 
 
 

Capturing Continuously to Pre-Allocated Buffers - VIDIOC_QBUF, VIDIOC_DQBUF, VIDIOC_STREAMON, VIDIOC_STREAMOFF

This capture mode is supported if the V4L2_FLAG_STREAMING flag is set in the struct v4l2_capability.

This capture mode captures to memory-mapped buffers. Before you can do streaming capture, you must first set up the capture image format, and allocate the capture buffers as described in the section titled Memory-Mapping Device Buffers in the Device document .

To do the capturing, call VIDIOC_QBUF to enqueue buffers to be filled. The driver will internally queue the buffers in a capture queue. The VIDIOC_QBUF ioctl takes as an argument a pointer to a struct v4l2_buffer with at least the type and index fields filled in. (Normally, you just pass back the structures returned from VIDIOC_QUERYBUF .) Call it once for each buffer to be queued. Typically you would queue up all the buffers. Then call VIDIOC_STREAMON with the buffer type to commence the capturing process.

The driver will begin filling the buffers with frame data. Only buffers that have been queued will be filled. Once a buffer is filled, it will not be filled again until it has been explicitly dequeued and requeued by the application. The application can sleep until the next buffer is done by calling select(). If no buffers are done then select() will block until a buffer is done. If there is(are) already a buffer(s) done, then select() will return immediately. It is not possible to wait on a specific buffer if there is more than one buffer queued.

Call VIDIOC_DQBUF to dequeue the next filled buffer. VIDIOC_DQBUF takes a struct v4l2_buffer object. The type field must be filled in with the buffer type. The driver will fill in the rest of the fields. See below for the flags that can be in the flags field. It is not possible to dequeue a specific buffer; buffers are always dequeued in the order in which they were captured. The bytesused field indicates how much data is in the buffer. After the data has been read out, the buffer should be queued up again to keep the frames flowing continuously. Do not queue the buffer until you have read the data out, otherwise the buffer could get overwritten before you have read all the data. VIDIOC_DQBUF immediately returns an error if there is no buffer ready (it never blocks).

You can dynamically throttle the capture frame rate by only queueing buffers at the rate you want to capture.

Call VIDIOC_STREAMOFF with the buffer type to turn off streaming. Any unfilled buffers that were queued for capture become unqueued. Any filled buffers remain in the queue. After it turns off streaming, the application should dequeue and read out any remaining filled buffers using VIDIOC_DQBUF . (If streaming is turned on again and there are any filled buffers still queued, they are dequeued and the data is lost.) Use munmap() to free the buffers.

The parameters to VIDIOC_STREAMON and VIDIOC_STREAMOFF are pointer to int.

There are certain things you can't do when streaming is active, for example changing the capture format, reading data through the read() call, or munmap()ing buffers.
 
 

Waiting for Frames Using select()

The driver supports the select() call on its file descriptors if the V4L2_FLAG_SELECT flag is set in the struct v4l2_capability. If streaming capture is not running, select() returns when there is data ready to be read with the read() call. If streaming capture is running, select() returns when there is a buffer ready to be dequeued. The caller should be sure there is a buffer in the queue first. Preview capturing does not affect select().
 
 

Capture Performance - VIDIOC_G_PERF

The VIDIOC_G_PERF ioctl fills in a struct v4l2_performance object indicating the number of frames captured, dropped, and the number of bytes captured. See the Device document for details of the v4l2_performance structure.
 
 
 

Capture Parms - VIDIOC_G_PARM, VIDIOC_S_PARM

This is to control various parameters related to video capture. These ioctls use struct v4l2_streamparm objects. The application should set the type field to V4L2_BUF_TYPE_CAPTURE, and use the capture member of the parm union. The timeperframe field applies to read() and streaming capture, and may apply to preview. It's not defined what happens for alternating-field capture if timeperframe is not equal to the natural frame rate of the video, i.e. 400000 for PAL or SECAM, or 333667 for NTSC.
 
struct v4l2_captureparm
__u32 capability   The supported capturemode flags
__u32 capturemode   Capture mode flags
unsigned long timeperframe   The desired time between frames expressed in 0.1 microsecond units
__u32 extendedmode   Driver-specific capturing mode extensions
__u32 reserved[4]   reserved for future parameters
     
Flags for the capturemode and capability fields
V4L2_MODE_HIGHQUALITY   High quality capture mode for imaging applications
V4L2_CAP_TIMEPERFRAME   The driver supports programmable frame rates (capability field only)
     

High quality mode is intended for still imaging applications. The idea is to get the best possible image quality that the hardware can deliver. It is not defined how the driver writer may acheive that; it will depend on the hardware and the ingenuity of the driver writer. High quality mode is a different mode from the the regular motion video capture modes. In high quality mode:

  1. The driver may be able to capture higher resolutions than for motion capture.
  2. The driver may support fewer pixel formats than motion capture (e.g. true color).
  3. The driver may capture and arithmetically combine multiple successive fields or frames to remove color edge artifacts and reduce the noise in the video data.
  4. The driver may capture images in slices like a scanner in order to handle larger format images than would otherwise be possible.
  5. An image capture operation may be significantly slower than motion capture.
  6. Moving objects in the image might have excessive motion blur.
  7. Capture might only work through the read() call.


Raw Device Image Cropping - VIDIOC_CROPCAP, VIDIOC_G_CROP, VIDIOC_S_CROP

Still to come....
 

Digital Zoom - VIDIOC_ZOOMCAP, VIDIOC_G_ZOOM, VIDIOC_S_ZOOM

Many devices can create a zoom and pan effect by taking the captured image from a subrectangle area of the raw device image. These ioctls give you access to that capability. Bear in mind that devices can have limited flexibility in performing the image cropping and shrinking that is involved, which could result in discrete levels of zoom. The VIDIOC_ZOOMCAP ioctl takes a pointer to a struct v4l2_zoomcap and returns the digital zoom limits of the device. The device will return an EINVAL error code if digital zoom is not supported. Even if the device supports the zoom ioctls, it is possible that the minwidth and minheight will be equal to maxwidth and maxheight, which indicates that a zoom in cannot be performed at the current time. The application should also check for that case.

Use VIDIOC_G_ZOOM and VIDIOC_S_ZOOM to query and change the current zoom area setting using a struct v4l2_zoom object. The maxwidth and maxheight represent the total size of the raw device image. If the zoom width and height are set to these then the entire image is captured, corresponding to being zoomed all the way out. The minwidth and minheight represent the smallest subrectangle that can be captured. This will likely depend on the capture format width and height. Devices may not be able to support every possible cropping rectangle, so the driver will choose the closest rectangle coordinates supported by the hardware on a VIDIOC_S_ZOOM ioctl. VIDIOC_G_ZOOM will return the actual rectangle.

If the capturing application changes the capture image dimensions, the range of valid zoom rectangles can change. If the current rectangle becomes invalid, the driver will automatically select a new rectangle in the allowed range.
 
struct v4l2_zoomcap
__u32 capability   Digital zoom capability flags (None defined yet.)
__u32 maxwidth   The maximum width of the capture subrectangle. Corresponds to zoomed all the way out.
__u32 maxheight   The maximum height of the capture subrectangle
__u32 minwidth   The minimum width of the capture subrectangle. Corresponds to zoomed all the way in.
__u32 minheight   The minimum height of the capture subrectangle
__u32 reserved[2]   reserved
     
Flags for the capability field of v4l2_zoomcap
V4L2_ZOOM_NONCAP   Zooming is supported from a non-capturing open
V4L2_ZOOM_WHILESTREAMING   Device can zoom while streaming capture is in progress
     

 
 
struct v4l2_zoom
__u32 x   Center of capture subrectangle in device coordinates. Maxwidth / 2 is the center of the image
__u32 y   Center of capture subrectangle
__u32 width   Width of capture subrectangle
__u32 height   Height of capture subrectangle
__u32 reserved   reserved
     

 

Video Standard - VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_ENUMSTD

These ioctls use a struct v4l2_standard to describe the analog video format. This structure has a number of fields for completely describing a video signal including frame rate, total lines per frame, color standard and so on.

VIDIOC_G_STD and VIDIOC_S_STD query and switch the current video standard respectively. The video standard selected applies to all inputs on the device. These ioctls pass a struct v4l2_standard object. VIDIOC_G_STD will return a structure with all fields filled in, including name. The name field is a short name for the format, for example "NTSC-M".

Use VIDIOC_ENUMSTD to enumerate the available standards. To change the standard call VIDIOC_S_STD with a struct v4l2_standard object. You can use one of the standards enumerated by VIDIOC_ENUMSTD , or fill in a struct v4l2_standard structure explicitly. The driver will examine the fields to identify the format and determine if the hardware can support it. The name field is always ignored by VIDIOC_S_STD.

It is worth stressing that switching the video standard is a big deal . Many capabilities of the capture card depend on the video standard selected, including the image resolution and frame rate. After changing the standard, the capture dimensions, required image buffer size, or other capture parameters may have changed. The caller should re-set-up the capture. The driver may only allow a standard change when there is only one open on the device.
 
struct v4l2_standard
char name[24]   A short name for the format
__u32 framerate.numerator   The frame period (not field period) is numerator/denominator, ...
__u32 framerate.denominator   ...for example, NTSC is 1001/30000, and PAL is 1/25
__u32 framelines   Total lines per frame including blanking, e.g. 525 for NTSC, 625 for PAL
__u32 reserved1   reserved
__u32 colorstandard   One of the V4L2_COLOR_STD_* values
__u32 colorstandard_data.pal. colorsubcarrier   The color subcarrier frequency rounded to the nearest Hz
__u32 colorstandard_data.ntsc. colorsubcarrier   The color subcarrier frequency rounded to the nearest Hz
__u32 colorstandard_data.secam.f0b   SECAM B-Y carrier center frequency
__u32 colorstandard_data.secam.f0r   SECAM R-Y carrier center frequency
__u32 transmission   The transmission standard. Only for RF formats. Zero for baseband signals.
__u32 reserved2   reserved
     
Values for the colorstandard field
V4L2_COLOR_STD_PAL   A PAL standard
V4L2_COLOR_STD_NTSC   An NTSC standard
V4L2_COLOR_STD_SECAM   A SECAM standard
     
Standard values for the colorsubcarrier fields
V4L2_COLOR_SUBC_PAL   (4433619) Used by most PAL formats
V4L2_COLOR_SUBC_PAL_M   (3575611) Used by PAL-M only
V4L2_COLOR_SUBC_PAL_N   (3582056) Used by PAL-N only
V4L2_COLOR_SUBC_NTSC   (3579545) Used by normal NTSC formats
V4L2_COLOR_SUBC_SECAMB   (4250000) Standard SECAM B-Y center frequency
V4L2_COLOR_SUBC_SECAMR   (4406250) Standard SECAM R-Y center frequency
     
Values for the transmission field
V4L2_TRANSM_STD_B/D/G/H/I/K/K1/L/M/N/NC   The various substandard identification letters
     

 

VIDIOC_ENUMSTD is used to retreive a list of supported standards from the device. VIDIOC_ENUMSTD takes a struct v4l2_enumstd object with the index field filled in to identify which standard in the list of supported standards to query. VIDIOC_ENUMSTD will fill in the std field. The application should start with an index of zero and increment by one until VIDIOC_ENUMSTD returns an error. The v4l2_standard structures returned by this function are suitable to be sent to VIDIOC_S_STD to select the standard. Some devices may be able to support various non-standard formats. In that case the signal formats enumerated by this ioctl may not be exhaustive of all formats the device can possibly support, but it will at least cover the supported modes among the most commonly used standards.

The inputs and outputs fields indicate which inputs/outputs of the device support this standard. If input number 0 supports this standard then bit 0 is on; if input number 1 supports it then bit 1 is on, etc.
 
struct v4l2_enumstd
int index   Index of list entry to retreive
struct v4l2_standard std   Video standard structure to be filled in
__u32 inputs   Bitmask telling which input ports can support this standard
__u32 outputs   Bitmask telling which output ports support this standard
__u32 reserved[2]   reserved
     

 

Non-Capturing Opens

If an application is opening the driver for administration or control purposes, and does not want to capture, then it should pass the O_NONCAP flag in the open() call. For example, a control panel application would do this. A non-capturing open can do the following:
 
Function   Restrictions
VIDIOC_QUERYCAP   none
VIDIOC_ENUM_PIXFMT   none
VIDIOC_ENUM_FBUFFMT   none
VIDIOC_G_FMT   none
VIDIOC_G_PERF   none
VIDIOC_G_PARM   none
VIDIOC_G_COMP   none
VIDIOC_ZOOMCAP   none
VIDIOC_G_ZOOM   none
VIDIOC_S_ZOOM   If V4L2_ZOOM_NONCAP is set
VIDIOC_ENUMSTD   none
VIDIOC_G_STD   none
VIDIOC_S_STD   Only if there is no capturing open at the time
VIDIOC_ENUMINPUT   none
VIDIOC_G_INPUT   none
VIDIOC_S_INPUT   Driver may fail the call if the change would change the standard and there is a capturing open at the time
VIDIOC_QUERYCTRL   none
VIDIOC_G_CTRL   none
VIDIOC_S_CTRL   none
VIDIOC_G_TUNER   none
VIDIOC_S_TUNER   No change can be made that will change the standard if there is a capturing open at the time
VIDIOC_G_FREQ   none
VIDIOC_S_FREQ

none
VIDIOC_G_FREQUENCY   none
VIDIOC_S_FREQUENCY

none
VIDIOC_G_AUDIO   none
VIDIOC_S_AUDIO   none

 

Video Inputs - VIDIOC_G_INPUT, VIDIOC_S_INPUT, VIDIOC_ENUMINPUT

The VIDIOC_ENUMINPUT ioctl retreives the properties of a video input into a struct v4l2_input object. Before calling VIDIOC_ENUMINPUT the caller fills in the index field to indicate which input is being queried. VIDIOC_G_INPUT takes a pointer to an integer, and returns the index of the currently selected input. VIDIOC_S_INPUT takes a pointer to an integer which is the index of the input to be used, and switches the hardware to that input.
 
struct v4l2_input
int index   The input to which these properties apply (set by the caller)
char name[32]   Friendly name of the input, preferably including the label on the input itself
int type   Type of input
__u32 capability   Capability flags of this input
int assoc_audio
Audio input associated to this video input
__u32 reserved[4]   reserved for future input properties
     
Values for the type field
V4L2_INPUT_TYPE_TUNER   This input is an analog TV tuner
V4L2_INPUT_TYPE_CAMERA   Analog baseband input
     
Flags for the capability field
V4L2_INPUT_CAP_AUDIO   The input has an associated audio channel

 

Controls - VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU, VIDIOC_G_CTRL, VIDIOC_S_CTRL

See the Device document . Capture devices typically support brightness, contrast, saturation, etc.
 
 

Tuning - VIDIOC_G_TUNER, VIDIOC_S_TUNER, VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY

If a video input is of the type V4L2_INPUT_TYPE_TUNER, then it has a tuner attached. Use VIDIOC_G_TUNER to get the information about the tuner. Tuners are described by a struct v4l2_tuner. Fill in the input number in the structure with the video input associated with the tuner, then pass the structure to the ioctl to have the data filled in. Use VIDIOC_S_TUNER to set the audmode. A struct v4l2_tuner has the following fields
 
struct v4l2_tuner
int input   The video input for this tuner
char name[32]   Canonical name for this tuner
struct v4l2_standard std   The video standard supported by this tuner
__u32 capability   Tuner capability flags
__u32 rangelow   Lowest tunable frequency
__u32 rangehigh   Hightest tunable frequency
__u32 rxsubchans   Audio subprograms currently being received
__u32 audmode   Currently selected audio mode
int signal   Signal strength if known
int afc   AFC. If negative, tune higher; if positive, tune lower
__u32 reserved[4]   reserved
     
Flags for the capability field
V4L2_TUNER_CAP_LOW   Frequency is in a lower range
V4L2_TUNER_CAP_NORM   The norm for this tuner is settable
V4L2_TUNER_CAP_STEREO   Stereo reception is supported
V4L2_TUNER_CAP_LANG1
First language (of two or more) reception is supported
V4L2_TUNER_CAP_LANG2   Second language channel reception is supported
V4L2_TUNER_CAP_SAP   Second Audio Program reception is supported
     
Flags for the rxsubchans field of struct v4l2_tuner
V4L2_TUNER_SUB_MONO   Receiving a mono signal
V4L2_TUNER_SUB_STEREO   Receiving a stereo signal
V4L2_TUNER_SUB_LANG1
Receiving first language signal
V4L2_TUNER_SUB_LANG2   Receiving a second language signal
V4L2_TUNER_SUB_SAP   Reveiving a Second Audio Program signal
     
Values for the audmode field of struct v4l2_tuner
V4L2_TUNER_MODE_MONO   Playing mono audio
V4L2_TUNER_MODE_STEREO   Playing stereo audio
V4L2_TUNER_MODE_LANG1
Playing first language audio
V4L2_TUNER_MODE_LANG2   Playing second language audio
V4L2_TUNER_MODE_SAP   Playing SAP audio



VIDIOC_G_FREQUENCY and VIDIOC_S_FREQUENCY get and set the tuner frequency of the video input indicated by the input field. Tuning frequencies are unsigned 32-bit values in units of 62.5 KHz, or if the V4L2_TUNER_CAP_LOW bit is set, in units of 62.5 Hz.

struct v4l2_frequency
int input

The video input for this tuner
__u32 frequency

The frequency divided by 62.5KHz or 62.5 Hz
__u32 reserved[2]

reserved




 
 

Audio

TV and Radio devices have one or more audio inputs that may be selected. The audio properties are queried by passing struct v4l2_audio to VIDIOC_G_AUDIO ioctl. The VIDIOC_S_AUDIO ioctl sets audio properties.
 
struct v4l2_audio
int audio   The audio input number
char name[32]   Canonical name for the audio input
__u32 capability   Capability flags
__u32 mode   The selected modes
__u32 reserved[2]   reserved
     
Flags for the capability field of struct v4l2_audio
V4L2_AUDCAP_EFFECTS   Stereo effects are supported
V4L2_AUDCAP_AVL   Automatic Volume Level mode is supported
     
Flags and values for the mode field of struct v4l2_audio
V4L2_AUDMODE_AVL   AVL mode is on
V4L2_AUDMODE_STEREO_field   Mask for stereo effects field
V4L2_AUDMODE_STEREO_LINEAR   This stereo mode is enabled
V4L2_AUDMODE_STEREO_PSEUDO   This stereo mode is enabled
V4L2_AUDMODE_STEREO_SPATIAL30   This stereo mode is enabled
V4L2_AUDMODE_STEREO_SPATIAL50   This stereo mode is enabled