libcamera::ColorSpace Class Reference

Class to describe a color space. More...

Collaboration diagram for libcamera::ColorSpace:

Public Types
enum	Primaries
	The color primaries for this color space.
enum	TransferFunction
	The transfer function used for this color space.
enum	YcbcrEncoding
	The Y'CbCr encoding.
enum	Range
	The range (sometimes "quantisation") for this color space.

Public Member Functions
constexpr	ColorSpace (Primaries p, TransferFunction t, YcbcrEncoding e, Range r)
	Construct a ColorSpace from explicit values. More...
std::string	toString () const
	Assemble and return a readable string representation of the ColorSpace. More...
bool	adjust (PixelFormat format)
	Adjust the color space to match a pixel format. More...

Static Public Member Functions
static std::string	toString (const std::optional< ColorSpace > &colorSpace)
	Assemble and return a readable string representation of an optional ColorSpace. More...
static std::optional< ColorSpace >	fromString (const std::string &str)
	Construct a color space from a string. More...

Public Attributes
Primaries	primaries
	The color primaries of this color space.
TransferFunction	transferFunction
	The transfer function used by this color space.
YcbcrEncoding	ycbcrEncoding
	The Y'CbCr encoding used by this color space.
Range	range
	The pixel range used with by color space.

Static Public Attributes
static const ColorSpace	Raw
	A constant representing a raw color space (from a sensor)
static const ColorSpace	Srgb
	A constant representing the sRGB color space (RGB formats only)
static const ColorSpace	Sycc
	A constant representing the sYCC color space, typically used for encoding JPEG images.
static const ColorSpace	Smpte170m
	A constant representing the SMPTE170M color space.
static const ColorSpace	Rec709
	A constant representing the Rec.709 color space.
static const ColorSpace	Rec2020
	A constant representing the Rec.2020 color space.

Detailed Description

Class to describe a color space.

The ColorSpace class defines the color primaries, the transfer function, the Y'CbCr encoding associated with the color space, and the range (sometimes also referred to as the quantisation) of the color space.

Certain combinations of these fields form well-known standard color spaces such as "sRGB" or "Rec709".

In the strictest sense a "color space" formally only refers to the color primaries and white point. Here, however, the ColorSpace class adopts the common broader usage that includes the transfer function, Y'CbCr encoding method and quantisation.

More information on color spaces is available in the V4L2 documentation, see in particular

• sRGB
• JPEG
• SMPTE 170M
• Rec.709
• Rec.2020

Note that there is no guarantee of a 1:1 mapping between color space names and definitions in libcamera and V4L2. Two notable differences are

• The sRGB libcamera color space is defined for RGB formats only with no Y'CbCr encoding and a full quantization range, while the V4L2 SRGB color space has a Y'CbCr encoding and a limited quantization range.
• The sYCC libcamera color space is called JPEG in V4L2 due to historical reasons.

Todo:

Define the color space fully in the libcamera API to avoid referencing V4L2

Constructor & Destructor Documentation

ColorSpace()

libcamera::ColorSpace::ColorSpace ( Primaries  p, TransferFunction  t, YcbcrEncoding  e, Range  r  )

inline

Construct a ColorSpace from explicit values.

Parameters

[in]	p	The color primaries
[in]	t	The transfer function for the color space
[in]	e	The Y'CbCr encoding
[in]	r	The range of the pixel values in this color space

Member Function Documentation

adjust()

bool libcamera::ColorSpace::adjust

(

PixelFormat

format

)

Adjust the color space to match a pixel format.

Parameters

[in]

format

The pixel format

Not all combinations of pixel formats and color spaces make sense. For instance, nobody uses a limited quantization range with raw Bayer formats, and the YcbcrEncoding::None encoding isn't valid for YUV formats. This function adjusts the ColorSpace to make it compatible with the given format, by applying the following rules:

• The color space for RAW formats must be Raw.
• The Y'CbCr encoding and quantization range for RGB formats must be YcbcrEncoding::None and Range::Full respectively.
• The Y'CbCr encoding for YUV formats must not be YcbcrEncoding::None. The best encoding is in that case guessed based on the primaries and transfer function.

Returns

True if the color space has been adjusted, or false if it was already compatible with the format and hasn't been changed

fromString()

std::optional< ColorSpace > libcamera::ColorSpace::fromString ( const std::string &  str )

static

Construct a color space from a string.

Parameters

[in]

str

The string

The string str can contain the name of a well-known color space, or be made of the four color space components separated by a '/' character, ordered as

primaries '/' transferFunction '/' ycbcrEncoding '/' range 

Any failure to parse the string, either because it doesn't match the expected format, or because the one of the names isn't recognized, will cause this function to return std::nullopt.

Returns

The ColorSpace corresponding to the string, or std::nullopt if the string doesn't describe a known color space

toString() [1/2]

std::string libcamera::ColorSpace::toString

(

)

const

Assemble and return a readable string representation of the ColorSpace.

If the color space matches a standard ColorSpace (such as ColorSpace::Sycc) then the short name of the color space ("sYCC") is returned. Otherwise the four constituent parts of the ColorSpace are assembled into a longer string.

Returns

A string describing the ColorSpace

toString() [2/2]

std::string libcamera::ColorSpace::toString ( const std::optional< ColorSpace > &  colorSpace )

static

Assemble and return a readable string representation of an optional ColorSpace.

This is a convenience helper to easily obtain a string representation for a ColorSpace in parts of the libcamera API where it is stored in a std::optional<>. If the ColorSpace is set, this function returns colorSpace.toString(), otherwise it returns "Unset".

Returns

A string describing the optional ColorSpace

---

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

• include/libcamera/color_space.h
• src/libcamera/color_space.cpp