template<class T>
Magnum::Math::Color3 class

Color in linear RGB color space.

The class can store either a floating-point or an integral representation of a linear RGB color. Colors in sRGB color space should not beused directly in calculations — they should be converted to linear RGB using fromSrgb(), calculation done on the linear representation and then converted back to sRGB using toSrgb().

Integral colors are assumed to be in a packed representation where the $ [0.0, 1.0] $ range is mapped to $ [0, 2^b - 1] $ with $ b $ being bit count of given integer type. Note that constructor conversion between different types (like in Vector classes) doesn't do any (un)packing, you need to use either pack() / unpack() or the integer variants of toSrgb() / fromSrgb() instead:

Color3 a{1.0f, 0.2f, 0.4f};
auto bSrgb = a.toSrgb<UnsignedByte>();  // {0xff, 0x7c, 0xaa}
auto bLinear = Math::pack<Color3ub>(a); // {0xff, 0x33, 0x66}

Conversion from and to HSV is done always using floating-point types, so hue is always in range in range $ [0.0\degree, 360.0\degree] $ , saturation and value in range $ [0.0, 1.0] $ .

Base classes

template<class T>
class Vector3
Three-component vector.

Public types

using FloatingPointType = TypeTraits<T>::FloatingPointType
Corresponding floating-point type.
using Hsv = std::tuple<Deg<FloatingPointType>, FloatingPointType, FloatingPointType> deprecated in 2019.10
HSV float color.

Public static functions

static auto red(T red = Implementation::fullChannel<T>()) -> static Color3<T> constexpr
Red color.
static auto green(T green = Implementation::fullChannel<T>()) -> static Color3<T> constexpr
Green color.
static auto blue(T blue = Implementation::fullChannel<T>()) -> static Color3<T> constexpr
Blue color.
static auto cyan(T red = T(0)) -> static Color3<T> constexpr
Cyan color.
static auto magenta(T green = T(0)) -> static Color3<T> constexpr
Magenta color.
static auto yellow(T blue = T(0)) -> static Color3<T> constexpr
Yellow color.
static auto fromHsv(const ColorHsv<FloatingPointType>& hsv) -> Color3<T>
Create RGB color from HSV representation.
static auto fromHsv(Deg<FloatingPointType> hue, FloatingPointType saturation, FloatingPointType value) -> Color3<T> deprecated in 2019.10
Create RGB color from HSV representation.
static auto fromSrgb(const Vector3<FloatingPointType>& srgb) -> Color3<T>
Create linear RGB color from sRGB representation.
template<class Integral>
static auto fromSrgb(const Vector3<Integral>& srgb) -> Color3<T>
Create linear RGB color from integral sRGB representation.
static auto fromSrgb(UnsignedInt srgb) -> Color3<T>
Create linear RGB color from 24-bit sRGB representation.
static auto fromXyz(const Vector3<FloatingPointType>& xyz) -> Color3<T>
Create RGB color from CIE XYZ representation.

Constructors, destructors, conversion operators

Color3() constexpr noexcept
Default constructor.
Color3(ZeroInitT) explicit constexpr noexcept
Construct a zero color.
Color3(NoInitT) explicit noexcept
Construct a vector without initializing the contents.
Color3(T rgb) explicit constexpr noexcept
Gray constructor.
Color3(T r, T g, T b) constexpr noexcept
Constructor.
template<class U>
Color3(const Vector<3, U>& other) explicit constexpr noexcept
Construct a vector from another of different type.
template<class U, class V = decltype(Implementation::VectorConverter<3, T, U>::from(std::declval<U>()))>
Color3(const U& other) explicit constexpr
Construct color from external representation.
Color3(const Vector<3, T>& other) constexpr noexcept
Copy constructor.

Public functions

auto toHsv() const -> ColorHsv<FloatingPointType>
Convert to HSV representation.
auto hue() const -> Deg<FloatingPointType>
Hue.
auto saturation() const -> FloatingPointType
Saturation.
auto value() const -> FloatingPointType
Value.
auto toSrgb() const -> Vector3<FloatingPointType>
Convert to sRGB representation.
template<class Integral>
auto toSrgb() const -> Vector3<Integral>
Convert to integral sRGB representation.
auto toSrgbInt() const -> UnsignedInt
Convert to 24-bit integral sRGB representation.
auto toXyz() const -> Vector3<FloatingPointType>
Convert to CIE XYZ representation.

Typedef documentation

template<class T>
typedef TypeTraits<T>::FloatingPointType Magnum::Math::Color3<T>::FloatingPointType

Corresponding floating-point type.

For HSV and other color spaces.

template<class T>
typedef std::tuple<Deg<FloatingPointType>, FloatingPointType, FloatingPointType> Magnum::Math::Color3<T>::Hsv

HSV float color.

Function documentation

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::red(T red = Implementation::fullChannel<T>()) constexpr

Red color.

Convenience alternative to e.g. Color3{red, 0.0f, 0.0f}. With floating-point underlying type equivalent to Vector3::xAxis().

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::green(T green = Implementation::fullChannel<T>()) constexpr

Green color.

Convenience alternative to e.g. Color3(0.0f, green, 0.0f). With floating-point underlying type equivalent to Vector3::yAxis().

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::blue(T blue = Implementation::fullChannel<T>()) constexpr

Blue color.

Convenience alternative to e.g. Color3{0.0f, 0.0f, blue}. With floating-point underlying type equivalent to Vector3::zAxis().

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::cyan(T red = T(0)) constexpr

Cyan color.

Convenience alternative to e.g. Color3{red, 1.0f, 1.0f}. With floating-point underlying type equivalent to Vector3::xScale().

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::magenta(T green = T(0)) constexpr

Magenta color.

Convenience alternative to e.g. Color3{1.0f, green, 1.0f}. With floating-point underlying type equivalent to Vector3::yScale().

template<class T>
static static Color3<T> Magnum::Math::Color3<T>::yellow(T blue = T(0)) constexpr

Yellow color.

Convenience alternative to e.g. Color3{1.0f, 1.0f, yellow}. With floating-point underlying type equivalent to Vector3::zScale().

template<class T>
static Color3<T> Magnum::Math::Color3<T>::fromHsv(const ColorHsv<FloatingPointType>& hsv)

Create RGB color from HSV representation.

Parameters
hsv Color in HSV color space

Hue is allowed to overflow the range $ [0.0\degree, 360.0\degree] $ , in which case it will be wrapped back to this range.

template<class T>
static Color3<T> Magnum::Math::Color3<T>::fromHsv(Deg<FloatingPointType> hue, FloatingPointType saturation, FloatingPointType value)

Create RGB color from HSV representation.

template<class T>
static Color3<T> Magnum::Math::Color3<T>::fromSrgb(const Vector3<FloatingPointType>& srgb)

Create linear RGB color from sRGB representation.

Parameters
srgb Color in sRGB color space

Applies inverse sRGB curve onto input, returning the input in linear RGB color space with D65 illuminant and 2° standard colorimetric observer.

\[ \boldsymbol{c}_\mathrm{linear} = \begin{cases} \dfrac{\boldsymbol{c}_\mathrm{sRGB}}{12.92}, & \boldsymbol{c}_\mathrm{sRGB} \le 0.04045 \\ \left( \dfrac{\boldsymbol{c}_\mathrm{sRGB} + a}{1 + a} \right)^{2.4}, & \boldsymbol{c}_\mathrm{sRGB} > 0.04045 \end{cases} \]

template<class T> template<class Integral>
static Color3<T> Magnum::Math::Color3<T>::fromSrgb(const Vector3<Integral>& srgb)

Create linear RGB color from integral sRGB representation.

Parameters
srgb Color in sRGB color space

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Useful in cases where you have for example an 8-bit sRGB representation and want to create a floating-point linear RGB color out of it:

Math::Vector3<UnsignedByte> srgb;
auto rgb = Color3::fromSrgb(srgb);

For conversion from a linear 24-bit representation (i.e, without applying the sRGB curve), use unpack():

Color3ub a{0xff, 0x33, 0x66};
auto bFromSrgb = Color3::fromSrgb(a);       // {1.0f, 0.03311f, 0.1329f}
auto bFromLinear = Math::unpack<Color3>(a); // {1.0f, 0.2f, 0.4f}

template<class T>
static Color3<T> Magnum::Math::Color3<T>::fromSrgb(UnsignedInt srgb)

Create linear RGB color from 24-bit sRGB representation.

Parameters
srgb 24-bit sRGB color

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. See fromSrgb() for more information and toSrgbInt() for an inverse operation. There's also a operator""_srgbf() that does this conversion directly from hexadecimal literals. The following two statements are equivalent:

Color3 a = Color3::fromSrgb(0xff3366);
Color3 b = 0xff3366_srgbf;

Note that the integral value is endian-dependent (the red channel being in the last byte on little-endian platforms), for conversion from endian-independent sRGB / linear representation use fromSrgb(const Vector3<Integral>&) / unpack().

template<class T>
static Color3<T> Magnum::Math::Color3<T>::fromXyz(const Vector3<FloatingPointType>& xyz)

Create RGB color from CIE XYZ representation.

Parameters
xyz Color in CIE XYZ color space

Applies transformation matrix, returning the input in linear RGB color space with D65 illuminant and 2° standard colorimetric observer.

\[ \begin{bmatrix} R_\mathrm{linear} \\ G_\mathrm{linear} \\ B_\mathrm{linear} \end{bmatrix} = \begin{bmatrix} 3.2406 & -1.5372 & -0.4986 \\ -0.9689 & 1.8758 & 0.0415 \\ 0.0557 & -0.2040 & 1.0570 \end{bmatrix} \begin{bmatrix} X \\ Y \\ Z \end{bmatrix} \]

template<class T>
Magnum::Math::Color3<T>::Color3() constexpr noexcept

Default constructor.

Equivalent to Color3(ZeroInitT).

template<class T>
Magnum::Math::Color3<T>::Color3(ZeroInitT) explicit constexpr noexcept

Construct a zero color.

All components are set to zero.

template<class T>
Magnum::Math::Color3<T>::Color3(T rgb) explicit constexpr noexcept

Gray constructor.

Parameters
rgb RGB value

template<class T>
Magnum::Math::Color3<T>::Color3(T r, T g, T b) constexpr noexcept

Constructor.

Parameters
r R value
g G value
b B value

template<class T> template<class U>
Magnum::Math::Color3<T>::Color3(const Vector<3, U>& other) explicit constexpr noexcept

Construct a vector from another of different type.

Performs only default casting on the values, no rounding or anything else. Example usage:

Vector4 floatingPoint{1.3f, 2.7f, -15.0f, 7.0f};
Vector4i integral{floatingPoint}; // {1, 2, -15, 7}

template<class T>
ColorHsv<FloatingPointType> Magnum::Math::Color3<T>::toHsv() const

Convert to HSV representation.

template<class T>
Deg<FloatingPointType> Magnum::Math::Color3<T>::hue() const

Hue.

Returns Hue in range $ [0.0\degree, 360.0\degree] $ .

template<class T>
FloatingPointType Magnum::Math::Color3<T>::saturation() const

Saturation.

Returns Saturation in range $ [0.0, 1.0] $ .

template<class T>
FloatingPointType Magnum::Math::Color3<T>::value() const

Value.

Returns Value in range $ [0.0, 1.0] $ .

template<class T>
Vector3<FloatingPointType> Magnum::Math::Color3<T>::toSrgb() const

Convert to sRGB representation.

Assuming the color is in linear RGB with D65 illuminant and 2° standard colorimetric observer, applies sRGB curve onto it, returning the color represented in sRGB color space:

\[ \boldsymbol{c}_\mathrm{sRGB} = \begin{cases} 12.92C_\mathrm{linear}, & \boldsymbol{c}_\mathrm{linear} \le 0.0031308 \\ (1 + a) \boldsymbol{c}_\mathrm{linear}^{1/2.4}-a, & \boldsymbol{c}_\mathrm{linear} > 0.0031308 \end{cases} \]

template<class T> template<class Integral>
Vector3<Integral> Magnum::Math::Color3<T>::toSrgb() const

Convert to integral sRGB representation.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Useful in cases where you have a floating-point linear RGB color and want to create for example an 8-bit sRGB representation out of it:

Color3 color;
Math::Vector3<UnsignedByte> srgb = color.toSrgb<UnsignedByte>();

For conversion to a linear 24-bit representation (i.e, without applying the sRGB curve), use pack():

Color3 a{1.0f, 0.2f, 0.4f};
auto bSrgb = a.toSrgb<UnsignedByte>();  // {0xff, 0x7c, 0xaa}
auto bLinear = Math::pack<Color3ub>(a); // {0xff, 0x33, 0x66}

template<class T>
UnsignedInt Magnum::Math::Color3<T>::toSrgbInt() const

Convert to 24-bit integral sRGB representation.

See toSrgb() const for more information. Note that the integral value is endian-dependent (the red channel being in the last byte on little-endian platforms), for conversion to an endian-independent sRGB / linear representation use toSrgb() const / pack().

template<class T>
Vector3<FloatingPointType> Magnum::Math::Color3<T>::toXyz() const

Convert to CIE XYZ representation.

Assuming the color is in linear RGB with D65 illuminant and 2° standard colorimetric observer, applies transformation matrix, returning the color in CIE XYZ color space.

\[ \begin{bmatrix} X \\ Y \\ Z \end{bmatrix} = \begin{bmatrix} 0.4124 & 0.3576 & 0.1805 \\ 0.2126 & 0.7152 & 0.0722 \\ 0.0193 & 0.1192 & 0.9505 \end{bmatrix} \begin{bmatrix} R_\mathrm{linear} \\ G_\mathrm{linear} \\ B_\mathrm{linear} \end{bmatrix} \]

Please note that x(), y() and z() do not correspond to primaries in CIE XYZ color space, but are rather aliases to r(), g() and b().

template<class T> template<class T>
Vector3<T> xyYToXyz(const Vector3<T>& xyY)

Convert color from CIE xyY representation to CIE XYZ.

\[ \begin{array}{rcl} X & = & \dfrac{Y}{y}x \\ Z & = & \dfrac{Y}{y}(1 - x - y) \end{array} \]

template<class T> template<class T>
Vector3<T> xyzToXyY(const Vector3<T>& xyz)

Convert color from CIE XYZ representation to CIE xyY.

\[ \begin{array}{rcl} x & = & \dfrac{X}{X + Y + Z} \\ y & = & \dfrac{Y}{X + Y + Z} \end{array} \]

template<class T>
Color3<UnsignedByte> operator""_rgb(unsigned long long value) constexpr

8bit-per-channel linear RGB literal

Unpacks the literal into three 8-bit values. Example usage:

using namespace Math::Literals;
Color3ub a = 0x33b27f_rgb;      // {0x33, 0xb2, 0x7f}

template<class T>
Vector3<UnsignedByte> operator""_srgb(unsigned long long value) constexpr

8bit-per-channel sRGB literal

Unpacks the literal into three 8-bit values without any colorspace conversion. Behaves identically to operator""_rgb() though it doesn't return a Color3 type to indicate that the resulting value is not linear RGB. Use this literal to document that given value is in sRGB. Example usage:

using namespace Math::Literals;
Math::Vector3<UnsignedByte> a = 0x33b27f_srgb; // {0x33, 0xb2, 0x7f}

template<class T>
Color3<Float> operator""_rgbf(unsigned long long value)

Float linear RGB literal.

Unpacks the 8-bit values into three floats. Example usage:

using namespace Math::Literals;
Color3 a = 0x33b27f_rgbf;       // {0.2f, 0.698039f, 0.498039f}

template<class T>
Color3<Float> operator""_srgbf(unsigned long long value)

Float sRGB literal.

Calls Color3::fromSrgb(UnsignedInt) on the literal value. Example usage:

using namespace Math::Literals;
Color3 a = 0x33b27f_srgbf;      // {0.0331048f, 0.445201f, 0.212231f}

template<class T>
Corrade::Utility::Debug& operator<<(Corrade::Utility::Debug& debug, const Color3<UnsignedByte>& value)

Debug output operator.

If Corrade::Utility::Debug::Flag::Color is enabled or Corrade::Utility::Debug::color was set immediately before, prints the value as an ANSI 24bit color escape sequence using two successive Unicode block characters (to have it roughly square). To preserve at least some information when text is copied, the square consists of one of the five ░▒▓█ shades, however the color is set for both foreground and background so the actual block character is indistinguishable when seen on a terminal.

If Corrade::Utility::Debug::Flag::Color is enabled and Corrade::Utility::Debug::Flag::DisableColors is set, only the shaded character is used, without any ANSI color escape sequence.

If Corrade::Utility::Debug::Flag::Color is not enabled, the value is printed as a hex color (e.g. #ff33aa). Other underlying types are handled by operator<<(Corrade::Utility::Debug&, const Vector<size, T>&).

For example, the following snippet:

Debug{Debug::Flag::Color} << 0xdcdcdc_rgb << 0xa5c9ea_rgb << 0x3bd267_rgb
    << 0xc7cf2f_rgb << 0xcd3431_rgb << 0x2f83cc_rgb << 0x747474_rgb;

prints the following on terminals that support it:

‌██ ‌██ ‌██ ‌██ ‌██ ‌▓▓ ‌▒▒