Video buffer payload

ID: video-buffer-payload

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.

New to topics? Read the docs here!