NAME
video —
device-independent video driver
layer
SYNOPSIS
#include <sys/videoio.h>
DESCRIPTION
The
video driver provides support for various video
peripherals. It provides a uniform programming interface layer above different
underlying video hardware drivers. The video layer provides a Video4Linux2
compatible API. A number of
ioctl(2) commands are supported
controlling the device.
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 compression 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 allocates
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 represents the bus to which the
hardware device is attached.
The capabilities field contains a number of flags
indicating various 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 ALSO
auvitek(4),
pseye(4),
uvideo(4),
video(9)
V4L2 API Specification
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 interface.
Does not support writing, overlay, VBI, tuner, audio, radio, or asyncio.