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) |
(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 |
| QVariant | 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 的 ICC 注册（1998 年） |
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 编码，其基色与 Bt2020 相同，但使用感知量化器传输函数。BT.2100 的 ICC 注册 |
QColorSpace::Bt2100Hlg (since Qt 6.8) | 8 | BT.2100 (HLG) 是一种 HDR 编码，其基底与 Bt2020 相同，但使用了混合对数-伽玛传递函数。 |
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 | 混合对数伽玛传递函数。 |
[since 6.8] enum class QColorSpace::TransformModel
定义用于色彩空间变换的处理模型。
| 常数 | 值 | 说明 |
|---|---|---|
QColorSpace::TransformModel::ThreeComponentMatrix | 0 | 变换由一个矩阵和一组传递函数组成，矩阵由每个颜色通道的原色和传递函数计算得出。这种方法非常快速，所有预定义的色彩空间都会使用。这种形式的任何色彩空间都是可逆的，并且始终都是有效的源和目标。 |
QColorSpace::TransformModel::ElementListProcessing | 1 | 转换是一个或两个处理元素列表，可以做很多事情，每个列表只处理连接色彩空间或从连接色彩空间转换。这样做非常灵活，但速度相当慢，而且只能通过读取 ICC 配置文件来设置（参见fromIccProfile() ）。由于两个列表是分开的，因此该表格中的色彩空间可以是有效的源，但不一定也是有效的目标。当改变此类型色彩空间的基色或传递函数时，它将重置为空的 ThreeComponentMatrix（三分量矩阵）形式。 |
此枚举在 Qt 6.8 中引入。
成员函数文档
[noexcept] QColorSpace::QColorSpace()
创建一个新的色彩空间对象，表示未定义的无效色彩空间。
QColorSpace::QColorSpace(QColorSpace::NamedColorSpace namedColorSpace)
创建一个新的色彩空间对象，表示namedColorSpace 。
[since 6.1] QColorSpace::QColorSpace(QColorSpace::Primaries gamut, const QList<uint16_t> &transferFunctionTable)
使用transferFunctionTable 描述的自定义传递函数，以gamut 为基色创建自定义色彩空间。
该表至少应包含 2 个值，并包含一个从 0 到 65535 的单调递增值列表。
此函数在 Qt 6.1 中引入。
QColorSpace::QColorSpace(QColorSpace::Primaries primaries, float gamma)
使用gamma 的伽玛传递函数创建自定义色彩空间，原色为primaries 。
[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)
使用传递函数transferFunction 和可选的gamma ，创建一个带有原色primaries 的自定义色彩空间。
[explicit, since 6.8] QColorSpace::QColorSpace(QPointF whitePoint, QColorSpace::TransferFunction transferFunction, float gamma = 0.0f)
使用传输函数transferFunction 和可选的gamma 创建自定义灰度颜色空间，白点为whitePoint 。
该函数在 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 中引入。
[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 配置文件生成的，也会返回 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
返回此色彩空间使用的 transfrom 处理模型。
此函数在 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()。
QVariant 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 数据类型。
© 2025 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.
