QColorSpace Class

The QColorSpace class provides a color space abstraction. More...

Header: #include <QColorSpace>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Public Types

(since 6.8) enum class ColorModel { Undefined, Rgb, Gray, Cmyk }
enum NamedColorSpace { SRgb, SRgbLinear, AdobeRgb, DisplayP3, ProPhotoRgb, …, Bt2100Hlg }
enum class Primaries { Custom, SRgb, AdobeRgb, DciP3D65, ProPhotoRgb, Bt2020 }
enum class TransferFunction { Custom, Linear, Gamma, SRgb, ProPhotoRgb, …, Hlg }
(since 6.8) enum class TransformModel { ThreeComponentMatrix, ElementListProcessing }

Public Functions

QColorSpace()
QColorSpace(QColorSpace::NamedColorSpace namedColorSpace)
(since 6.1) QColorSpace(QColorSpace::Primaries gamut, const QList<uint16_t> &transferFunctionTable)
QColorSpace(QColorSpace::Primaries primaries, float gamma)
(since 6.8) QColorSpace(QPointF whitePoint, const QList<uint16_t> &transferFunctionTable)
QColorSpace(QColorSpace::Primaries primaries, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
(since 6.8) QColorSpace(QPointF whitePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
(since 6.1) QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, const QList<uint16_t> &transferFunctionTable)
QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
(since 6.1) QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable)
(since 6.8) QColorSpace::ColorModel colorModel() const
(since 6.2) QString description() const
float gamma() const
QByteArray iccProfile() const
bool isValid() const
(since 6.8) bool isValidTarget() const
QColorSpace::Primaries primaries() const
(since 6.2) void setDescription(const QString &description)
void setPrimaries(QColorSpace::Primaries primariesId)
void setPrimaries(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint)
(since 6.1) void setTransferFunction(const QList<uint16_t> &transferFunctionTable)
void setTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
(since 6.1) void setTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable)
(since 6.8) void setWhitePoint(QPointF whitePoint)
void swap(QColorSpace &other)
QColorSpace::TransferFunction transferFunction() const
(since 6.8) QColorSpace::TransformModel transformModel() const
QColorTransform transformationToColorSpace(const QColorSpace &colorspace) const
(since 6.8) QPointF whitePoint() const
(since 6.1) QColorSpace withTransferFunction(const QList<uint16_t> &transferFunctionTable) const
QColorSpace withTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f) const
(since 6.1) QColorSpace withTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable) const
QVariant operator QVariant() const

Static Public Members

QColorSpace fromIccProfile(const QByteArray &iccProfile)
bool operator!=(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
QDataStream &operator<<(QDataStream &stream, const QColorSpace &colorSpace)
bool operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
QDataStream &operator>>(QDataStream &stream, QColorSpace &colorSpace)

Detailed Description

Color values can be interpreted in different ways, and based on the interpretation can live in different spaces. We call this color spaces.

QColorSpace provides access to creating several predefined color spaces and can generate QColorTransforms for converting colors from one color space to another.

QColorSpace can also represent color spaces defined by ICC profiles or embedded in images, that do not otherwise fit the predefined color spaces.

A color space can generally speaking be conceived as a combination of set of primary colors and a transfer function. The primaries defines the axes of the color space, and the transfer function how values are mapped on the axes. The primaries are for ColorModel::Rgb color spaces defined by three primary colors that represent exactly how red, green, and blue look in this particular color space, and a white color that represents where and how bright pure white is. For grayscale color spaces, only a single white primary is needed. The range of colors expressible by the primary colors is called the gamut, and a color space that can represent a wider range of colors is also known as a wide-gamut color space.

The transfer function or gamma curve determines how each component in the color space is encoded. These are used because human perception does not operate linearly, and the transfer functions try to ensure that colors will seem evenly spaced to human eyes.

Member Type Documentation

[since 6.8] enum class QColorSpace::ColorModel

Defines the color model used by the color space data.

ConstantValueDescription
QColorSpace::ColorModel::Undefined0No color model
QColorSpace::ColorModel::Rgb1An RGB color model with red, green, and blue colors. Can apply to RGB and grayscale data.
QColorSpace::ColorModel::Gray2A gray scale color model. Can only apply to grayscale data.
QColorSpace::ColorModel::Cmyk3Can only represent color data defined with cyan, magenta, yellow, and black colors. In effect only QImage::Format_CMYK32. Note Cmyk color spaces will be TransformModel::ElementListProcessing.

This enum was introduced in Qt 6.8.

enum QColorSpace::NamedColorSpace

Predefined color spaces.

ConstantValueDescription
QColorSpace::SRgb1The sRGB color space, which Qt operates in by default. It is a close approximation of how most classic monitors operate, and a mode most software and hardware support. ICC registration of sRGB.
QColorSpace::SRgbLinear2The sRGB color space with linear gamma. Useful for gamma-corrected blending.
QColorSpace::AdobeRgb3The Adobe RGB color space is a classic wide-gamut color space, using a gamma of 2.2. ICC registration of Adobe RGB (1998)
QColorSpace::DisplayP34A color-space using the primaries of DCI-P3, but with the whitepoint and transfer function of sRGB. Common in modern wide-gamut screens. ICC registration of DCI-P3
QColorSpace::ProPhotoRgb5The Pro Photo RGB color space, also known as ROMM RGB is a very wide gamut color space. ICC registration of ROMM RGB
QColorSpace::Bt2020 (since Qt 6.8)6BT.2020, also known as Rec.2020 is a basic colorspace of HDR TVs. ICC registration of BT.2020
QColorSpace::Bt2100Pq (since Qt 6.8)7BT.2100(PQ), also known as Rec.2100 or HDR10 is an HDR encoding with the same primaries as Bt2020 but using the Perceptual Quantizer transfer function. ICC registration of BT.2100
QColorSpace::Bt2100Hlg (since Qt 6.8)8BT.2100 (HLG) is an HDR encoding with the same primaries as Bt2020 but using the Hybrid Log-Gamma transfer function.

enum class QColorSpace::Primaries

Predefined sets of primary colors.

ConstantValueDescription
QColorSpace::Primaries::Custom0The primaries are undefined or does not match any predefined sets.
QColorSpace::Primaries::SRgb1The sRGB primaries
QColorSpace::Primaries::AdobeRgb2The Adobe RGB primaries
QColorSpace::Primaries::DciP3D653The DCI-P3 primaries with the D65 whitepoint
QColorSpace::Primaries::ProPhotoRgb4The ProPhoto RGB primaries with the D50 whitepoint
QColorSpace::Primaries::Bt2020 (since Qt 6.8)5The BT.2020 primaries with a D65 whitepoint

enum class QColorSpace::TransferFunction

Predefined transfer functions or gamma curves.

ConstantValueDescription
QColorSpace::TransferFunction::Custom0The custom or null transfer function
QColorSpace::TransferFunction::Linear1The linear transfer functions
QColorSpace::TransferFunction::Gamma2A transfer function that is a real gamma curve based on the value of gamma()
QColorSpace::TransferFunction::SRgb3The sRGB transfer function, composed of linear and gamma parts
QColorSpace::TransferFunction::ProPhotoRgb4The ProPhoto RGB transfer function, composed of linear and gamma parts
QColorSpace::TransferFunction::Bt2020 (since Qt 6.8)5The BT.2020 transfer function, composited of linear and gamma parts
QColorSpace::TransferFunction::St2084 (since Qt 6.8)6The SMPTE ST 2084 transfer function, also known Perceptual Quantizer(PQ).
QColorSpace::TransferFunction::Hlg (since Qt 6.8)7The Hybrid log-gamma transfer function.

[since 6.8] enum class QColorSpace::TransformModel

Defines the processing model used for color space transforms.

ConstantValueDescription
QColorSpace::TransformModel::ThreeComponentMatrix0The transform consist of a matrix calculated from primaries and set of transfer functions for each color channel. This is very fast and used by all predefined color spaces. Any color space on this form is reversible and always both valid sources and targets.
QColorSpace::TransformModel::ElementListProcessing1The transforms are one or two lists of processing elements that can do many things, each list only process either to the connection color space or from it. This is very flexible, but rather slow, and can only be set by reading ICC profiles (See fromIccProfile()). Since the two lists are separate a color space on this form can be a valid source, but not necessarily also a valid target. When changing either primaries or transfer function on a color space on this type it will reset to an empty ThreeComponentMatrix form.

This enum was introduced in Qt 6.8.

Member Function Documentation

[noexcept] QColorSpace::QColorSpace()

Creates a new colorspace object that represents an undefined and invalid colorspace.

QColorSpace::QColorSpace(QColorSpace::NamedColorSpace namedColorSpace)

Creates a new colorspace object that represents a namedColorSpace.

[since 6.1] QColorSpace::QColorSpace(QColorSpace::Primaries gamut, const QList<uint16_t> &transferFunctionTable)

Creates a custom color space with the primaries gamut, using a custom transfer function described by transferFunctionTable.

The table should contain at least 2 values, and contain an monotonically increasing list of values from 0 to 65535.

This function was introduced in Qt 6.1.

QColorSpace::QColorSpace(QColorSpace::Primaries primaries, float gamma)

Creates a custom color space with the primaries primaries, using a gamma transfer function of gamma.

[explicit, since 6.8] QColorSpace::QColorSpace(QPointF whitePoint, const QList<uint16_t> &transferFunctionTable)

Creates a custom grayscale color space with white point whitePoint, and using the custom transfer function described by transferFunctionTable.

This function was introduced in Qt 6.8.

QColorSpace::QColorSpace(QColorSpace::Primaries primaries, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)

Creates a custom color space with the primaries primaries, using the transfer function transferFunction and optionally gamma.

[explicit, since 6.8] QColorSpace::QColorSpace(QPointF whitePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)

Creates a custom grayscale color space with the white point whitePoint, using the transfer function transferFunction and optionally gamma.

This function was introduced in Qt 6.8.

[since 6.1] QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, const QList<uint16_t> &transferFunctionTable)

Creates a custom color space with primaries based on the chromaticities of the primary colors whitePoint, redPoint, greenPoint and bluePoint, and using the custom transfer function described by transferFunctionTable.

This function was introduced in Qt 6.1.

QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)

Creates a custom colorspace with a primaries based on the chromaticities of the primary colors whitePoint, redPoint, greenPoint and bluePoint, and using the transfer function transferFunction and optionally gamma.

[since 6.1] QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable)

Creates a custom color space with primaries based on the chromaticities of the primary colors whitePoint, redPoint, greenPoint and bluePoint, and using the custom transfer functions described by redTransferFunctionTable, greenTransferFunctionTable, and blueTransferFunctionTable.

This function was introduced in Qt 6.1.

[noexcept, since 6.8] QColorSpace::ColorModel QColorSpace::colorModel() const

Returns the color model this color space can represent

This function was introduced in Qt 6.8.

[noexcept, since 6.2] QString QColorSpace::description() const

Returns the name or short description. If a description hasn't been given in setDescription(), the original name of the profile is returned if the profile is unmodified, a guessed name is returned if the profile has been recognized as a known color space, otherwise an empty string is returned.

This function was introduced in Qt 6.2.

See also setDescription().

[static] QColorSpace QColorSpace::fromIccProfile(const QByteArray &iccProfile)

Creates a QColorSpace from ICC profile iccProfile.

Note: Not all ICC profiles are supported. QColorSpace only supports RGB or Gray ICC profiles.

If the ICC profile is not supported an invalid QColorSpace is returned where you can still read the original ICC profile using iccProfile().

See also iccProfile().

[noexcept] float QColorSpace::gamma() const

Returns the gamma value of color spaces with TransferFunction::Gamma, an approximate gamma value for other predefined color spaces, or 0.0 if no approximate gamma is known.

See also transferFunction().

QByteArray QColorSpace::iccProfile() const

Returns an ICC profile representing the color space.

If the color space was generated from an ICC profile, that profile is returned, otherwise one is generated.

Note: Even invalid color spaces may return the ICC profile if they were generated from one, to allow applications to implement wider support themselves.

See also fromIccProfile().

[noexcept] bool QColorSpace::isValid() const

Returns true if the color space is valid. For a color space with TransformModel::ThreeComponentMatrix that means both primaries and transfer functions set, and implies isValidTarget(). For a color space with TransformModel::ElementListProcessing it means it has a valid source transform, to check if it also a valid target color space use isValidTarget().

See also isValidTarget().

[noexcept, since 6.8] bool QColorSpace::isValidTarget() const

Returns true if the color space is a valid target color space.

This function was introduced in Qt 6.8.

[noexcept] QColorSpace::Primaries QColorSpace::primaries() const

Returns the predefined primaries of the color space or primaries::Custom if it doesn't match any of them.

See also setPrimaries().

[since 6.2] void QColorSpace::setDescription(const QString &description)

Sets the name or short description of the color space to description.

If set to empty description() will return original or guessed descriptions instead.

This function was introduced in Qt 6.2.

See also description().

void QColorSpace::setPrimaries(QColorSpace::Primaries primariesId)

Sets the primaries to those of the primariesId set.

See also primaries().

void QColorSpace::setPrimaries(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint)

Set primaries to the chromaticities of whitePoint, redPoint, greenPoint and bluePoint.

See also primaries().

[since 6.1] void QColorSpace::setTransferFunction(const QList<uint16_t> &transferFunctionTable)

Sets the transfer function to transferFunctionTable.

This function was introduced in Qt 6.1.

See also transferFunction() and withTransferFunction().

void QColorSpace::setTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)

Sets the transfer function to transferFunction and gamma.

See also transferFunction(), gamma(), and withTransferFunction().

[since 6.1] void QColorSpace::setTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable)

Sets the transfer functions to redTransferFunctionTable, greenTransferFunctionTable and blueTransferFunctionTable.

This function was introduced in Qt 6.1.

See also withTransferFunctions().

[since 6.8] void QColorSpace::setWhitePoint(QPointF whitePoint)

Sets the white point to used for this color space to whitePoint.

This function was introduced in Qt 6.8.

See also whitePoint().

[noexcept] void QColorSpace::swap(QColorSpace &other)

Swaps color space other with this color space. This operation is very fast and never fails.

[noexcept] QColorSpace::TransferFunction QColorSpace::transferFunction() const

Returns the predefined transfer function of the color space or TransferFunction::Custom if it doesn't match any of them.

See also gamma(), setTransferFunction(), and withTransferFunction().

[noexcept, since 6.8] QColorSpace::TransformModel QColorSpace::transformModel() const

Returns the transfrom processing model used for this color space.

This function was introduced in Qt 6.8.

QColorTransform QColorSpace::transformationToColorSpace(const QColorSpace &colorspace) const

Generates and returns a color space transformation from this color space to colorspace.

[since 6.8] QPointF QColorSpace::whitePoint() const

Returns the white point used for this color space. Returns a null QPointF if not defined.

This function was introduced in Qt 6.8.

See also setWhitePoint().

[since 6.1] QColorSpace QColorSpace::withTransferFunction(const QList<uint16_t> &transferFunctionTable) const

Returns a copy of this color space, except using the transfer function described by transferFunctionTable.

This function was introduced in Qt 6.1.

See also transferFunction() and setTransferFunction().

QColorSpace QColorSpace::withTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f) const

Returns a copy of this color space, except using the transfer function transferFunction and gamma.

See also transferFunction(), gamma(), and setTransferFunction().

[since 6.1] QColorSpace QColorSpace::withTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable) const

Returns a copy of this color space, except using the transfer functions described by redTransferFunctionTable, greenTransferFunctionTable and blueTransferFunctionTable.

This function was introduced in Qt 6.1.

See also setTransferFunctions().

QVariant QColorSpace::operator QVariant() const

Returns the color space as a QVariant.

Related Non-Members

bool operator!=(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)

Returns true if colorspace colorSpace1 is not equal to colorspace colorSpace2; otherwise returns false

QDataStream &operator<<(QDataStream &stream, const QColorSpace &colorSpace)

Writes the given colorSpace to the given stream as an ICC profile.

See also QColorSpace::iccProfile() and Serializing Qt Data Types.

bool operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)

Returns true if colorspace colorSpace1 is equal to colorspace colorSpace2; otherwise returns false

QDataStream &operator>>(QDataStream &stream, QColorSpace &colorSpace)

Reads a color space from the given stream and stores it in the given colorSpace.

See also QColorSpace::fromIccProfile() and Serializing Qt Data Types.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.