Video for Linux Two - Video Output API Specification

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 output devices. Video output devices can take digitized images from computer memory, such as those captured from a capture device, and convert them into a video signal. A video signal is a standard analog signal such as a PAL or NTSC signal, or a digital video signal such as an ITU-R601, or DV signal. A video output device can also output video to a graphics display frame buffer or overlay device.

An output device can be thought of a reverse capture device, or as a codec device where the output goes out onto a wire or to a frame buffer instead of to a memory buffer.
 

Multiple Opens per Device

Video output devices can support no-I/O opens. See the Device document.
 
 

Query Capabilities - VIDIOC_QUERYCAP

This ioctl call is used to obtain the capability information for the device. See the Device document document. Output devices will typically set the V4L2_FLAG_WRITE flag to indicate they accept image data via the write() function.
 
 

Enumerating Supported Image Formats - VIDIOC_ENUM_PIXFMT, VIDIOC_ENUM_FBUFFMT

An application can query the list of supported source formats or preview frame buffer formats with the VIDIOC_ENUM_PIXFMT or VIDIOC_ENUM_FBUFFMT ioctl respectively. The PIXFMT format is the format of the images being sent to the driver to be output. 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. These ioctls behave essentially just like the format enumeration of a capture device.
 
 

Source Image Format - VIDIOC_G_FMT, VIDIOC_S_FMT

Use VIDIOC_S_FMT to set the source image format. VIDIOC_G_FMT retrieves the current source format. Both ioctls use a struct v4l2_format to pass the format. See the Device document for more information about that structure. Use V4L2_BUF_TYPE_VIDEOOUT in the type field of v4l2_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.

If the images passed in will be entire frames, that is, two fields interlaced into one image, the V4L2_FMT_FLAG_INTERLACED flag should be set in the format. If the images will be a single field, and always the same field, the application should set one of the V4L2_FMT_FLAG_TOPFIELD or V4L2_FMT_FLAG_BOTFIELD flags.

If the images are to be alternating fields, each image is a single field, the application 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. Alternating field data like this is only supported with memory-mapped buffers and the streaming ioctls, not with the write() call.

If you are planning on using memory mapped device buffers, it is a good idea to unmap the buffers before changing the image format with VIDIOC_S_FMT If you don't then image dimensions will be limited by the size of the existing buffers.
 
 

Memory-Mapping Device Buffers - VIDIOC_REQBUFS, VIDIOC_QUERYBUF

These ioctls implement a general-purpose protocol for using mmap() to make driver buffers or device memory buffers accessible to the application for I/O. See the Device document for a complete discussion. Devices will use V4L2_BUF_TYPE_VIDEOOUT for buffers that accept images from the application to be output.
 
 

Writing Source Images - write()

This capture mode is supported if the V4L2_FLAG_WRITE flag is set in the struct v4l2_capability. Each call to write() should send a new frame. The driver may fail the write() if the length parameter is less than the required buffer size specified by the VIDIOC_G_FMT ioctl.

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.

Non-blocking write() mode is supported in the usual way.
 
 

Continuous Output from Pre-Allocated Buffers - VIDIOC_QBUF, VIDIOC_DQBUF, VIDIOC_STREAMON, VIDIOC_STREAMOFF

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

This uses memory-mapped buffers to send data to the device driver. Before you can do streaming output, you must first set up the image format, and allocate the buffers as described in the Device document in the section titled Memory-Mapping Device Buffers.

To send images out, first fill a buffer, or several buffers with data, and fill in the bytesused, flags, timestamp, and timecode (optional) fields of the corresponding v4l2_buffer structures. In the flags field, you should set or clear the V4L2_BUF_FLAG_KEYFRAME, _PFRAME, _BFRAME, _ODDFIELD and _EVENFIELD flags as appropriate.

Then queue the buffers by calling the VIDIOC_QBUF ioctl for each buffer with a pointer to the struct v4l2_buffer. The driver will internally queue the buffers. When the buffers are queued, call VIDIOC_STREAMON with a pointer to an integer set to the buffer type. The device will begin processing the buffers and sending them out. After a buffer has been processed, it is available to be dequeued and used again. The application can sleep until the next buffer becomes available by calling select(). If a buffer is already done, the call will return immediately.

The driver will transmit the frames in the order in which they were enqueued. The driver will not transmit a frame until the current system time reaches the time set in the timestamp field. When a frame is used, the driver will fill in the timestamp field with the time when the frame was actually transmitted.

Call VIDIOC_DQBUF to dequeue the next available buffer. VIDIOC_DQBUF takes a struct v4l2_buffer object. The type field must first be filled in with the buffer type. The driver will fill in the rest of the fields. Buffers should be dequeued, refilled and requeued again to keep the data flowing continuously. VIDIOC_DQBUF immediately returns an error if there is no buffer ready (it never blocks).

Call VIDIOC_STREAMOFF with a pointer to an integer set to the buffer type to turn off streaming output. Use munmap() to free the buffers.

There are certain things you can't do when streaming is active, for example changing the image format, or writing data through the write() call.
 
 

Waiting for the Device 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 output is not running, select() returns when the driver is ready to accept data with the write() call. If streaming 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.
 
 

Performance - VIDIOC_G_PERF

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

Output to a Hardware Frame Buffer - VIDIOC_G_FBUF, VIDIOC_S_FBUF, VIDIOC_G_WIN, VIDIOC_S_WIN

This mode is supported if the the flag is set in struct v4l2_capability. Certain V4L2_FLAG_PREVIEW implementation details depend on the hardware and the driver.

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. The frame buffer could 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. 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.

VIDIOC_G_FBUF, VIDIOC_S_FBUF, VIDIOC_G_WIN, VIDIOC_S_WIN work the same way as descibed in the capture spec.
 
 

Output Parameters - VIDIOC_G_PARM, VIDIOC_S_PARM

This is to control various parameters related to video output. These ioctls use struct v4l2_streamparm objects, with the parm.output field filled in. Set the type field of the v4l2_streamparm to V4L2_BUF_TYPE_VIDEOOUT.

[What do we need here?]
 

struct v4l2_outputparm

__u32 capability		The supported outputmode flags
__u32 outputmode		Output 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 outputmode and capability fields

V4L2_CAP_TIMEPERFRAME		The driver supports programmable frame rates (capability field only)

 

Video Standard - VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_ENUMSTD

These ioctls set the video output standard for those devices that generate PAL/NTSC/SECAM type analog video. They work as described in the capture spec.
 
 

No-I/O Opens

If an application is opening the driver for administration or control purposes, and does not want to do video output, then it should pass the O_NOIO flag in the open() call. For example, a control panel application would do this. A no-I/O open can do the following:
 

Video Outputs - VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT, VIDIOC_ENUMOUTPUT

The VIDIOC_ENUMINPUT ioctl retreives the properties of a video output into a struct v4l2_output object. Before calling VIDIOC_ENUMOUTPUT the caller fills in the index field to indicate which output is being queried. VIDIOC_G_OUTPUT takes a pointer to an integer, and returns the index of the currently selected output. VIDIOC_S_OUTPUT takes a pointer to an set to the index of the output to be used, and switches the hardware to that output.
 

Controls - VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU, VIDIOC_G_CTRL, VIDIOC_S_CTRL

See the Device document.
 
 

Tuning - VIDIOC_G_MOD, VIDIOC_S_MOD, VIDIOC_G_FREQ, VIDIOC_S_FREQ

If a video output is of the type V4L2_OUTPUT_TYPE_MODULATOR, then it has a RF modulator attached. Use VIDIOC_G_MOD to get the information about the modulator. Modulators are described by a struct v4l2_modulator. Fill in the output number in the structure with the video output associated with the modulator, then pass the structure to the ioctl to have the data filled in. Use VIDIOC_S_MOD to set the txsubchans. A struct v4l2_modulator has the following fields
 

VIDIOC_G_FREQ and VIDIOC_S_FREQ get and set the tuner frequency. 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.
 
 

Audio

A video output may have an audio output too. The audio properties are queried by passing struct v4l2_audioout to VIDIOC_G_AUDOUT ioctl. The VIDIOC_S_AUDOUT ioctl sets audio properties.