Updated: 2021/Apr/14

VIDEO(4)                     Device Drivers Manual                    VIDEO(4)

     video - device-independent video driver layer

     #include <sys/videoio.h>

     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.

     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.

     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:

                     support video capturing

                     supports the read(2) and/or write(2) mode

                     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];

     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

             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;

             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.

             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.


     auvitek(4), pseye(4), uvideo(4), video(9)

     V4L2 API Specification: http://v4l2spec.bytesex.org/

     The video device driver first appeared in NetBSD 5.0.

     Patrick Mahoney <pat@polycrystal.org>

     Does not support the complete V4L2 API.  Only supports the capture
     interface.  Does not support writing, overlay, VBI, tuner, audio, radio,
     or asyncio.

NetBSD 9.99                      March 5, 2011                     NetBSD 9.99