Shaders: more convenient VertexColor::Color[34] attribute specifiers.

Much easier to write (and explain!) than Shaders::VertexColor2D::Color{
Shaders::VertexColor2D::Color::Components::Three}. Ugh. Why again it
took me *years* to realize?

doc/changelog.dox

@@ -92,6 +92,12 @@ See also:
 -   @ref Platform::GlfwApplication no longer stores a needless global window
     pointer
 
+@subsubsection changelog-latest-changes-shaders Shaders library
+
+-   New dedicated @ref Shaders::VertexColor::Color3 and
+    @ref Shaders::VertexColor::Color4 attribute specifiers for more convenient
+    distinction between three- and four-component vertex color attribute.
+
 @subsubsection changelog-latest-changes-trade Trade library
 
 -   @ref Trade::PhongMaterialData now contains well-defined color values
@@ -145,6 +151,9 @@ See also:
     tuple was deprecated, use the simpler version taking just
     @ref Trade::MeshData2D / @ref Trade::MeshData3D and directly returning a
     @ref GL::Mesh instead
+-   `Shaders::VertexColor::Color` is deprecated, use the direct
+    @ref Shaders::VertexColor::Color3 or @ref Shaders::VertexColor::Color4
+    alternatives instead
 
 @subsection changelog-latest-compatibility Potential compatibility breakages, removed APIs
 

doc/generated/primitives.cpp

@@ -176,7 +176,7 @@ int PrimitiveVisualizer::exec() {
             vertices.setData(MeshTools::interleave(data->positions(0), data->colors(0)), GL::BufferUsage::StaticDraw);
             indices.setData(data->indices(), GL::BufferUsage::StaticDraw);
             GL::Mesh mesh;
-            mesh.addVertexBuffer(vertices, 0, Shaders::VertexColor2D::Position{}, Shaders::VertexColor2D::Color{Shaders::VertexColor2D::Color::Components::Four})
+            mesh.addVertexBuffer(vertices, 0, Shaders::VertexColor2D::Position{}, Shaders::VertexColor2D::Color4{})
                 .setIndexBuffer(indices, 0, GL::MeshIndexType::UnsignedInt)
                 .setCount(data->indices().size())
                 .setPrimitive(data->primitive());
@@ -205,7 +205,7 @@ int PrimitiveVisualizer::exec() {
             vertices.setData(MeshTools::interleave(data->positions(0), data->colors(0)), GL::BufferUsage::StaticDraw);
             indices.setData(data->indices(), GL::BufferUsage::StaticDraw);
             GL::Mesh mesh;
-            mesh.addVertexBuffer(vertices, 0, Shaders::VertexColor3D::Position{}, Shaders::VertexColor3D::Color{Shaders::VertexColor3D::Color::Components::Four})
+            mesh.addVertexBuffer(vertices, 0, Shaders::VertexColor3D::Position{}, Shaders::VertexColor3D::Color4{})
                 .setIndexBuffer(indices, 0, GL::MeshIndexType::UnsignedInt)
                 .setCount(data->indices().size())
                 .setPrimitive(data->primitive());

doc/generated/shaders.cpp

@@ -202,7 +202,7 @@ std::string ShaderVisualizer::vertexColor() {
         .setCount(sphere.indices().size())
         .addVertexBuffer(vertices, 0,
             Shaders::VertexColor3D::Position{},
-            Shaders::VertexColor3D::Color{Shaders::VertexColor3D::Color::Components::Three})
+            Shaders::VertexColor3D::Color3{})
         .setIndexBuffer(indices, 0, GL::MeshIndexType::UnsignedInt);
 
     Shaders::VertexColor3D shader;

doc/snippets/MagnumShaders.cpp

@@ -414,7 +414,7 @@ vertices.setData(data, GL::BufferUsage::StaticDraw);
 GL::Mesh mesh;
 mesh.addVertexBuffer(vertices, 0,
     Shaders::VertexColor3D::Position{},
-    Shaders::VertexColor3D::Color{Shaders::VertexColor3D::Color::Components::Three});
+    Shaders::VertexColor3D::Color3{});
 /* [VertexColor-usage1] */
 
 /* [VertexColor-usage2] */

src/Magnum/DebugTools/ObjectRenderer.cpp

@@ -89,7 +89,7 @@ template<UnsignedInt dimensions> ObjectRenderer<dimensions>::ObjectRenderer(Scen
         .setCount(data.indices().size())
         .addVertexBuffer(*vertexBuffer, 0,
             typename Shaders::VertexColor<dimensions>::Position(),
-            typename Shaders::VertexColor<dimensions>::Color{Shaders::VertexColor<dimensions>::Color::Components::Four})
+            typename Shaders::VertexColor<dimensions>::Color4{})
         .setIndexBuffer(*indexBuffer, 0, GL::MeshIndexType::UnsignedByte, 0, data.positions(0).size());
     ResourceManager::instance().set<GL::Mesh>(_mesh.key(), mesh, ResourceDataState::Final, ResourcePolicy::Manual);
 }

src/Magnum/Shaders/Generic.h

@@ -68,27 +68,41 @@ template<UnsignedInt dimensions> struct Generic {
     typedef GL::Attribute<2, Vector3> Normal;
 
     /**
-     * @brief Vertex color
+     * @brief Three-component vertex color.
+     *
+     * @ref Magnum::Color3. Use either this or the @ref Color4 attribute.
+     */
+    typedef GL::Attribute<3, Magnum::Color3> Color3;
+
+    /**
+     * @brief Four-component vertex color.
      *
-     * @ref Color4, however defaults to @ref Color3 if @ref MAGNUM_BUILD_DEPRECATED
+     * @ref Magnum::Color4. Use either this or the @ref Color3 attribute.
-     * is defined. See the constructor documentation for more information.
+     */
+    typedef GL::Attribute<3, Magnum::Color4> Color4;
+
+    #ifdef MAGNUM_BUILD_DEPRECATED
+    /**
+     * @brief Vertex color
+     * @deprecated Use @ref Color3 or @ref Color4 instead.
      */
-    struct Color: GL::Attribute<3, Color4> {
+    struct Color: GL::Attribute<3, Magnum::Color4> {
         /**
          * @brief Constructor
          * @param components    Component count
          * @param dataType      Type of passed data
          * @param dataOptions   Data options
+         *
+         * @deprecated Use @ref Color3 or @ref Color4 instead.
          */
-        constexpr explicit Color(Components components, DataType dataType = DataType::Float, DataOptions dataOptions = {});
+        CORRADE_DEPRECATED("use Color3 or Color4 instead") constexpr explicit Color(Components components, DataType dataType = DataType::Float, DataOptions dataOptions = {});
 
-        #ifdef MAGNUM_BUILD_DEPRECATED
         /** @brief @copybrief Color(Components, DataType, DataOptions)
-         * @deprecated Use @ref Color(Components, DataType, DataOptions) instead.
+         * @deprecated Use @ref Color3 or @ref Color4 instead.
          */
-        CORRADE_DEPRECATED("use Color(Components, DataType, DataOptions) instead") constexpr explicit Color(DataType dataType = DataType::Float, DataOptions dataOptions = {});
+        CORRADE_DEPRECATED("use Color3 or Color4 instead") constexpr explicit Color(DataType dataType = DataType::Float, DataOptions dataOptions = {});
-        #endif
     };
+    #endif
 };
 #endif
 
@@ -101,14 +115,16 @@ typedef Generic<3> Generic3D;
 #ifndef DOXYGEN_GENERATING_OUTPUT
 struct BaseGeneric {
     typedef GL::Attribute<1, Vector2> TextureCoordinates;
-
+    typedef GL::Attribute<3, Magnum::Color3> Color3;
-    struct Color: GL::Attribute<3, Color4> {
+    typedef GL::Attribute<3, Magnum::Color4> Color4;
-        constexpr explicit Color(Components components, DataType dataType = DataType::Float, DataOptions dataOptions = DataOptions()): Attribute<3, Color4>{components, dataType, dataOptions} {}
 
     #ifdef MAGNUM_BUILD_DEPRECATED
-        CORRADE_DEPRECATED("use Color(Components, DataType, DataOptions) instead") constexpr explicit Color(DataType dataType = DataType::Float, DataOptions dataOptions = DataOptions()): Attribute<3, Color4>{Components::Three, dataType, dataOptions} {}
+    struct Color: GL::Attribute<3, Magnum::Color4> {
-        #endif
+        CORRADE_DEPRECATED("use Color3 or Color4 instead") constexpr explicit Color(Components components, DataType dataType = DataType::Float, DataOptions dataOptions = DataOptions()): Attribute<3, Magnum::Color4>{components, dataType, dataOptions} {}
+
+        CORRADE_DEPRECATED("use Color3 or Color4 instead") constexpr explicit Color(DataType dataType = DataType::Float, DataOptions dataOptions = DataOptions()): Attribute<3, Magnum::Color4>{Components::Three, dataType, dataOptions} {}
     };
+    #endif
 };
 
 template<> struct Generic<2>: BaseGeneric {

src/Magnum/Shaders/VertexColor.cpp

@@ -73,7 +73,7 @@ template<UnsignedInt dimensions> VertexColor<dimensions>::VertexColor() {
     #endif
     {
         bindAttributeLocation(Position::Location, "position");
-        bindAttributeLocation(Color::Location, "color");
+        bindAttributeLocation(Color3::Location, "color"); /* Color4 is the same */
     }
 
     CORRADE_INTERNAL_ASSERT_OUTPUT(link());

src/Magnum/Shaders/VertexColor.h

@@ -50,10 +50,8 @@ attributes in your triangle mesh and call at least
 
 @section Shaders-VertexColor-example Example usage
 
-Common mesh setup. Note the explicit specification of components for the color
+Common mesh setup. The shader accepts either three- or four-component color
-attribute --- the shader accepts four-component color attribute but, similarly
+attribute, use either @ref Color3 or @ref Color4 to specify which one you use.
-to all other attributes, it's possible to supply also three-component colors if
-alpha is not important.
 
 @snippet MagnumShaders.cpp VertexColor-usage1
 
@@ -74,13 +72,28 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT VertexColor: public
         typedef typename Generic<dimensions>::Position Position;
 
         /**
-         * @brief Vertex color
+         * @brief Three-component vertex color.
+         *
+         * @ref shaders-generic "Generic attribute", @ref Magnum::Color3. Use
+         * either this or the @ref Color4 attribute.
+         */
+        typedef typename Generic<dimensions>::Color3 Color3;
+
+        /**
+         * @brief Four-component vertex color.
          *
-         * @ref shaders-generic "Generic attribute", @ref Color4, however
+         * @ref shaders-generic "Generic attribute", @ref Magnum::Color4. Use
-         * defaults to @ref Color3 if @ref MAGNUM_BUILD_DEPRECATED is defined.
+         * either this or the @ref Color3 attribute.
-         * See the @ref Generic::Color for more information.
+         */
+        typedef typename Generic<dimensions>::Color4 Color4;
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /**
+         * @brief Vertex color
+         * @deprecated Use @ref Color3 or @ref Color4 instead.
          */
-        typedef typename Generic<dimensions>::Color Color;
+        typedef CORRADE_DEPRECATED("use Color3 or Color4 instead") typename Generic<dimensions>::Color Color;
+        #endif
 
         explicit VertexColor();