= V4L2 multi-planar API
{c}
The \b[V4L2 multi-planar API] is the <Video4Linux> interface for describing video buffers whose data may occupy several <image memory planes>. A buffer acts as a container, while per-plane descriptors identify the relevant storage. This supports formats such as <NV12M> and <NV21M> without assuming that one plane immediately follows another.<Single- and multi-planar APIs in the Linux Kernel documentation>[§1.26, discontiguous frame storage and interface extensions]{ref}
A multi-planar interface and a multi-planar format are different choices. The interface can also carry supported single-planar formats when described through its structures; the reverse interface cannot describe a multi-planar format. Buffer-type names ending in `_MPLANE` identify the multi-planar interface, rather than specifying a colour model or sampling ratio.<Single- and multi-planar APIs in the Linux Kernel documentation>[§1.26.1, API versus format; opening buffer-type description]{ref}
A practical interpretation depends on the structure being read. In `v4l2_buffer`, `length` means a number of plane-array elements under the multi-planar API. Inside a <V4L2 plane descriptor>, `length` instead means that plane's allocation size in <bytes>.<Buffers in the Linux Kernel video API documentation>[§§3.5.2–3.5.3, length fields]{ref}
For an original descriptor example, a frame with two planes has a container plane count of two and stipulated plane capacities4096 and2048 bytes. Treating the outer count as a two-byte storage capacity, or treating4096 as the number of plane descriptors, confuses quantities with different meanings. The sum6144 describes those declared capacities, not the number of active image bytes.
The negotiated <pixel format> still determines the component arrangement. Descriptors for two planes could represent a luma plane plus interleaved colour differences; they do not automatically mean one red plane and one green plane. <Framebuffer stride>, sample encoding and <chroma sample location> remain part of interpreting the image.
Back to article page
