Optional and opaque RGB colors

CMakeLists.txt

@@ -954,6 +954,7 @@ add_executable(mixxx-test
   src/test/readaheadmanager_test.cpp
   src/test/replaygaintest.cpp
   src/test/rescalertest.cpp
+  src/test/rgbcolor_test.cpp
   src/test/samplebuffertest.cpp
   src/test/sampleutiltest.cpp
   src/test/schemamanager_test.cpp

src/mixxxapplication.cpp

@@ -9,6 +9,7 @@
 #include "soundio/soundmanagerutil.h"
 #include "track/track.h"
 #include "track/trackref.h"
+#include "util/color/rgbcolor.h"
 #include "util/math.h"
 
 // When linking Qt statically on Windows we have to Q_IMPORT_PLUGIN all the
@@ -67,6 +68,7 @@ void MixxxApplication::registerMetaTypes() {
     qRegisterMetaType<mixxx::ReplayGain>("mixxx::ReplayGain");
     qRegisterMetaType<mixxx::Bpm>("mixxx::Bpm");
     qRegisterMetaType<mixxx::Duration>("mixxx::Duration");
+    qRegisterMetaType<mixxx::OptionalRgbColor>("mixxx::OptionalRgbColor");
     qRegisterMetaType<SoundDeviceId>("SoundDeviceId");
     QMetaType::registerComparators<SoundDeviceId>();
 }

src/test/rgbcolor_test.cpp

@@ -0,0 +1,68 @@
+#include "util/color/rgbcolor.h"
+
+#include <gtest/gtest.h>
+
+#include "test/mixxxtest.h"
+
+namespace mixxx {
+
+TEST(OptionalRgbColorTest, DefaultIsUndefined) {
+    EXPECT_FALSE(OptionalRgbColor().optional());
+    EXPECT_FALSE(static_cast<bool>(OptionalRgbColor().optional()));
+}
+
+TEST(OptionalRgbColorTest, FromRgbColorCode) {
+    EXPECT_TRUE(OptionalRgbColor(0x000000).optional());
+    EXPECT_EQ(RgbColor(0x000000), *OptionalRgbColor(0x000000).optional());
+    EXPECT_TRUE(OptionalRgbColor(0xFF0000).optional());
+    EXPECT_EQ(RgbColor(0xFF0000), *OptionalRgbColor(0xFF0000).optional());
+    EXPECT_TRUE(OptionalRgbColor(0x00FF00).optional());
+    EXPECT_EQ(RgbColor(0x00FF00), *OptionalRgbColor(0x00FF00).optional());
+    EXPECT_TRUE(OptionalRgbColor(0x0000FF).optional());
+    EXPECT_EQ(RgbColor(0x0000FF), *OptionalRgbColor(0x0000FF).optional());
+    EXPECT_TRUE(OptionalRgbColor(0xFFFFFF).optional());
+    EXPECT_EQ(RgbColor(0xFFFFFF), *OptionalRgbColor(0xFFFFFF).optional());
+}
+
+TEST(OptionalRgbColorTest, FromOptionalRgbColorCode) {
+    EXPECT_EQ(OptionalRgbColor(), OptionalRgbColor(std::nullopt));
+    EXPECT_EQ(OptionalRgbColor(0x123456), OptionalRgbColor(std::make_optional(RgbColor(0x123456))));
+}
+
+TEST(OptionalRgbColorTest, FromQColor) {
+    EXPECT_FALSE(OptionalRgbColor(QColor()).optional());
+    EXPECT_EQ(OptionalRgbColor(), OptionalRgbColor(QColor()));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgb(0x000000)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x000000), OptionalRgbColor(QColor::fromRgb(0x000000)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgb(0xFF0000)).optional());
+    EXPECT_EQ(OptionalRgbColor(0xFF0000), OptionalRgbColor(QColor::fromRgb(0xFF0000)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgb(0x00FF00)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x00FF00), OptionalRgbColor(QColor::fromRgb(0x00FF00)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgb(0x0000FF)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x0000FF), OptionalRgbColor(QColor::fromRgb(0x0000FF)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgb(0xFFFFFF)).optional());
+    EXPECT_EQ(OptionalRgbColor(0xFFFFFF), OptionalRgbColor(QColor::fromRgb(0xFFFFFF)));
+}
+
+TEST(OptionalRgbColorTest, FromQColorWithAlpha) {
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgba(0xAA000000)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x000000), OptionalRgbColor(QColor::fromRgba(0xAA000000)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgba(0xAAFF0000)).optional());
+    EXPECT_EQ(OptionalRgbColor(0xFF0000), OptionalRgbColor(QColor::fromRgba(0xAAFF0000)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgba(0xAA00FF00)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x00FF00), OptionalRgbColor(QColor::fromRgba(0xAA00FF00)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgba(0xAA0000FF)).optional());
+    EXPECT_EQ(OptionalRgbColor(0x0000FF), OptionalRgbColor(QColor::fromRgba(0xAA0000FF)));
+    EXPECT_TRUE(OptionalRgbColor(QColor::fromRgba(0xAAFFFFFF)).optional());
+    EXPECT_EQ(OptionalRgbColor(0xFFFFFF), OptionalRgbColor(QColor::fromRgba(0xAAFFFFFF)));
+}
+
+TEST(OptionalRgbColorTest, ToQColor) {
+    EXPECT_EQ(QColor(), OptionalRgbColor().toQColor());
+    EXPECT_EQ(QColor::fromRgba(0xAABBCCDD),
+            OptionalRgbColor().toQColor(QColor::fromRgba(0xAABBCCDD)));
+    EXPECT_EQ(QColor::fromRgb(0x123456),
+            OptionalRgbColor(QColor::fromRgba(0xAA123456)).toQColor(QColor::fromRgba(0xAABBCCDD)));
+}
+
+} // namespace mixxx

src/util/color/rgbcolor.h

@@ -0,0 +1,168 @@
+#pragma once
+
+#include <QColor>
+#include <QtGlobal>
+
+#include "util/assert.h"
+#include "util/optional.h"
+
+namespace mixxx {
+
+// A pure 24-bit 0xxRRGGBB color code with 8-bit per channel
+// without an an alpha channel.
+// We are using a separate typedef, because QRgb implicitly
+// includes an alpha channel whereas this type does not!
+typedef quint32 RgbColorCode;
+
+// Type-safe wrapper around RgbColorCode without implicit
+// range checks and no implicit validation.
+// Apart from the assignment operator this type is immutable.
+class RgbColor {
+  public:
+    // The default constructor is not available, because there is
+    // no common default value that fits all possible use cases!
+    RgbColor() = delete;
+    // Explicit conversion from RgbColorCode.
+    explicit constexpr RgbColor(RgbColorCode code)
+            : m_code(code) {
+    }
+    // Explicit conversion from QColor.
+    RgbColor(QColor anyColor, RgbColorCode codeIfInvalid)
+            : m_code(anyColorToCode(anyColor, codeIfInvalid)) {
+    }
+
+    // Explicit conversion to a valid color code.
+    RgbColorCode validCode() const {
+        return validateCode(m_code);
+    }
+
+    // Explicit conversion into the corresponding QColor.
+    QColor validQColor() const {
+        return QColor::fromRgb(validCode());
+    }
+
+    friend bool operator==(RgbColor lhs, RgbColor rhs) {
+        return lhs.m_code == rhs.m_code;
+    }
+
+  protected:
+    // Bitmask of valid codes = 0x00RRGGBB
+    static constexpr RgbColorCode kRgbCodeMask = 0x00FFFFFF;
+
+    static RgbColorCode validateCode(RgbColorCode code) {
+        return code & kRgbCodeMask;
+    }
+    static bool isValidCode(RgbColorCode code) {
+        return code == validateCode(code);
+    }
+
+    static RgbColorCode anyColorToCode(QColor anyColor, RgbColorCode codeIfInvalid) {
+        if (anyColor.isValid()) {
+            // Strip alpha channel bits!
+            return validateCode(anyColor.rgb());
+        } else {
+            return codeIfInvalid;
+        }
+    }
+
+    RgbColorCode m_code;
+};
+
+inline bool operator!=(RgbColor lhs, RgbColor rhs) {
+    return !(lhs == rhs);
+}
+
+// A thin wrapper around 24-bit opaque RGB values that includes
+// a single undefined state. The undefined state could be used
+// to represent missing or transparent values.
+// This class might be used as a "hub" for the conversion between
+// RgbColorCode, std::optional<RgbColorCode>, and QColor. For
+// this particulare use case it's only purpose is to store an
+// intermediate representation before the internal value that
+// has been converted from the source type is finally converted
+// into the desired target type.
+// std::optional<RgbColorCode> is equivalent, RgbColorCode is
+// less versatile, and QColor is more versatile.
+// Apart from the assignment operator this type is immutable.
+class OptionalRgbColor final : public RgbColor {
+  public:
+    OptionalRgbColor()
+            : RgbColor(kUndefinedInternalCode) {
+        DEBUG_ASSERT(!isValidCode(m_code));
+    }
+    // Explicit conversion from RgbColor
+    explicit OptionalRgbColor(RgbColor base)
+            : RgbColor(base.validCode()) {
+        DEBUG_ASSERT(isValidCode(m_code));
+    }
+    // Explicit conversion from RgbColorCode
+    explicit OptionalRgbColor(RgbColorCode code)
+            : RgbColor(RgbColor(validateCode(code))) {
+        DEBUG_ASSERT(isValidCode(m_code) == isValidCode(code));
+    }
+    // Explicit conversion from an optional RgbColor that
+    // is equivalent to this class. The conversion is explicit
+    // to avoid ambiguities with the implicit conversion back
+    // into std::optional<RgbColor>.
+    explicit OptionalRgbColor(std::optional<RgbColor> optional)
+            : RgbColor(optional ? optional->validCode() : kUndefinedInternalCode) {
+        DEBUG_ASSERT(isValidCode(m_code) == static_cast<bool>(optional));
+    }
+    // Explicit conversion from QColor
+    explicit OptionalRgbColor(QColor anyColor)
+            : RgbColor(anyColorToInternalCode(anyColor)) {
+        DEBUG_ASSERT(isValidCode(m_code) == anyColor.isValid());
+    }
+    OptionalRgbColor(const OptionalRgbColor&) = default;
+    OptionalRgbColor(OptionalRgbColor&&) = default;
+
+    // Explicit conversion to an optional RGB color.
+    std::optional<RgbColor> optional() const {
+        if (isValidCode(m_code)) {
+            // Defined
+            return std::make_optional(RgbColor(m_code));
+        } else {
+            // Undefined
+            return std::nullopt;
+        }
+    }
+
+    // Explicit conversion into the corresponding QColor.
+    // Optionally the desired QColor that represents undefined
+    // values could be provided.
+    QColor toQColor(QColor undefinedColor = QColor()) const {
+        if (isValidCode(m_code)) {
+            // Defined
+            return validQColor();
+        } else {
+            // Undefined
+            return undefinedColor;
+        }
+    }
+
+  private:
+    static constexpr RgbColorCode kUndefinedInternalCode = 0xFFFFFFFF;
+
+    static RgbColorCode codeToInternalCode(RgbColorCode code) {
+        // The unused bits of an RgbColorCode should never be set.
+        DEBUG_ASSERT(isValidCode(code));
+        // This normalization should not be necessary, just in case.
+        return code & kRgbCodeMask;
+    }
+    static RgbColorCode optionalCodeToInternalCode(std::optional<RgbColorCode> optionalCode) {
+        if (optionalCode) {
+            return codeToInternalCode(*optionalCode);
+        } else {
+            return kUndefinedInternalCode;
+        }
+    }
+
+    static RgbColorCode anyColorToInternalCode(QColor anyColor) {
+        return anyColorToCode(anyColor, kUndefinedInternalCode);
+    }
+};
+
+} // namespace mixxx
+
+Q_DECLARE_TYPEINFO(mixxx::OptionalRgbColor, Q_PRIMITIVE_TYPE);
+Q_DECLARE_METATYPE(mixxx::OptionalRgbColor)

src/util/optional.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#if __has_include(<optional>) || \
+    (defined(__cpp_lib_optional) && __cpp_lib_optional >= 201606L)
+
+#include <optional>
+
+#else
+
+#include <experimental/optional>
+
+namespace std {
+
+using std::experimental::make_optional;
+using std::experimental::nullopt;
+using std::experimental::optional;
+
+// Workarounds for missing member functions:
+// option::has_value() -> explicit operator bool()
+// option::value() -> operator*()
+
+} // namespace std
+
+#endif