Improve our color space terminology

Replace our use of 'gamut' with 'primaries'. One is the axes of the
color space, the other the volume of representable values. For the
currently supported color spaces those are mostly equivalent, but when
we later add support for scRgb, this would be misleading as it has the
same primaries as sRGB but a much wider gamut, and we would like to use
the same primaries/"gamut" id for it.

Also few people would know what "the sRGB gamut" is, but
"the sRGB primaries" is easily googable.

Change-Id: I3348ccaae27a071ec77a4356331b9bbbf92e0d19
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

5 files changed, 81 insertions, 77 deletions

diff --git a/src/gui/image/qpnghandler.cpp b/src/gui/image/qpnghandler.cpp
index 8cfcbdb2d2..3bf4e9db15 100644
--- a/src/gui/image/qpnghandler.cpp
+++ b/src/gui/image/qpnghandler.cpp
@@ -648,7 +648,7 @@ bool QPngHandlerPrivate::readPngHeader()
                 colorSpace = QColorSpace(primaries.whitePoint, primaries.redPoint, primaries.greenPoint, primaries.bluePoint,
                                          QColorSpace::TransferFunction::Gamma, fileGamma);
             } else {
-                colorSpace = QColorSpace(QColorSpace::Gamut::SRgb,
+                colorSpace = QColorSpace(QColorSpace::Primaries::SRgb,
                                          QColorSpace::TransferFunction::Gamma, fileGamma);
             }
             colorSpaceState = GammaChrm;
diff --git a/src/gui/painting/qcolorspace.cpp b/src/gui/painting/qcolorspace.cpp
index 926f2f687a..a14d630814 100644
--- a/src/gui/painting/qcolorspace.cpp
+++ b/src/gui/painting/qcolorspace.cpp
@@ -55,34 +55,34 @@ QT_BEGIN_NAMESPACE
 
 QBasicMutex QColorSpacePrivate::s_lutWriteLock;
 
-QColorSpacePrimaries::QColorSpacePrimaries(QColorSpace::Gamut gamut)
+QColorSpacePrimaries::QColorSpacePrimaries(QColorSpace::Primaries primaries)
 {
-    switch (gamut) {
-    case QColorSpace::Gamut::SRgb:
+    switch (primaries) {
+    case QColorSpace::Primaries::SRgb:
         redPoint   = QPointF(0.640, 0.330);
         greenPoint = QPointF(0.300, 0.600);
         bluePoint  = QPointF(0.150, 0.060);
         whitePoint = QColorVector::D65Chromaticity();
         break;
-    case QColorSpace::Gamut::DciP3D65:
+    case QColorSpace::Primaries::DciP3D65:
         redPoint   = QPointF(0.680, 0.320);
         greenPoint = QPointF(0.265, 0.690);
         bluePoint  = QPointF(0.150, 0.060);
         whitePoint = QColorVector::D65Chromaticity();
         break;
-    case QColorSpace::Gamut::Bt2020:
+    case QColorSpace::Primaries::Bt2020:
         redPoint   = QPointF(0.708, 0.292);
         greenPoint = QPointF(0.190, 0.797);
         bluePoint  = QPointF(0.131, 0.046);
         whitePoint = QColorVector::D65Chromaticity();
         break;
-    case QColorSpace::Gamut::AdobeRgb:
+    case QColorSpace::Primaries::AdobeRgb:
         redPoint   = QPointF(0.640, 0.330);
         greenPoint = QPointF(0.210, 0.710);
         bluePoint  = QPointF(0.150, 0.060);
         whitePoint = QColorVector::D65Chromaticity();
         break;
-    case QColorSpace::Gamut::ProPhotoRgb:
+    case QColorSpace::Primaries::ProPhotoRgb:
         redPoint   = QPointF(0.7347, 0.2653);
         greenPoint = QPointF(0.1596, 0.8404);
         bluePoint  = QPointF(0.0366, 0.0001);
@@ -153,7 +153,7 @@ QColorMatrix QColorSpacePrimaries::toXyzMatrix() const
 
 QColorSpacePrivate::QColorSpacePrivate()
         : id(QColorSpace::Unknown)
-        , gamut(QColorSpace::Gamut::Custom)
+        , primaries(QColorSpace::Primaries::Custom)
         , transferFunction(QColorSpace::TransferFunction::Custom)
         , gamma(0.0f)
         , whitePoint(QColorVector::null())
@@ -166,43 +166,43 @@ QColorSpacePrivate::QColorSpacePrivate(QColorSpace::ColorSpaceId colorSpaceId)
 {
     switch (colorSpaceId) {
     case QColorSpace::Undefined:
-        gamut = QColorSpace::Gamut::Custom;
+        primaries = QColorSpace::Primaries::Custom;
         transferFunction = QColorSpace::TransferFunction::Custom;
         gamma = 0.0f;
         description = QStringLiteral("Undefined");
         break;
     case QColorSpace::SRgb:
-        gamut = QColorSpace::Gamut::SRgb;
+        primaries = QColorSpace::Primaries::SRgb;
         transferFunction = QColorSpace::TransferFunction::SRgb;
         gamma = 2.31f; // ?
         description = QStringLiteral("sRGB");
         break;
     case QColorSpace::SRgbLinear:
-        gamut = QColorSpace::Gamut::SRgb;
+        primaries = QColorSpace::Primaries::SRgb;
         transferFunction = QColorSpace::TransferFunction::Linear;
         gamma = 1.0f;
         description = QStringLiteral("Linear sRGB");
         break;
     case QColorSpace::AdobeRgb:
-        gamut = QColorSpace::Gamut::AdobeRgb;
+        primaries = QColorSpace::Primaries::AdobeRgb;
         transferFunction = QColorSpace::TransferFunction::Gamma;
         gamma = 2.19921875f; // Not quite 2.2, see https://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf
         description = QStringLiteral("Adobe RGB");
         break;
     case QColorSpace::DisplayP3:
-        gamut = QColorSpace::Gamut::DciP3D65;
+        primaries = QColorSpace::Primaries::DciP3D65;
         transferFunction = QColorSpace::TransferFunction::SRgb;
         gamma = 2.31f; // ?
         description = QStringLiteral("Display P3");
         break;
     case QColorSpace::ProPhotoRgb:
-        gamut = QColorSpace::Gamut::ProPhotoRgb;
+        primaries = QColorSpace::Primaries::ProPhotoRgb;
         transferFunction = QColorSpace::TransferFunction::ProPhotoRgb;
         gamma = 1.8f;
         description = QStringLiteral("ProPhoto RGB");
         break;
     case QColorSpace::Bt2020:
-        gamut = QColorSpace::Gamut::Bt2020;
+        primaries = QColorSpace::Primaries::Bt2020;
         transferFunction = QColorSpace::TransferFunction::Bt2020;
         gamma = 2.1f; // ?
         description = QStringLiteral("BT.2020");
@@ -216,8 +216,8 @@ QColorSpacePrivate::QColorSpacePrivate(QColorSpace::ColorSpaceId colorSpaceId)
     initialize();
 }
 
-QColorSpacePrivate::QColorSpacePrivate(QColorSpace::Gamut gamut, QColorSpace::TransferFunction fun, float gamma)
-        : gamut(gamut)
+QColorSpacePrivate::QColorSpacePrivate(QColorSpace::Primaries primaries, QColorSpace::TransferFunction fun, float gamma)
+        : primaries(primaries)
         , transferFunction(fun)
         , gamma(gamma)
 {
@@ -229,7 +229,7 @@ QColorSpacePrivate::QColorSpacePrivate(QColorSpace::Gamut gamut, QColorSpace::Tr
 QColorSpacePrivate::QColorSpacePrivate(const QColorSpacePrimaries &primaries,
                                        QColorSpace::TransferFunction fun,
                                        float gamma)
-        : gamut(QColorSpace::Gamut::Custom)
+        : primaries(QColorSpace::Primaries::Custom)
         , transferFunction(fun)
         , gamma(gamma)
 {
@@ -243,8 +243,8 @@ QColorSpacePrivate::QColorSpacePrivate(const QColorSpacePrimaries &primaries,
 
 bool QColorSpacePrivate::identifyColorSpace()
 {
-    switch (gamut) {
-    case QColorSpace::Gamut::SRgb:
+    switch (primaries) {
+    case QColorSpace::Primaries::SRgb:
         if (transferFunction == QColorSpace::TransferFunction::SRgb) {
             id = QColorSpace::SRgb;
             if (description.isEmpty())
@@ -258,7 +258,7 @@ bool QColorSpacePrivate::identifyColorSpace()
             return true;
         }
         break;
-    case QColorSpace::Gamut::AdobeRgb:
+    case QColorSpace::Primaries::AdobeRgb:
         if (transferFunction == QColorSpace::TransferFunction::Gamma) {
             if (qAbs(gamma - 2.19921875f) < (1/1024.0f)) {
                 id = QColorSpace::AdobeRgb;
@@ -268,7 +268,7 @@ bool QColorSpacePrivate::identifyColorSpace()
             }
         }
         break;
-    case QColorSpace::Gamut::DciP3D65:
+    case QColorSpace::Primaries::DciP3D65:
         if (transferFunction == QColorSpace::TransferFunction::SRgb) {
             id = QColorSpace::DisplayP3;
             if (description.isEmpty())
@@ -276,7 +276,7 @@ bool QColorSpacePrivate::identifyColorSpace()
             return true;
         }
         break;
-    case QColorSpace::Gamut::ProPhotoRgb:
+    case QColorSpace::Primaries::ProPhotoRgb:
         if (transferFunction == QColorSpace::TransferFunction::ProPhotoRgb) {
             id = QColorSpace::ProPhotoRgb;
             if (description.isEmpty())
@@ -293,7 +293,7 @@ bool QColorSpacePrivate::identifyColorSpace()
             }
         }
         break;
-    case QColorSpace::Gamut::Bt2020:
+    case QColorSpace::Primaries::Bt2020:
         if (transferFunction == QColorSpace::TransferFunction::Bt2020) {
             id = QColorSpace::Bt2020;
             if (description.isEmpty())
@@ -315,14 +315,14 @@ void QColorSpacePrivate::initialize()
 
 void QColorSpacePrivate::setToXyzMatrix()
 {
-    if (gamut == QColorSpace::Gamut::Custom) {
+    if (primaries == QColorSpace::Primaries::Custom) {
         toXyz = QColorMatrix::null();
         whitePoint = QColorVector::D50();
         return;
     }
-    QColorSpacePrimaries primaries(gamut);
-    toXyz = primaries.toXyzMatrix();
-    whitePoint = QColorVector(primaries.whitePoint);
+    QColorSpacePrimaries colorSpacePrimaries(primaries);
+    toXyz = colorSpacePrimaries.toXyzMatrix();
+    whitePoint = QColorVector(colorSpacePrimaries.whitePoint);
 }
 
 void QColorSpacePrivate::setTransferFunction()
@@ -390,12 +390,14 @@ QColorTransform QColorSpacePrivate::transformationToColorSpace(const QColorSpace
     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 a transfer
-    function and a gamut. The gamut defines which colors the color space can represent.
-    A color space that can represent a wider range of colors is also known as a
-    wide-gamut color space. The gamut is 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.
+    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 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. The range of colors expressable 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
@@ -427,16 +429,16 @@ QColorTransform QColorSpacePrivate::transformationToColorSpace(const QColorSpace
 */
 
 /*!
-    \enum QColorSpace::Gamut
+    \enum QColorSpace::Primaries
 
-    Predefined gamuts, or sets of primary colors.
+    Predefined sets of primary colors.
 
-    \value Custom The gamut is undefined or does not match any predefined sets.
-    \value SRgb The sRGB gamut
-    \value AdobeRgb The Adobe RGB gamut
-    \value DciP3D65 The DCI-P3 gamut with the D65 whitepoint
-    \value ProPhotoRgb The ProPhoto RGB gamut with the D50 whitepoint
-    \value Bt2020 The BT.2020 gamut
+    \value Custom The primaries are undefined or does not match any predefined sets.
+    \value SRgb The sRGB primaries
+    \value AdobeRgb The Adobe RGB primaries
+    \value DciP3D65 The DCI-P3 primaries with the D65 whitepoint
+    \value ProPhotoRgb The ProPhoto RGB primaries with the D50 whitepoint
+    \value Bt2020 The BT.2020 primaries
 */
 
 /*!
@@ -472,25 +474,25 @@ QColorSpace::QColorSpace(QColorSpace::ColorSpaceId colorSpaceId)
 }
 
 /*!
-    Creates a custom color space with the gamut \a gamut, using the transfer function \a fun and
+    Creates a custom color space with the primaries \a primaries, using the transfer function \a fun and
     optionally \a gamma.
  */
-QColorSpace::QColorSpace(QColorSpace::Gamut gamut, QColorSpace::TransferFunction fun, float gamma)
-        : d_ptr(new QColorSpacePrivate(gamut, fun, gamma))
+QColorSpace::QColorSpace(QColorSpace::Primaries primaries, QColorSpace::TransferFunction fun, float gamma)
+        : d_ptr(new QColorSpacePrivate(primaries, fun, gamma))
 {
 }
 
 /*!
-    Creates a custom color space with the gamut \a gamut, using a gamma transfer function of
+    Creates a custom color space with the primaries \a primaries, using a gamma transfer function of
     \a gamma.
  */
-QColorSpace::QColorSpace(QColorSpace::Gamut gamut, float gamma)
-        : d_ptr(new QColorSpacePrivate(gamut, TransferFunction::Gamma, gamma))
+QColorSpace::QColorSpace(QColorSpace::Primaries primaries, float gamma)
+        : d_ptr(new QColorSpacePrivate(primaries, TransferFunction::Gamma, gamma))
 {
 }
 
 /*!
-    Creates a custom colorspace with a gamut based on the chromaticities of the primary colors \a whitePoint,
+    Creates a custom colorspace with a primaries based on the chromaticities of the primary colors \a whitePoint,
     \a redPoint, \a greenPoint and \a bluePoint, and using the transfer function \a fun and optionally \a gamma.
  */
 QColorSpace::QColorSpace(const QPointF &whitePoint, const QPointF &redPoint,
@@ -548,12 +550,14 @@ QColorSpace::ColorSpaceId QColorSpace::colorSpaceId() const noexcept
 }
 
 /*!
-    Returns the predefined gamut of the color space
-    or \c Gamut::Custom if it doesn't match any of them.
+    Returns the predefined primaries of the color space
+    or \c primaries::Custom if it doesn't match any of them.
 */
-QColorSpace::Gamut QColorSpace::gamut() const noexcept
+QColorSpace::Primaries QColorSpace::primaries() const noexcept
 {
-    return d_ptr->gamut;
+    if (Q_UNLIKELY(!d_ptr))
+        return QColorSpace::Primaries::Custom;
+    return d_ptr->primaries;
 }
 
 /*!
@@ -646,8 +650,8 @@ bool operator==(const QColorSpace &colorSpace1, const QColorSpace &colorSpace2)
     if (colorSpace1.colorSpaceId() != QColorSpace::Unknown && colorSpace2.colorSpaceId() != QColorSpace::Unknown)
         return colorSpace1.colorSpaceId() == colorSpace2.colorSpaceId();
 
-    if (colorSpace1.gamut() != QColorSpace::Gamut::Custom && colorSpace2.gamut() != QColorSpace::Gamut::Custom) {
-        if (colorSpace1.gamut() != colorSpace2.gamut())
+    if (colorSpace1.primaries() != QColorSpace::Primaries::Custom && colorSpace2.primaries() != QColorSpace::Primaries::Custom) {
+        if (colorSpace1.primaries() != colorSpace2.primaries())
             return false;
     } else {
         if (colorSpace1.d_ptr->toXyz != colorSpace2.d_ptr->toXyz)
@@ -735,7 +739,7 @@ QDebug operator<<(QDebug dbg, const QColorSpace &colorSpace)
     QDebugStateSaver saver(dbg);
     dbg.nospace();
     dbg << "QColorSpace(";
-    dbg << colorSpace.colorSpaceId() << ", " << colorSpace.gamut() << ", " << colorSpace.transferFunction();
+    dbg << colorSpace.colorSpaceId() << ", " << colorSpace.primaries() << ", " << colorSpace.transferFunction();
     dbg << ", gamma=" << colorSpace.gamma();
     dbg << ')';
     return dbg;
diff --git a/src/gui/painting/qcolorspace.h b/src/gui/painting/qcolorspace.h
index 709ce38916..a9871fc277 100644
--- a/src/gui/painting/qcolorspace.h
+++ b/src/gui/painting/qcolorspace.h
@@ -63,7 +63,7 @@ public:
         Bt2020,
     };
     Q_ENUM(ColorSpaceId)
-    enum class Gamut {
+    enum class Primaries {
         Custom = 0,
         SRgb,
         AdobeRgb,
@@ -71,7 +71,7 @@ public:
         ProPhotoRgb,
         Bt2020,
     };
-    Q_ENUM(Gamut)
+    Q_ENUM(Primaries)
     enum class TransferFunction {
         Custom = 0,
         Linear,
@@ -83,8 +83,8 @@ public:
     Q_ENUM(TransferFunction)
 
     QColorSpace(ColorSpaceId colorSpaceId = Undefined);
-    QColorSpace(Gamut gamut, TransferFunction fun, float gamma = 0.0f);
-    QColorSpace(Gamut gamut, float gamma);
+    QColorSpace(Primaries primaries, TransferFunction fun, float gamma = 0.0f);
+    QColorSpace(Primaries primaries, float gamma);
     QColorSpace(const QPointF &whitePoint, const QPointF &redPoint,
                 const QPointF &greenPoint, const QPointF &bluePoint,
                 TransferFunction fun, float gamma = 0.0f);
@@ -99,7 +99,7 @@ public:
     { qSwap(d_ptr, colorSpace.d_ptr); }
 
     ColorSpaceId colorSpaceId() const noexcept;
-    Gamut gamut() const noexcept;
+    Primaries primaries() const noexcept;
     TransferFunction transferFunction() const noexcept;
     float gamma() const noexcept;
 
diff --git a/src/gui/painting/qcolorspace_p.h b/src/gui/painting/qcolorspace_p.h
index 75b74f062f..2a40a0cfd8 100644
--- a/src/gui/painting/qcolorspace_p.h
+++ b/src/gui/painting/qcolorspace_p.h
@@ -66,7 +66,7 @@ class Q_GUI_EXPORT QColorSpacePrimaries
 {
 public:
    QColorSpacePrimaries() = default;
-   QColorSpacePrimaries(QColorSpace::Gamut gamut);
+   QColorSpacePrimaries(QColorSpace::Primaries primaries);
    QColorSpacePrimaries(QPointF whitePoint,
                         QPointF redPoint,
                         QPointF greenPoint,
@@ -91,7 +91,7 @@ class QColorSpacePrivate : public QSharedData
 public:
     QColorSpacePrivate();
     QColorSpacePrivate(QColorSpace::ColorSpaceId colorSpaceId);
-    QColorSpacePrivate(QColorSpace::Gamut gamut, QColorSpace::TransferFunction fun, float gamma);
+    QColorSpacePrivate(QColorSpace::Primaries primaries, QColorSpace::TransferFunction fun, float gamma);
     QColorSpacePrivate(const QColorSpacePrimaries &primaries, QColorSpace::TransferFunction fun, float gamma);
     QColorSpacePrivate(const QColorSpacePrivate &other) = default;
 
@@ -113,7 +113,7 @@ public:
     QColorTransform transformationToColorSpace(const QColorSpacePrivate *out) const;
 
     QColorSpace::ColorSpaceId id;
-    QColorSpace::Gamut gamut;
+    QColorSpace::Primaries primaries;
     QColorSpace::TransferFunction transferFunction;
     float gamma;
     QColorVector whitePoint;
diff --git a/src/gui/painting/qicc.cpp b/src/gui/painting/qicc.cpp
index 1941981d30..6cb7b57493 100644
--- a/src/gui/painting/qicc.cpp
+++ b/src/gui/painting/qicc.cpp
@@ -677,26 +677,26 @@ bool fromIccProfile(const QByteArray &data, QColorSpace *colorSpace)
     if (!parseXyzData(data, tagIndex[Tag::wtpt], colorspaceDPtr->whitePoint))
         return false;
 
-    colorspaceDPtr->gamut = QColorSpace::Gamut::Custom;
+    colorspaceDPtr->primaries = QColorSpace::Primaries::Custom;
     if (colorspaceDPtr->toXyz == QColorMatrix::toXyzFromSRgb()) {
-        qCDebug(lcIcc) << "fromIccProfile: sRGB gamut detected";
-        colorspaceDPtr->gamut = QColorSpace::Gamut::SRgb;
+        qCDebug(lcIcc) << "fromIccProfile: sRGB primaries detected";
+        colorspaceDPtr->primaries = QColorSpace::Primaries::SRgb;
     } else if (colorspaceDPtr->toXyz == QColorMatrix::toXyzFromAdobeRgb()) {
-        qCDebug(lcIcc) << "fromIccProfile: Adobe RGB gamut detected";
-        colorspaceDPtr->gamut = QColorSpace::Gamut::AdobeRgb;
+        qCDebug(lcIcc) << "fromIccProfile: Adobe RGB primaries detected";
+        colorspaceDPtr->primaries = QColorSpace::Primaries::AdobeRgb;
     } else if (colorspaceDPtr->toXyz == QColorMatrix::toXyzFromDciP3D65()) {
-        qCDebug(lcIcc) << "fromIccProfile: DCI-P3 D65 gamut detected";
-        colorspaceDPtr->gamut = QColorSpace::Gamut::DciP3D65;
+        qCDebug(lcIcc) << "fromIccProfile: DCI-P3 D65 primaries detected";
+        colorspaceDPtr->primaries = QColorSpace::Primaries::DciP3D65;
     } else if (colorspaceDPtr->toXyz == QColorMatrix::toXyzFromBt2020()) {
-        qCDebug(lcIcc) << "fromIccProfile: BT.2020 gamut detected";
-        colorspaceDPtr->gamut = QColorSpace::Gamut::Bt2020;
+        qCDebug(lcIcc) << "fromIccProfile: BT.2020 primaries detected";
+        colorspaceDPtr->primaries = QColorSpace::Primaries::Bt2020;
     }
     if (colorspaceDPtr->toXyz == QColorMatrix::toXyzFromProPhotoRgb()) {
-        qCDebug(lcIcc) << "fromIccProfile: ProPhoto RGB gamut detected";
-        colorspaceDPtr->gamut = QColorSpace::Gamut::ProPhotoRgb;
+        qCDebug(lcIcc) << "fromIccProfile: ProPhoto RGB primaries detected";
+        colorspaceDPtr->primaries = QColorSpace::Primaries::ProPhotoRgb;
     }
     // Reset the matrix to our canonical values:
-    if (colorspaceDPtr->gamut != QColorSpace::Gamut::Custom)
+    if (colorspaceDPtr->primaries != QColorSpace::Primaries::Custom)
         colorspaceDPtr->setToXyzMatrix();
 
     // Parse TRC tags