libcamera  v0.2.0+85-1c5830a9
Supporting cameras in Linux since 2019
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:
Collaboration graph
[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 PixelFormatInfoinfo (const PixelFormat &format)
 Retrieve information about a pixel format. More...
 
static const PixelFormatInfoinfo (const V4L2PixelFormat &format)
 Retrieve information about a V4L2 pixel format. More...
 
static const PixelFormatInfoinfo (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< V4L2PixelFormatv4l2Formats
 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

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]sizeThe size of the frame, in pixels
[in]alignThe 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]sizeThe size of the frame, in pixels
[in]stridesThe 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]formatThe 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]formatThe 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]nameThe 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]sizeThe size of the frame, in pixels
[in]planeThe plane index
[in]alignThe 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]heightThe height of the frame, in pixels
[in]planeThe plane index
[in]strideThe 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]widthThe width of the line, in pixels
[in]planeThe index of the plane whose stride is to be computed
[in]alignThe 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: