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?]
| __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 | |
| 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:
| 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_ENUMSTD | none | |
| VIDIOC_G_STD | none | |
| VIDIOC_S_STD | Only if there is no capturing open at the time | |
| VIDIOC_ENUMOUTPUT | none | |
| VIDIOC_G_OUTPUT | none | |
| VIDIOC_S_OUTPUT | 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_MOD | none | |
| VIDIOC_S_MOD | 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_AUDOUT | none | |
| VIDIOC_S_AUDOUT | none |
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.
| int index | The outnput to which these properties apply (set by the caller) | |
| char name[32] | Friendly name of the output, preferably including the label on the output itself | |
| int type | Type of output | |
| __u32 capability | Capability flags of this output | |
| int assoc_audio | Audio output associated with this video output | |
| __u32 reserved[4] | reserved for future output properties | |
| V4L2_OUTPUT_TYPE_MODULATOR | This output is an analog TV modulator | |
| V4L2_OUTPUT_TYPE_ANALOG | Analog baseband output | |
| V4L2_OUTPUT_CAP_AUDIO | Video output has an associated audio 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
| int output | The video output for this modulator | |
| char name[32] | Canonical name for this modulator | |
| struct v4l2_standard std | The video standard supported by this modulator | |
| __u32 capability | Modulator capability flags | |
| __u32 rangelow | Lowest tunable frequency | |
| __u32 rangehigh | Hightest tunable frequency | |
| __u32 txsubchans | Audio subprograms being transmitted | |
| __u32 reserved[4] | reserved | |
| 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 transmission is supported | |
| V4L2_TUNER_CAP_LANG1 | First language (of two) channel transmission is supported | |
| V4L2_TUNER_CAP_LANG2 | Second language channel transmission is supported | |
| V4L2_TUNER_CAP_SAP | Second Audio Program transmission is supported | |
| V4L2_TUNER_SUB_MONO | Transmitting mono audio | |
| V4L2_TUNER_SUB_STEREO | Transmitting stereo audio | |
| V4L2_TUNER_SUB_LANG1 | Transmitting first language audio | |
| V4L2_TUNER_SUB_LANG2 | Transmitting second language audio | |
| V4L2_TUNER_SUB_SAP | Transmitting SAP audio |
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.
| int audio | The audio output number | |
| char name[32] | Canonical name for the audio input | |
| __u32 capability | Capability flags | |
| __u32 mode | The selected modes | |
| int reserved[2] | reserved | |
| (none) | No audio capabilities are defined yet. | |
| (none) | No audio modes are defined yet. |