QColorSpace Class
QColorSpace 类提供了一种色彩空间的抽象实现。更多内容...
| 头文件： | #include <QColorSpace> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
- 所有成员的列表，包括继承的成员
- QColorSpace 属于绘图类。
公共类型
(since 6.9) struct | PrimaryPoints |
(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 } |
公共函数
| 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.9) | QColorSpace(const QColorSpace::PrimaryPoints &primaryPoints, 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) |
| QColorSpace(QColorSpace &&colorSpace) | |
(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.9) QColorSpace::PrimaryPoints | primaryPoints() 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.9) void | setPrimaryPoints(const QColorSpace::PrimaryPoints &primaryPoints) |
(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 |
| operator QVariant() const |
静态公共成员
| 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) |
详细说明
颜色值可以有不同的解释方式，并根据不同的解释存在于不同的空间中。我们称之为色域。
QColorSpace 提供了创建多种预定义色彩空间的功能，并能生成 QColorTransforms 以将颜色从一个色彩空间转换为另一个色彩空间。
QColorSpace 还可以表示由 ICC 配置文件定义或嵌入在图像中的色彩空间，这些色彩空间不属于预定义的色彩空间。
一般而言，色空间可视为一组原色与一个转换函数的组合。 原色定义了色彩空间的坐标轴，而转换函数则规定了值在坐标轴上的映射方式。对于ColorModel::Rgb 色彩空间，原色由三种原色定义，它们精确地表示了该特定色彩空间中红色、绿色和蓝色的外观，以及一种白色，它代表纯白色所在的位置及其亮度。 对于灰度色彩空间，仅需一个白色原色。原色所能表达的颜色范围称为色域，而能够表示更广泛颜色范围的色彩空间也被称为广色域色彩空间。
传递函数或伽马曲线决定了色彩空间中每个分量的编码方式。之所以采用这些函数，是因为人类的感知并非线性运作，而传递函数旨在确保颜色在人眼中看起来间隔均匀。
成员类型文档
[since 6.8] enum class QColorSpace::ColorModel
定义色彩空间数据所使用的色彩模型。
| 常量 | 值 | 描述 |
|---|---|---|
QColorSpace::ColorModel::Undefined | 0 | 无色彩模型 |
QColorSpace::ColorModel::Rgb | 1 | 包含红、绿、蓝三原色的 RGB 色彩模型。可应用于 RGB 和灰度数据。 |
QColorSpace::ColorModel::Gray | 2 | 一种灰度颜色模型。仅适用于灰度数据。 |
QColorSpace::ColorModel::Cmyk | 3 | 仅能表示由青色、品红色、黄色和黑色定义的颜色数据。实际上仅支持 QImage::Format_CMYK32。注意：CMYK 色彩空间将采用TransformModel::ElementListProcessing 。 |
该枚举在 Qt 6.8 中引入。
enum QColorSpace::NamedColorSpace
预定义色彩空间。
| 常量 | 值 | 描述 |
|---|---|---|
QColorSpace::SRgb | 1 | sRGB 色彩空间，这是 Qt 的默认工作模式。它非常接近大多数经典显示器的运行方式，也是大多数软件和硬件支持的模式。sRGB 的 ICC 注册信息。 |
QColorSpace::SRgbLinear | 2 | 具有线性伽马的 sRGB 色彩空间。适用于伽马校正后的混合操作。 |
QColorSpace::AdobeRgb | 3 | Adobe RGB 色彩空间是一种经典的广色域色彩空间，采用 2.2 的伽马值。Adobe RGB (1998) 的 ICC 配置文件 |
QColorSpace::DisplayP3 | 4 | 一种采用 DCI-P3 原色，但白点和传递函数与 sRGB 相同的色彩空间。常见于现代广色域屏幕。DCI-P3 的 ICC 注册 |
QColorSpace::ProPhotoRgb | 5 | Pro Photo RGB 色彩空间，也称为 ROMM RGB，是一种色域非常宽的色彩空间。ROMM RGB 的 ICC 注册 |
QColorSpace::Bt2020 (since Qt 6.8) | 6 | BT.2020，也称为 Rec.2020，是 HDR 电视的基础色彩空间。BT.2020 的 ICC 注册 |
QColorSpace::Bt2100Pq (since Qt 6.8) | 7 | BT.2100(PQ)，也称为 Rec.2100 或 HDR10，是一种 HDR 编码方案，其原色与 BT.2020 相同，但采用感知量化器（Perceptual Quantizer）传递函数。BT.2100 的 ICC 注册 |
QColorSpace::Bt2100Hlg (since Qt 6.8) | 8 | BT.2100 (HLG) 是一种 HDR 编码标准，其原色与 BT.2020 相同，但采用混合对数伽马 (HLG) 传输函数。 |
enum class QColorSpace::Primaries
预定义的原色集合。
| 常量 | 值 | 描述 |
|---|---|---|
QColorSpace::Primaries::Custom | 0 | 原色未定义，或与任何预定义集合都不匹配。 |
QColorSpace::Primaries::SRgb | 1 | sRGB 原色 |
QColorSpace::Primaries::AdobeRgb | 2 | Adobe RGB 原色 |
QColorSpace::Primaries::DciP3D65 | 3 | 采用 D65 白点的 DCI-P3 原色 |
QColorSpace::Primaries::ProPhotoRgb | 4 | 采用 D50 白点的 ProPhoto RGB 原色 |
QColorSpace::Primaries::Bt2020 (since Qt 6.8) | 5 | 采用 D65 白点的 BT.2020 原色 |
enum class QColorSpace::TransferFunction
预定义的传递函数或伽马曲线。
| 常数 | 值 | 描述 |
|---|---|---|
QColorSpace::TransferFunction::Custom | 0 | 自定义或空传递函数 |
QColorSpace::TransferFunction::Linear | 1 | 线性传递函数 |
QColorSpace::TransferFunction::Gamma | 2 | 基于gamma() 值的实数伽马曲线传递函数 |
QColorSpace::TransferFunction::SRgb | 3 | 由线性部分和伽马部分组成的sRGB传递函数 |
QColorSpace::TransferFunction::ProPhotoRgb | 4 | 由线性部分和伽马部分组成的 ProPhoto RGB 传递函数 |
QColorSpace::TransferFunction::Bt2020 (since Qt 6.8) | 5 | 由线性部分和伽马部分组成的BT.2020传递函数 |
QColorSpace::TransferFunction::St2084 (since Qt 6.8) | 6 | SMPTE ST 2084 传递函数，也称为感知量化器（PQ）。 |
QColorSpace::TransferFunction::Hlg (since Qt 6.8) | 7 | 混合对数-伽马（HLG）传输函数。 |
[since 6.8] enum class QColorSpace::TransformModel
定义用于色彩空间变换的处理模型。
| 常量 | 值 | 描述 |
|---|---|---|
QColorSpace::TransformModel::ThreeComponentMatrix | 0 | 该变换由根据原色计算得出的矩阵以及每个颜色通道的一组传递函数组成。这种方法速度非常快，并被所有预定义的色彩空间所采用。采用此形式的任何色彩空间都是可逆的，且源和目标始终均有效。 |
QColorSpace::TransformModel::ElementListProcessing | 1 | 该变换由一个或两个处理元素列表组成，这些元素可执行多种操作；每个列表仅处理从连接色空间输入或向其输出的数据。这种方式非常灵活，但速度较慢，且只能通过读取 ICC 配置文件来设置（参见fromIccProfile()）。 由于这两个列表是独立的，因此此类色彩空间可以是有效的源，但不一定也是有效的目标。当更改此类色彩空间的原色或传递函数时，它将重置为空的 ThreeComponentMatrix 形式。 |
该枚举类型在 Qt 6.8 中引入。
成员函数文档
[constexpr noexcept default] QColorSpace::QColorSpace()
创建一个新的色彩空间对象，该对象表示一个未定义且无效的色彩空间。
QColorSpace::QColorSpace(QColorSpace::NamedColorSpace namedColorSpace)
创建一个新的色彩空间对象，该对象表示namedColorSpace 。
[since 6.1] QColorSpace::QColorSpace(QColorSpace::Primaries gamut, const QList<uint16_t> &transferFunctionTable)
创建一个以gamut 为原色的自定义色彩空间，使用由transferFunctionTable 描述的自定义转换函数。
该表应至少包含 2 个值，且包含一个从 0 到 65535 的单调递增的值列表。
该函数于 Qt 6.1 中引入。
QColorSpace::QColorSpace(QColorSpace::Primaries primaries, float gamma)
创建一个自定义色彩空间，其原色为primaries ，并采用gamma 作为伽马转换函数。
[explicit, since 6.8] QColorSpace::QColorSpace(QPointF whitePoint, const QList<uint16_t> &transferFunctionTable)
创建一个自定义灰度色彩空间，其白点为whitePoint ，并使用由transferFunctionTable 描述的自定义转换函数。
该函数于 Qt 6.8 中引入。
QColorSpace::QColorSpace(QColorSpace::Primaries primaries, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
创建一个以primaries 为原色的自定义色空间，使用传输函数transferFunction ，并可选地使用gamma 。
[explicit, since 6.8] QColorSpace::QColorSpace(QPointF whitePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
创建一个自定义灰度颜色空间，其白点为whitePoint ，使用转换函数transferFunction ，并可选地使用gamma 。
该函数于 Qt 6.8 中引入。
[since 6.9] QColorSpace::QColorSpace(const QColorSpace::PrimaryPoints &primaryPoints, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
创建一个自定义色彩空间，其原色基于原色的色度值primaryPoints ，并使用传输函数transferFunction 以及可选的gamma 。
该函数于 Qt 6.9 版本中引入。
[since 6.1] QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, const QList<uint16_t> &transferFunctionTable)
创建一个自定义色彩空间，其原色基于以下原色的色度值：whitePoint 、redPoint 、greenPoint 和bluePoint ，并使用由transferFunctionTable 描述的自定义转换函数。
该函数在 Qt 6.1 中引入。
QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
创建一个自定义色彩空间，其原色基于以下原色的色度值：whitePoint 、redPoint 、greenPoint 和bluePoint ，并使用传递函数transferFunction 以及可选的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)
创建一个基于以下原色色度值的自定义色彩空间：whitePoint 、redPoint 、greenPoint 和bluePoint ，并使用由redTransferFunctionTable 、greenTransferFunctionTable 和blueTransferFunctionTable 描述的自定义转换函数。
该函数首次出现在 Qt 6.1 中。
[constexpr noexcept default] QColorSpace::QColorSpace(QColorSpace &&colorSpace)
通过 Move 构造一个 `QColorSpace` 的实例。
[noexcept, since 6.8] QColorSpace::ColorModel QColorSpace::colorModel() const
返回该颜色空间所能表示的颜色模型
该函数于 Qt 6.8 中引入。
[noexcept, since 6.2] QString QColorSpace::description() const
返回名称或简短描述。如果在setDescription()中未提供描述，则当配置文件未被修改时返回其原始名称；若配置文件已被识别为已知色彩空间，则返回推测的名称；否则返回空字符串。
该函数在 Qt 6.2 中引入。
另请参阅 setDescription()。
[static] QColorSpace QColorSpace::fromIccProfile(const QByteArray &iccProfile)
根据 ICC 配置文件iccProfile 生成一个QColorSpace 。
注意：并非 所有 ICC 配置文件均受支持。QColorSpace 仅支持 RGB 或灰度 ICC 配置文件。
如果 ICC 配置文件不受支持，则会返回一个无效的QColorSpace ，此时您仍可通过iccProfile() 读取原始的 ICC 配置文件。
另请参阅 iccProfile()。
[noexcept] float QColorSpace::gamma() const
返回采用TransferFunction::Gamma 的色彩空间的伽马值；对于其他预定义的色彩空间，返回其近似伽马值；若未知近似伽马值，则返回0.0。
另请参阅 transferFunction()。
QByteArray QColorSpace::iccProfile() const
返回一个表示该色彩空间的 ICC 配置文件。
如果该色彩空间是由 ICC 配置文件生成的，则返回该配置文件；否则将生成一个新的配置文件。
注意：即使 是不合法的色彩空间，只要它是从 ICC 配置文件生成的，也会返回该 ICC 配置文件，以便应用程序能够自行实现更广泛的支持。
另请参阅 fromIccProfile()。
[noexcept] bool QColorSpace::isValid() const
如果颜色空间有效，则返回true 。对于满足TransformModel::ThreeComponentMatrix 的颜色空间，这意味着其原色和转换函数均已设置，且隐含isValidTarget()。对于满足TransformModel::ElementListProcessing 的颜色空间，这意味着其源变换有效；若要检查其是否也是有效的目标颜色空间，请使用isValidTarget()。
另请参阅 isValidTarget()。
[noexcept, since 6.8] bool QColorSpace::isValidTarget() const
如果该色彩空间是有效的目标色彩空间，则返回true 。
该函数在 Qt 6.8 中引入。
[noexcept] QColorSpace::Primaries QColorSpace::primaries() const
返回该色彩空间的预定义主色；若不匹配其中任何一种，则返回primaries::Custom 。
另请参阅 setPrimaries()。
[since 6.9] QColorSpace::PrimaryPoints QColorSpace::primaryPoints() const
返回主色度；若未定义，则返回空点。
该函数在 Qt 6.9 中引入。
另请参阅 primaries() 和setPrimaryPoints()。
[since 6.2] void QColorSpace::setDescription(const QString &description)
将色彩空间的名称或简短描述设置为description 。
如果设置为空，description() 将返回原始描述或推测的描述。
该函数在 Qt 6.2 中引入。
另请参阅 description()。
void QColorSpace::setPrimaries(QColorSpace::Primaries primariesId)
将主颜色设置为primariesId 集合中的颜色。
另请参阅 primaries()。
void QColorSpace::setPrimaries(const QPointF &whitePoint, const QPointF &redPoint, const QPointF &greenPoint, const QPointF &bluePoint)
将原色设置为以下色度值：whitePoint 、redPoint 、greenPoint 和bluePoint 。
另请参阅 primaries() 和setPrimaryPoints()。
[since 6.9] void QColorSpace::setPrimaryPoints(const QColorSpace::PrimaryPoints &primaryPoints)
将所有主色设置为色度值primaryPoints 。
该函数在 Qt 6.9 中引入。
另请参阅 primaries() 和primaryPoints()。
[since 6.1] void QColorSpace::setTransferFunction(const QList<uint16_t> &transferFunctionTable)
将传递函数设置为transferFunctionTable 。
该函数在 Qt 6.1 中引入。
另请参阅 transferFunction() 和withTransferFunction()。
void QColorSpace::setTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
将传递函数设置为transferFunction 和gamma 。
另请参阅 transferFunction()、gamma() 和withTransferFunction()。
[since 6.1] void QColorSpace::setTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable)
将传递函数设置为redTransferFunctionTable 、greenTransferFunctionTable 和blueTransferFunctionTable 。
该函数在 Qt 6.1 中引入。
另请参阅 withTransferFunctions()。
[since 6.8] void QColorSpace::setWhitePoint(QPointF whitePoint)
将此色彩空间所用的白点设置为whitePoint 。
该函数在 Qt 6.8 中引入。
另请参阅 whitePoint()。
[noexcept] void QColorSpace::swap(QColorSpace &other)
将该色彩空间与other 互换。此操作速度极快，且绝不会失败。
[noexcept] QColorSpace::TransferFunction QColorSpace::transferFunction() const
返回该色彩空间的预定义传递函数；如果与任何预定义传递函数都不匹配，则返回TransferFunction::Custom 。
另请参见 gamma()、setTransferFunction() 以及withTransferFunction()。
[noexcept, since 6.8] QColorSpace::TransformModel QColorSpace::transformModel() const
返回用于该色彩空间的变换处理模型。
该函数于 Qt 6.8 中引入。
QColorTransform QColorSpace::transformationToColorSpace(const QColorSpace &colorspace) const
生成并返回从该色彩空间到colorspace 的色彩空间转换。
[since 6.8] QPointF QColorSpace::whitePoint() const
返回该色彩空间所使用的白点。若未定义，则返回空QPointF 。
该函数在 Qt 6.8 中引入。
另请参阅 setWhitePoint()。
[since 6.1] QColorSpace QColorSpace::withTransferFunction(const QList<uint16_t> &transferFunctionTable) const
返回该色彩空间的副本，但使用由transferFunctionTable 描述的转换函数。
该函数在 Qt 6.1 中引入。
另请参阅 transferFunction() 和setTransferFunction()。
QColorSpace QColorSpace::withTransferFunction(QColorSpace::TransferFunction transferFunction, float gamma = 0.0f) const
返回该色彩空间的一个副本，但使用的是转换函数transferFunction 和gamma 。
另请参阅 transferFunction()、gamma() 和setTransferFunction()。
[since 6.1] QColorSpace QColorSpace::withTransferFunctions(const QList<uint16_t> &redTransferFunctionTable, const QList<uint16_t> &greenTransferFunctionTable, const QList<uint16_t> &blueTransferFunctionTable) const
返回该色彩空间的副本，但使用由redTransferFunctionTable 、greenTransferFunctionTable 和blueTransferFunctionTable 所描述的转换函数。
该函数在 Qt 6.1 中引入。
另请参阅 setTransferFunctions()。
QColorSpace::operator QVariant() const
返回颜色空间，格式为QVariant 。
相关的非成员
bool operator!=(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
如果颜色空间colorSpace1 不等于颜色空间colorSpace2 ，则返回true ；否则返回false
QDataStream &operator<<(QDataStream &stream, const QColorSpace &colorSpace)
将给定的colorSpace 作为ICC配置文件写入给定的stream 中。
另请参阅 QColorSpace::iccProfile() 以及《Qt 数据类型的序列化》。
bool operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
如果颜色空间colorSpace1 与颜色空间colorSpace2 相等，则返回 `true `；否则返回false
QDataStream &operator>>(QDataStream &stream, QColorSpace &colorSpace)
从给定的stream 中读取一个色彩空间，并将其存储到给定的colorSpace 中。
另请参阅 QColorSpace::fromIccProfile() 以及《Qt 数据类型的序列化》。
© 2026 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.
