Information about pixel formats. More...

Collaboration diagram for libcamera::PixelFormatInfo:

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 text representation of the PixelFormat.

PixelFormat	format
	The PixelFormat described by this instance.

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.

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,
		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

◆ frameSize() [2/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

◆ 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 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

◆ info() [3/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

◆ 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 of bits 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.

◆ 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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ ColourEncoding

Member Function Documentation

◆ frameSize() [1/2]

◆ frameSize() [2/2]

◆ info() [1/3]

◆ info() [2/3]

◆ info() [3/3]

◆ isValid()

◆ numPlanes()

◆ planeSize() [1/2]

◆ planeSize() [2/2]

◆ stride()

Member Data Documentation

◆ bitsPerPixel

◆ packed

◆ pixelsPerGroup

◆ planes

◆ v4l2Formats