1.24. Extendend API¶

1.24.1. Introduction¶

The Extended Format API was conceived to extend V4L2 capabilities and to simplify certain mechanisms. It unifies single- vs multi- planar handling, brings the concept of pixelformat + modifiers, allows planes to be placed in any offset inside a buffer and let userspace to change colorspace attributes if supported by the driver.

Data format negotiation and buffer handling works very similar to the classical version, thus in this document we’ll just mention the main differences.

1.24.2. Data Format Negotiation¶

The API replaces the classical ioctls:

VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT (with v4l2_format as the main parameter).

By the extended versions:

VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT (with v4l2_ext_pix_format as the main parameter).

For CAPTURE and OUTPUT queues only.

The type field of struct v4l2_ext_pix_format only accepts V4L2_BUF_TYPE_VIDEO_CAPTURE or V4L2_BUF_TYPE_VIDEO_OUTPUT, and it supports multiplanar format through a combination of pixelfomat and modifier fields.

Only the single-planar variants of the pixel formats are valid in the pixelformat field. To support multi-planar, a modifier should be set in the modifier field to provide more information regarding the memory layout of pixels and number of planes.

The plane_fmt field is an array which holds information by plane using the v4l2_plane_ext_pix_format. When this struct is filled, its sizeimage field should be non-zero for all valid planes for a given pixelformat + modifier combination, and zeroed for the invalid ones.

Colospace attributes are not read-only as in the classical version, i.e, they can be set by application and drivers will adjust accordingly depending on what is supported by the underlying hardware.

1.24.3. Buffers¶

The API replaces the classical ioctls:

VIDIOC_CREATE_BUFS (with v4l2_create_buffers as the main parameter), VIDIOC_QUERYBUF, VIDIOC_QBUF, VIDIOC_DQBUF, VIDIOC_PREPARE_BUF (with v4l2_buffer as the main parameter)

By the extended versions:

VIDIOC_EXT_CREATE_BUFS (with v4l2_ext_create_buffers as the main parameter), VIDIOC_EXT_QUERYBUF, VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF, VIDIOC_EXT_PREPARE_BUF (with v4l2_ext_buffer as the main parameter)

The basic difference between v4l2_create_buffers and v4l2_ext_create_buffers is that the later have a v4l2_ext_pix_format as the type of the format field.

Comparing v4l2_ext_buffer with v4l2_buffer, in the extended version there is a unification of the single-/multi- planar handling through the planes field of type v4l2_ext_plane.

The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset inside a buffer. Planes can be placed in different locations inside the same buffer, or in different buffers.

struct v4l2_ext_plane¶: extended plane buffer info

Definition

struct v4l2_ext_plane {
  __u32 buffer_length;
  __u32 plane_length;
  union {
    __u32 mem_offset;
    __u64 userptr;
    __s32 dmabuf_fd;
  } m;
  __u32 offset;
  __u32 memory;
  __u32 reserved[4];
};

Members

buffer_length: size of the entire buffer in bytes, should fit offset + plane_length
plane_length: size of the plane in bytes.
offset: offset in the memory buffer where the plane starts.
memory: enum v4l2_memory; the method, in which the actual video data is passed
reserved: extra space reserved for future fields, must be set to 0.

Description

Buffers consist of one or more planes, e.g. an YCbCr buffer with two planes can have one plane for Y, and another for interleaved CbCr components. Each plane can reside in a separate memory buffer, or even in a completely separate memory node (e.g. in embedded devices).

struct v4l2_ext_buffer¶: extended video buffer info

Definition

struct v4l2_ext_buffer {
  __u32 index;
  __u32 type;
  __u32 field;
  __u32 sequence;
  __u64 flags;
  __u64 timestamp;
  struct v4l2_ext_plane planes[VIDEO_MAX_PLANES];
  __s32 request_fd;
  __u32 reserved[9];
};

Members

index: id number of the buffer
type: V4L2_BUF_TYPE_VIDEO_CAPTURE or V4L2_BUF_TYPE_VIDEO_OUTPUT
field: enum v4l2_field; field order of the image in the buffer
sequence: sequence count of this frame
flags: buffer informational flags
timestamp: frame timestamp
planes: per-plane buffer information
request_fd: fd of the request that this buffer should use
reserved: extra space reserved for future fields, must be set to 0

Description

Contains data exchanged by application and driver using one of the Streaming I/O methods.