VIDEO(4) BSD Kernel Interfaces Manual VIDEO(4)NAMEvideo — device-independent video driver layer
SYNOPSIS
#include <sys/videoio.h>
DESCRIPTION
The video driver provides support for various video peripherals. It pro‐
vides a uniform programming interface layer above different underlying
video hardware drivers. The video layer provides a Video4Linux2 compati‐
ble API. A number of ioctl(2) commands are supported controlling the
device. See http://v4l2spec.bytesex.org/ for the official V4L2 specifi‐
cation.
The device file for video operation is /dev/video.
READING VIDEO SAMPLES
Video data is separated into logical video samples which will typically
be one complete video frame. With compressed formats, a video sample may
be one logical chunk and not one complete frame depending on the compres‐
sion format. Video samples may be read from /dev/video in one of several
different modes.
In read mode, calls to read(2) will return at most the data of one video
sample. If the entire sample is not read, then subsequent reads will
return at most the remaining data in that video sample.
Video samples may be mapped into memory with mmap(2). The driver allo‐
cates internal buffers for a number of video samples which are mapped
into memory. Initiating this mode requires several ioctl(2) commands:
VIDIOC_REQBUFS to request the driver reserve buffers, VIDIOC_QUERYBUF to
query the details of each buffer, mmap(2) to map each buffer into memory,
VIDIOC_QBUF to queue the buffers for receiving video data,
VIDIOC_STREAMON to begin streaming of video data, and VIDIOC_DQBUF to
remove a filled buffer from the queue. At this point the video data from
the dequeued buffer is valid.
DEVICE CAPABILITIES
VIDIOC_QUERYCAP (struct v4l2_capability)
This command queries the capabilities of the device. The first
three fields are informational NULL terminated strings filled by
the driver: driver describes the driver used by this device, card
describes the video capture card or camera, and buf_info repre‐
sents the bus to which the hardware device is attached.
The capabilities field contains a number of flags indicating var‐
ious features supported by the driver or hardware:
V4L2_CAP_VIDEO_CAPTURE
support video capturing
V4L2_CAP_READWRITE
supports the read(2) and/or write(2) mode
V4L2_CAP_STREAMING
supports mmap(2) mode
struct v4l2_capability {
uint8_t driver[16];
uint8_t card[32];
uint8_t bus_info[32];
uint32_t version;
uint32_t capabilities;
uint32_t reserved[4];
};
STREAMING INTERFACE
VIDIOC_REQBUFS (struct v4l2_requestbuffers)
This command requests that the driver reserve space for count
samples. type must be set to V4L2_BUF_TYPE_VIDEO_CAPTURE and
memory to V4L2_MEMORY_MMAP. The returned count represents the
actual number of samples reserved which may be more or fewer than
requested.
struct v4l2_requestbuffers {
uint32_t count;
enum v4l2_buf_type type;
enum v4l2_memory memory;
uint32_t reserved[2];
};
VIDIOC_QUERYBUF (struct v4l2_buffer)
This command should be called for each buffer in count above.
The fields index, type, and memory must be set to a valid index
from 0 to count-1, and the same type and memory as used in
VIDIOC_QUERYBUF. The driver returns m.offset and length.
struct v4l2_buffer {
uint32_t index;
enum v4l2_buf_type type;
uint32_t bytesused;
uint32_t flags;
enum v4l2_field field;
struct timeval timestamp;
struct v4l2_timecode timecode;
uint32_t sequence;
enum v4l2_memory memory;
union {
uint32_t offset;
unsigned long userptr;
} m;
uint32_t length;
uint32_t input;
uint32_t reserved;
};
mmap(2)
Each buffer must be mapped with a call to mmap(2), passing the
length and m.offset values obtained above. The prot
PROT_READ|PROT_WRITE and flags MAP_SHARED are recommended.
VIDIOC_QBUF (struct v4l2_buffer)
This command indicates to the driver that the buffer is ready to
receive a video sample. The following fields must be set: index,
set to a valid buffer index from 0 to count - 1; type, set to the
same type used above; and memory, set to the same memory used
above. Each buffer should be queued with this command. Order is
not important.
VIDIOC_STREAMON (int)
This command starts streaming. Queued buffers will be filled
with data. select(2) will indicate that a buffer is done and
available for reading.
VIDIOC_DQBUF (struct v4l2_buffer)
This command dequeues an available buffer from the driver. If no
buffer is available, it blocks until one is, unless O_NONBLOCK
was specified to open(2), in which case it returns EAGAIN.
select(2), or poll(2) prior to initiating any other mode will
begin streaming of video for reading with read(2). In this
streaming mode select(2) or poll(2) indicate the availability of
a video frame. Calls to read(2) will return at most the video
data of one video sample. If the entire sample is not read, then
subsequent reads will return at most the remaining data in that
video sample.
FILES
/dev/video
SEE ALSOauvitek(4), pseye(4), uvideo(4), video(9)HISTORY
The video device driver first appeared in NetBSD 5.0.
AUTHORS
Patrick Mahoney ⟨pat@polycrystal.org⟩
BUGS
Does not support the complete V4L2 API. Only supports the capture inter‐
face. Does not support writing, overlay, VBI, tuner, audio, radio, or
asyncio.
BSD March 5, 2011 BSD
