libcamera: libcamera::PixelFormatInfo Class Reference

libcamera v0.0.2 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
libcamera::PixelFormatInfo Class Reference

Information about pixel formats. More...

Collaboration diagram for libcamera::PixelFormatInfo:
[legend]

## Classes
struct | Plane
| Information about a single plane of a pixel format. More...

## Public Types
enum | ColourEncoding { ColourEncodingRGB , ColourEncodingYUV , ColourEncodingRAW }
| The colour encoding type. More...

## Public Member Functions
bool | isValid () const
| Check if the pixel format info is valid. More...
unsigned int | stride (unsigned int width, unsigned int plane, unsigned int align=1) const
| Compute the stride. More...
unsigned int | planeSize (const Size &size, unsigned int plane, unsigned int align=1) const
| Compute the number of bytes necessary to store a plane of a frame. More...
unsigned int | planeSize (unsigned int height, unsigned int plane, unsigned int stride) const
| Compute the number of bytes necessary to store a plane of a frame. More...
unsigned int | frameSize (const Size &size, unsigned int align=1) const
| Compute the number of bytes necessary to store a frame. More...
unsigned int | frameSize (const Size &size, const std::array< unsigned int, 3 > &strides) const
| Compute the number of bytes necessary to store a frame. More...
unsigned int | numPlanes () const
| Retrieve the number of planes represented by the format. More...

## Static Public Member Functions
static const PixelFormatInfo & | info (const PixelFormat &format)
| Retrieve information about a pixel format. More...
static const PixelFormatInfo & | info (const V4L2PixelFormat &format)
| Retrieve information about a V4L2 pixel format. More...
static const PixelFormatInfo & | info (const std::string &name)
| Retrieve information about a pixel format. More...

## Public Attributes
const char * | name
| The format name as a human-readable string, used as the test representation of the PixelFormat. More...
PixelFormat | format
| The PixelFormat described by this instance. More...
std::vector< V4L2PixelFormat > | v4l2Formats
| The V4L2 pixel formats corresponding to the PixelFormat. More...
unsigned int | bitsPerPixel
| The average number of bits per pixel. More...
enum ColourEncoding | colourEncoding
| The colour encoding type. More...
bool | packed
| Tell if multiple pixels are packed in the same bytes. More...
unsigned int | pixelsPerGroup
| The number of pixels in a pixel group. More...
std::array< Plane, 3 > | planes
| Information about pixels for each plane. More...

## Detailed Description

Information about pixel formats.

The PixelFormatInfo class groups together information describing a pixel format. It facilitates handling of pixel formats by providing data commonly used in pipeline handlers.

## Member Enumeration Documentation

## ◆ ColourEncoding

enum libcamera::PixelFormatInfo::ColourEncoding

The colour encoding type.

Enumerator
ColourEncodingRGB | RGB colour encoding.
ColourEncodingYUV | YUV colour encoding.
ColourEncodingRAW | RAW colour encoding.

## Member Function Documentation

## ◆ frameSize() [1/2]

unsigned int libcamera::PixelFormatInfo::frameSize | ( | const Size & | size,
|  | const std::array< unsigned int, 3 > & | strides
| ) |  | const

Compute the number of bytes necessary to store a frame.

Parameters

  [in] | size | The size of the frame, in pixels
  [in] | strides | The strides to use for each plane

This function is an overloaded version that takes custom strides for each plane, to be used when the device has custom alignment constraints that can't be described by just an alignment value.

Returns
  The number of bytes necessary to store the frame, or 0 if the PixelFormatInfo instance is not valid

## ◆ frameSize() [2/2]

unsigned int libcamera::PixelFormatInfo::frameSize | ( | const Size & | size,
|  | unsigned int | align = `1`
| ) |  | const

Compute the number of bytes necessary to store a frame.

Parameters

  [in] | size | The size of the frame, in pixels
  [in] | align | The stride alignment, in bytes (1 for default alignment)

The frame size is computed by adding the size of all planes, as computed by planeSize(), using the specified alignment constraints for all planes. For more complex stride constraints, use the frameSize() overloaded version that takes an array of stride values.

See also
  planeSize()

Returns
  The number of bytes necessary to store the frame, or 0 if the PixelFormatInfo instance is not valid

## ◆ info() [1/3]

const PixelFormatInfo & libcamera::PixelFormatInfo::info | ( | const PixelFormat & | format | ) |
| static

Retrieve information about a pixel format.

Parameters

  [in] | format | The pixel format

Returns
  The PixelFormatInfo describing the format if known, or an invalid PixelFormatInfo otherwise

## ◆ info() [2/3]

const PixelFormatInfo & libcamera::PixelFormatInfo::info | ( | const std::string & | name | ) |
| static

Retrieve information about a pixel format.

Parameters

  [in] | name | The name of pixel format

Returns
  The PixelFormatInfo describing the PixelFormat matching the name if known, or an invalid PixelFormatInfo otherwise

## ◆ info() [3/3]

const PixelFormatInfo & libcamera::PixelFormatInfo::info | ( | const V4L2PixelFormat & | format | ) |
| static

Retrieve information about a V4L2 pixel format.

Parameters

  [in] | format | The V4L2 pixel format

Returns
  The PixelFormatInfo describing the V4L2 format if known, or an invalid PixelFormatInfo otherwise

## ◆ isValid()

bool libcamera::PixelFormatInfo::isValid | ( |  | ) | const
| inline

Check if the pixel format info is valid.

Returns
  True if the pixel format info is valid, false otherwise

## ◆ numPlanes()

unsigned int libcamera::PixelFormatInfo::numPlanes | ( |  | ) | const

Retrieve the number of planes represented by the format.

Returns
  The number of planes used by the format

## ◆ planeSize() [1/2]

unsigned int libcamera::PixelFormatInfo::planeSize | ( | const Size & | size,
|  | unsigned int | plane,
|  | unsigned int | align = `1`
| ) |  | const

Compute the number of bytes necessary to store a plane of a frame.

Parameters

  [in] | size | The size of the frame, in pixels
  [in] | plane | The plane index
  [in] | align | The stride alignment, in bytes (1 for default alignment)

The plane size is computed by multiplying the line stride and the frame height, taking subsampling and other format characteristics into account. Stride alignment constraints may be specified through the align parameter.

See also
  stride()

Returns
  The number of bytes necessary to store the plane, or 0 if the PixelFormatInfo instance is not valid or the plane number isn't valid for the format

## ◆ planeSize() [2/2]

unsigned int libcamera::PixelFormatInfo::planeSize | ( | unsigned int | height,
|  | unsigned int | plane,
|  | unsigned int | stride
| ) |  | const

Compute the number of bytes necessary to store a plane of a frame.

Parameters

  [in] | height | The height of the frame, in pixels
  [in] | plane | The plane index
  [in] | stride | The plane stride, in bytes

The plane size is computed by multiplying the line stride and the frame height, taking subsampling and other format characteristics into account. Stride alignment constraints may be specified through the align parameter.

Returns
  The number of bytes necessary to store the plane, or 0 if the PixelFormatInfo instance is not valid or the plane number isn't valid for the format

## ◆ stride()

unsigned int libcamera::PixelFormatInfo::stride | ( | unsigned int | width,
|  | unsigned int | plane,
|  | unsigned int | align = `1`
| ) |  | const

Compute the stride.

Parameters

  [in] | width | The width of the line, in pixels
  [in] | plane | The index of the plane whose stride is to be computed
  [in] | align | The stride alignment, in bytes

The stride is the number of bytes necessary to store a full line of a frame, including padding at the end of the line. This function takes into account the alignment constraints intrinsic to the format (for instance, the SGRBG12_CSI2P format stores two 12-bit pixels in 3 bytes, and thus has a required stride alignment of 3 bytes). Additional alignment constraints may be specified through the align parameter, which will cause the stride to be rounded up to the next multiple of align.

For multi-planar formats, different planes may have different stride values. The plane parameter selects which plane to compute the stride for.

Returns
  The number of bytes necessary to store a line, or 0 if the PixelFormatInfo instance or the plane is not valid

## Member Data Documentation

## ◆ bitsPerPixel

libcamera::PixelFormatInfo::bitsPerPixel

The average number of bits per pixel.

The number per pixel averages the total number of bits for all colour components over the whole image, excluding any padding bits or padding pixels.

For formats that store pixels with bit padding within words, only the effective bits are taken into account. For instance, 12-bit Bayer data stored in two bytes per pixel report 12, not 16, in this field.

Formats that don't have a fixed number of bits per pixel, such as compressed formats, report 0 in this field.

## ◆ colourEncoding

libcamera::PixelFormatInfo::colourEncoding

The colour encoding type.

## ◆ format

libcamera::PixelFormatInfo::format

The PixelFormat described by this instance.

## ◆ name

libcamera::PixelFormatInfo::name

The format name as a human-readable string, used as the test representation of the PixelFormat.

## ◆ packed

libcamera::PixelFormatInfo::packed

Tell if multiple pixels are packed in the same bytes.

Packed formats are defined as storing data from multiple pixels in the same bytes. For instance, 12-bit Bayer data with two pixels stored in three bytes is packed, while the same data stored with 4 bits of padding in two bytes per pixel is not packed.

## ◆ pixelsPerGroup

libcamera::PixelFormatInfo::pixelsPerGroup

The number of pixels in a pixel group.

A pixel group is defined as the minimum number of pixels (including padding) necessary in a row when the image has only one column of effective pixels. pixelsPerGroup refers to this value. PixelFormatInfo::Plane::bytesPerGroup, then, refers to the number of bytes that a pixel group consumes. This definition of a pixel group allows simple calculation of stride, as ceil(width / pixelsPerGroup) * bytesPerGroup. These values are determined only in terms of a row. The ceiling accounts for padding.

A pixel group has a second constraint, such that the pixel group (bytesPerGroup and pixelsPerGroup) is the smallest repeatable unit. What this means is that, for example, in the IPU3 formats, if there is only one column of effective pixels, it looks like it could be fit in 5 bytes with 3 padding pixels (for a total of 4 pixels over 5 bytes). However, this unit is not repeatable, as at the 7th group in the same row, the pattern is broken. Therefore, the pixel group for IPU3 formats must be 25 pixels over 32 bytes.

For example, for something simple like BGR888, it is self-explanatory: the pixel group size is 1, and the bytes necessary is 3, and there is only one plane with no (= 1) vertical subsampling. For YUYV, the CbCr pair is shared between two pixels, so even if you have only one pixel, you would still need a padded second Y sample, therefore the pixel group size is 2, and bytes necessary is 4. YUYV also has no vertical subsampling. NV12 has a pixel group size of 2 pixels, due to the CbCr plane. The bytes per group then, for both planes, is 2. The first plane has no vertical subsampling, but the second plane is subsampled by a factor of 2.

The IPU3 raw Bayer formats are single-planar, and have a pixel group size of 25, consuming 32 bytes, due to the packing pattern being repeated in memory every 32 bytes. The IPU3 hardware, however, has an additional constraint on the DMA burst size, requiring lines to be multiple of 64 bytes. This isn't an intrinsic property of the formats and is thus not reflected here. It is instead enforced by the corresponding pipeline handler.

## ◆ planes

libcamera::PixelFormatInfo::planes

Information about pixels for each plane.

See also
  PixelFormatInfo::Plane

## ◆ v4l2Formats

libcamera::PixelFormatInfo::v4l2Formats

The V4L2 pixel formats corresponding to the PixelFormat.

Multiple V4L2 formats may exist for one PixelFormat, as V4L2 defines separate 4CCs for contiguous and non-contiguous versions of the same image format.

The documentation for this class was generated from the following files:

- include/libcamera/internal/formats.h
- src/libcamera/formats.cpp