The V4L2 video device image format and sizes. More...
Classes | |
| struct | Plane |
| Per-plane memory size information. More... | |
Public Member Functions | |
| const std::string | toString () const |
| Assemble and return a string describing the format. More... | |
Public Attributes | |
| V4L2PixelFormat | fourcc |
| The fourcc code describing the pixel encoding scheme. More... | |
| Size | size |
| The image size in pixels. | |
| std::optional< ColorSpace > | colorSpace |
| The color space of the pixels. More... | |
| std::array< Plane, 3 > | planes |
| The per-plane memory size information. More... | |
| unsigned int | planesCount = 0 |
| The number of valid data planes. | |
Detailed Description
The V4L2 video device image format and sizes.
This class describes the image format and resolution to be programmed on a V4L2 video device. The image format is defined by a fourcc code (as specified by the V4L2 API with the V4L2_PIX_FMT_* macros), a resolution (width and height) and one to three planes with configurable line stride and a total per-plane size in bytes.
Image formats, as defined by the V4L2 APIs, are categorised as packed, semi-planar and planar, and describe the layout of the image pixel components stored in memory.
Packed image formats store pixel components one after the other, in a contiguous memory area. Examples of packed image formats are YUYV permutations, RGB with different pixel sub-sampling ratios such as RGB565 or RGB666 or Raw-Bayer formats such as SRGGB8 or SGRBG12.
Semi-planar and planar image formats store the pixel components in separate and possibly non-contiguous memory areas, named planes, whose sizes depend on the pixel components sub-sampling ratios, which are defined by the format. Semi-planar formats use two planes to store pixel components and notable examples of such formats are the NV12 and NV16 formats, while planar formats use three planes to store pixel components and notable examples are YUV422 and YUV420.
Image formats supported by the V4L2 API are defined and described in Section number 2 of the "Part I - Video for Linux API" chapter of the "Linux Media Infrastructure userspace API", part of the Linux kernel documentation.
In the context of this document, packed image formats are referred to as "packed formats" and semi-planar and planar image formats are referred to as "planar formats".
V4L2 also defines two different sets of APIs to work with devices that store planes in contiguous or separate memory areas. They are named "Single-plane APIs" and "Multi-plane APIs" respectively and are documented in Section 2.1 and Section 2.2 of the above mentioned "Part I - Video for Linux API" documentation.
The single-plane API allows, among other parameters, the configuration of the image resolution, the pixel format and the stride length. In that case the stride applies to all planes (possibly sub-sampled). The multi-plane API allows configuring the resolution, the pixel format and a per-plane stride length and total size.
Packed image formats, which occupy a single memory area, are easily described through the single-plane API. When used on a video device that implements the multi-plane API, only the size and stride information contained in the first plane are taken into account.
Planar image formats, which occupy distinct memory areas, are easily described through the multi-plane APIs. When used on a video device that implements the single-plane API, all planes are stored one after the other in a contiguous memory area, and it is not possible to configure per-plane stride length and size, but only a global stride length which is applied to all planes.
The V4L2DeviceFormat class describes both packed and planar image formats, regardless of the API type (single or multi plane) implemented by the video device the format has to be applied to. The total size and bytes per line of images represented with packed formats are configured using the first entry of the V4L2DeviceFormat::planes array, while the per-plane size and per-plane stride length of images represented with planar image formats are configured using the opportune number of entries of the V4L2DeviceFormat::planes array, as prescribed by the image format definition (semi-planar formats use 2 entries, while planar formats use the whole 3 entries). The number of valid entries of the V4L2DeviceFormat::planes array is defined by the V4L2DeviceFormat::planesCount value.
Member Function Documentation
◆ toString()
| const std::string libcamera::V4L2DeviceFormat::toString | ( | ) | const |
Assemble and return a string describing the format.
- Returns
- A string describing the V4L2DeviceFormat
Member Data Documentation
◆ colorSpace
| libcamera::V4L2DeviceFormat::colorSpace |
The color space of the pixels.
The color space of the image. When setting the format this may be unset, in which case the driver gets to use its default color space. After being set, this value should contain the color space that was actually used. If this value is unset, then the color space chosen by the driver could not be represented by the ColorSpace class (and should probably be added).
It is up to the pipeline handler or application to check if the resulting color space is acceptable.
◆ fourcc
| libcamera::V4L2DeviceFormat::fourcc |
The fourcc code describing the pixel encoding scheme.
The fourcc code, as defined by the V4L2 API with the V4L2_PIX_FMT_* macros, that identifies the image format pixel encoding scheme.
◆ planes
| libcamera::V4L2DeviceFormat::planes |
The per-plane memory size information.
Images are stored in memory in one or more data planes. Each data plane has a specific line stride and memory size, which could differ from the image visible sizes to accommodate padding at the end of lines and end of planes. Only the first planesCount entries are considered valid.
The documentation for this class was generated from the following files:
- include/libcamera/internal/v4l2_videodevice.h
- src/libcamera/v4l2_videodevice.cpp
