VIDEO(4)

📦
version 11.0 · 2 versions
, in nixpkgs unstable

🌸 NAME 🌸

video — device-independent video driver layer. This is the video(4) page from the Kernel Interfaces Manual, bestie, and we are about to get into the whole video peripheral situation 💖

✨ SYNOPSIS ✨

#include <sys/videoio.h>

💖 DESCRIPTION 💖

Okay so the video driver? It provides support for various video peripherals. It gives you a uniform programming interface layer above different underlying video hardware drivers, which is iconic because the hardware underneath can be a whole mess. 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. That’s the main character path, periodt. 🎬

🎀 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. That’s lowkey important, bestie.

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. Not me side-eyeing partial reads, but okay 🙈

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, in this whole sequence:

  1. VIDIOC_REQBUFS to request the driver reserve buffers
  2. VIDIOC_QUERYBUF to query the details of each buffer
  3. mmap(2) to map each buffer into memory
  4. VIDIOC_QBUF to queue the buffers for receiving video data
  5. VIDIOC_STREAMON to begin streaming of video data
  6. VIDIOC_DQBUF to remove a filled buffer from the queue

At this point the video data from the dequeued buffer is valid. Slay. ✨

🦋 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
  • bus_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. So the vibe check on count is real, iykyk. 🫶

       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. That’s the iconic mapping combo, fr fr. 🗺️

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. Cute. 🎀

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. It’s giving “press play on the video feed” energy. ▶️

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. This is the part where you’re like “bestie, why are we waiting,” and the answer is: blocking, unless nonblocking was set. 😭

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. Yep, the remaining-data rule is back like a recurring character. 🔁

🍓 FILES 🍓

  • /dev/video

🌈 SEE ALSO 🌈

⭐ HISTORY ⭐

The video device driver first appeared in NetBSD 5.0. Vintage but make it iconic. 👑

👑 AUTHORS 👑

Patrick Mahoney <pat@polycrystal.org>

💀 BUGS 💀

Okay so the tea ☕: this does not support the complete V4L2 API. It only supports the capture interface. It does not support writing, overlay, VBI, tuner, audio, radio, or asyncio. No cap, that’s the whole list.

Mwah 💋 — this page is from Debian, dated March 5, 2011, and it’s the VIDEO(4) page. Byeee 🫶

📦 where this page comes from