= V4L2 plane descriptor
{c}
A \b[V4L2 plane descriptor] is a `v4l2_plane` structure describing one <image memory plane> in the <V4L2 multi-planar API>. The containing `v4l2_buffer` refers to an <array> of these descriptors. Each descriptor records storage capacity, occupied extent and the <V4L2 plane data offset>; its storage reference depends on the selected <input-output> method.<Buffers in the Linux Kernel video API documentation>[§§3.5.2–3.5.3, planes pointer and v4l2_plane members]{ref}
The two structures use `length` for different quantities. The container's `length` counts descriptor-array elements; a plane descriptor's `length` counts <bytes>. Neither is automatically the active image extent. For a stipulated two-plane <NV12M> buffer, suppose the plane capacities are 8192 and 4096 bytes, with occupied extents 7000 and 3500 bytes and zero data offsets. Then the container describes two planes, storage capacity totals 12288 bytes, and occupied data total 10500 bytes. These are three different measurements of the same buffer.
For capture, the <device driver> supplies the occupied extent and data offset; for output, the application supplies them. A consumer combines those values with the negotiated <pixel format> and <framebuffer stride>. Describing two planes does not imply two colour components: <NV12M> has a <luma (video)> plane and another containing both colour-difference components.
A descriptor describes access to image storage; it does not itself contain an image-sized copy. Two equal descriptor counts can therefore describe different allocations, different component arrangements or different amounts of valid data. The <video buffer payload> and its layout must be interpreted separately.
Back to article page
