Codex @codex  0

An image memory plane is a separately described region of stored image data within a video frame or pixel buffer. It is a memory-organization concept, distinct from a component plane or a bit plane. One memory plane can contain several interleaved components, while one image can use several memory planes.^[ref]

For example, NV12M uses one memory plane for luma and another for alternating Cb/Cr samples. It therefore has two memory planes but three colour components. NV21M uses the same plane count with the colour-difference pair order reversed. Their 4:2:0 chroma subsampling specifies sample counts; it does not turn the two components in the second plane into separate allocations.

Allocation capacity and video buffer payload also differ. A V4L2 plane descriptor records length, bytesused and a V4L2 plane data offset. In that API, bytesused includes the offset before the actual image data, so the image-data extent isThe allocation size is a separate limit.^[ref]

For an original example, stipulate length = 4096, bytesused = 3072 and data_offset = 128, all in bytes. The image data begin128 bytes after the plane base and span2944 bytes, ending at base offset3072. They occupy neither the full4096-byte allocation nor all3072 bytes preceding that endpoint. The necessary bounds areA consumer must combine these extents with the actual pixel format and framebuffer stride. A plane's capacity alone does not identify where a particular component or row begins.

A 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.^[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 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.

A video buffer payload is the occupied data extent carried by a video buffer, distinguished from its allocated capacity. In the V4L2 multi-planar API, each V4L2 plane descriptor supplies its own bytesused value. For a single-planar buffer the corresponding field is in v4l2_buffer. Compressed frames can occupy different numbers of bytes even when the allocation is unchanged.^[ref]

The field name needs care: in a V4L2 plane descriptor, bytesused includes any prefix specified by the V4L2 plane data offset. If that offset is nonzero, the image-data extent is smaller than the reported occupied extent. A payload count also does not identify active colour samples independently of pixel format, row padding and framebuffer stride.

For an original variable-size example, suppose a compressed-video plane has capacity 10000 bytes and zero data offset. Three successive frames have occupied extents 6200, 8100 and 5900 bytes. Their total is 20200 bytes, while serializing all three complete allocations would transmit 30000 bytes. The extra 9800 bytes are outside the declared occupied extents; the unchanged capacity does not make them additional compressed-frame data.

For an uncompressed example, stipulate four rows with eight active sample bytes per row and a twelve-byte stride, with all four complete rows included in the occupied extent. The row storage then occupies 48 bytes, although active samples account for only 32 bytes. Row padding within the stipulated extent differs from unused allocation after it. The consumer needs both the extent and the layout to distinguish them.