From 7917741346ce109ea5b3df9d29d8c7189cbf8da9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Thu, 8 Mar 2018 12:54:36 +0100
Subject: [PATCH] Shaders: rename texture binding functions from set*() to
 bind*().

This better reflects that the functions modify a global state instead of
a shader-local state and so rebinding may be necessary (unlike with
uniforms, which get preserved).

The old set*() functions are now inline aliases to the bind*()
functions, are marked as deprecated and will be removed in some future
release.
---
 doc/changelog.dox                        | 13 +++++
 doc/generated/shaders.cpp                |  4 +-
 doc/snippets/MagnumShaders.cpp           | 12 ++--
 doc/snippets/MagnumText.cpp              |  4 +-
 src/Magnum/Shaders/AbstractVector.cpp    |  2 +-
 src/Magnum/Shaders/AbstractVector.h      | 13 ++++-
 src/Magnum/Shaders/DistanceFieldVector.h | 11 +++-
 src/Magnum/Shaders/Flat.cpp              |  2 +-
 src/Magnum/Shaders/Flat.h                | 17 ++++--
 src/Magnum/Shaders/Phong.cpp             |  8 +--
 src/Magnum/Shaders/Phong.h               | 74 ++++++++++++++++++------
 src/Magnum/Shaders/Vector.h              | 11 +++-
 12 files changed, 124 insertions(+), 47 deletions(-)

diff --git a/doc/changelog.dox b/doc/changelog.dox
index 54bc15f92..26126e384 100644
--- a/doc/changelog.dox
+++ b/doc/changelog.dox
@@ -51,6 +51,19 @@ See also:
         @webgl_extension{WEBGL,color_buffer_float},
         @webgl_extension{EXT,color_buffer_float}
 
+@subsection changelog-latest-deprecated Deprecated APIs
+
+-   @cpp Shaders::*Vector::setVectorTexture() @ce, @cpp Shaders::Flat::setTexture() @ce,
+    @cpp Shaders::Phong::setAmbientTexture() @ce, @cpp Shaders::Phong::setDiffuseTexture() @ce,
+    @cpp Shaders::Phong::setSpecularTexture() @ce and @cpp Shaders::Phong::setTextures() @ce
+    are deprecated because texture binding (a global state) is confused there
+    with uniform setup (a shader-local state). That can lead to accidental
+    state mismatches where a texture is forgotten to be rebound. Use
+    @ref Shaders::AbstractVector::bindVectorTexture() "Shaders::*Vector::bindVectorTexture()",
+    @ref Shaders::Flat::bindTexture(), @ref Shaders::Phong::bindAmbientTexture(),
+    @ref Shaders::Phong::bindDiffuseTexture(), @ref Shaders::Phong::bindSpecularTexture()
+    and @ref Shaders::Phong::bindTextures() instead.
+
 @subsection changelog-latest-compatibility Potential compatibility breakages, removed APIs
 
 -   Removed the @cpp Buffer::Usage @ce enum that was deprecated in 2014.01, use
diff --git a/doc/generated/shaders.cpp b/doc/generated/shaders.cpp
index 91ce8dbcb..29c22b36f 100644
--- a/doc/generated/shaders.cpp
+++ b/doc/generated/shaders.cpp
@@ -252,7 +252,7 @@ std::string ShaderVisualizer::vector() {
 
     Shaders::Vector2D shader;
     shader.setColor(BaseColor)
-        .setVectorTexture(texture)
+        .bindVectorTexture(texture)
         .setTransformationProjectionMatrix({});
 
     Renderer::enable(Renderer::Feature::Blending);
@@ -288,7 +288,7 @@ std::string ShaderVisualizer::distanceFieldVector() {
     shader.setColor(BaseColor)
         .setOutlineColor(OutlineColor)
         .setOutlineRange(0.6f, 0.4f)
-        .setVectorTexture(texture)
+        .bindVectorTexture(texture)
         .setTransformationProjectionMatrix({});
 
     Renderer::enable(Renderer::Feature::Blending);
diff --git a/doc/snippets/MagnumShaders.cpp b/doc/snippets/MagnumShaders.cpp
index 11b347a99..896ea953d 100644
--- a/doc/snippets/MagnumShaders.cpp
+++ b/doc/snippets/MagnumShaders.cpp
@@ -72,7 +72,7 @@ Matrix4 transformationMatrix, projectionMatrix;
 Texture2D diffuseTexture, specularTexture;
 
 Shaders::Phong shader{Shaders::Phong::Flag::DiffuseTexture};
-shader.setDiffuseTexture(diffuseTexture)
+shader.bindDiffuseTexture(diffuseTexture)
     .setLightPosition({5.0f, 5.0f, 7.0f})
     .setTransformationMatrix(transformationMatrix)
     .setNormalMatrix(transformationMatrix.rotation())
@@ -132,7 +132,7 @@ Shaders::DistanceFieldVector2D shader;
 shader.setColor(0x2f83cc_rgbf)
     .setOutlineColor(0xdcdcdc_rgbf)
     .setOutlineRange(0.6f, 0.4f)
-    .setVectorTexture(texture)
+    .bindVectorTexture(texture)
     .setTransformationProjectionMatrix(projectionMatrix*transformationMatrix);
 
 mesh.draw(shader);
@@ -196,7 +196,7 @@ Texture2D texture;
 
 Shaders::Flat3D shader{Shaders::Flat3D::Flag::Textured};
 shader.setTransformationProjectionMatrix(projectionMatrix*transformationMatrix)
-    .setTexture(texture);
+    .bindTexture(texture);
 
 mesh.draw(shader);
 /* [Flat-usage-textured2] */
@@ -341,7 +341,7 @@ Texture2D diffuseTexture, specularTexture;
 
 Shaders::Phong shader{Shaders::Phong::Flag::DiffuseTexture|
                       Shaders::Phong::Flag::SpecularTexture};
-shader.setTextures(nullptr, &diffuseTexture, &specularTexture)
+shader.bindTextures(nullptr, &diffuseTexture, &specularTexture)
     .setLightPosition({5.0f, 5.0f, 7.0f})
     .setTransformationMatrix(transformationMatrix)
     .setNormalMatrix(transformationMatrix.rotation())
@@ -358,7 +358,7 @@ Color3 diffuseRgb, specularRgb;
 /* [Phong-usage-alpha] */
 Shaders::Phong shader{Shaders::Phong::Flag::AmbientTexture|
                       Shaders::Phong::Flag::DiffuseTexture};
-shader.setTextures(&ambientAlphaTexture, &diffuseAlphaTexture, nullptr)
+shader.bindTextures(&ambientAlphaTexture, &diffuseAlphaTexture, nullptr)
     .setAmbientColor(0x000000ff_rgbf)
     .setDiffuseColor(Color4{diffuseRgb, 0.0f})
     .setSpecularColor(Color4{specularRgb, 0.0f});
@@ -391,7 +391,7 @@ Texture2D texture;
 
 Shaders::Vector2D shader;
 shader.setColor(0x2f83cc_rgbf)
-    .setVectorTexture(texture)
+    .bindVectorTexture(texture)
     .setTransformationProjectionMatrix(projectionMatrix*transformationMatrix);
 
 mesh.draw(shader);
diff --git a/doc/snippets/MagnumText.cpp b/doc/snippets/MagnumText.cpp
index 7534ce9fe..3e28b0618 100644
--- a/doc/snippets/MagnumText.cpp
+++ b/doc/snippets/MagnumText.cpp
@@ -77,7 +77,7 @@ std::tie(mesh, std::ignore) = Text::Renderer2D::render(*font, cache, 0.15f,
 /* Draw the text on the screen */
 shader.setTransformationProjectionMatrix(projectionMatrix)
     .setColor(0xffffff_rgbf)
-    .setVectorTexture(cache.texture());
+    .bindVectorTexture(cache.texture());
 mesh.draw(shader);
 /* [Renderer-usage1] */
 
@@ -92,7 +92,7 @@ renderer.render("Hello World Countdown: 10");
 /* Draw the text on the screen */
 shader.setTransformationProjectionMatrix(projectionMatrix)
     .setColor(0xffffff_rgbf)
-    .setVectorTexture(cache.texture());
+    .bindVectorTexture(cache.texture());
 renderer.mesh().draw(shader);
 /* [Renderer-usage2] */
 }
diff --git a/src/Magnum/Shaders/AbstractVector.cpp b/src/Magnum/Shaders/AbstractVector.cpp
index de0b994ce..c6d78ad8b 100644
--- a/src/Magnum/Shaders/AbstractVector.cpp
+++ b/src/Magnum/Shaders/AbstractVector.cpp
@@ -30,7 +30,7 @@
 
 namespace Magnum { namespace Shaders {
 
-template<UnsignedInt dimensions> AbstractVector<dimensions>& AbstractVector<dimensions>::setVectorTexture(Texture2D& texture) {
+template<UnsignedInt dimensions> AbstractVector<dimensions>& AbstractVector<dimensions>::bindVectorTexture(Texture2D& texture) {
     texture.bind(VectorTextureLayer);
     return *this;
 }
diff --git a/src/Magnum/Shaders/AbstractVector.h b/src/Magnum/Shaders/AbstractVector.h
index 661c9106b..8c31d1f06 100644
--- a/src/Magnum/Shaders/AbstractVector.h
+++ b/src/Magnum/Shaders/AbstractVector.h
@@ -58,10 +58,19 @@ template<UnsignedInt dimensions> class AbstractVector: public AbstractShaderProg
         typedef typename Generic<dimensions>::TextureCoordinates TextureCoordinates;
 
         /**
-         * @brief Set vector texture
+         * @brief Bind vector texture
          * @return Reference to self (for method chaining)
          */
-        AbstractVector<dimensions>& setVectorTexture(Texture2D& texture);
+        AbstractVector<dimensions>& bindVectorTexture(Texture2D& texture);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindVectorTexture()
+         * @deprecated Use @ref bindVectorTexture() instead.
+         */
+        CORRADE_DEPRECATED("use bindVectorTexture() instead") AbstractVector<dimensions>& setVectorTexture(Texture2D& texture) {
+            return bindVectorTexture(texture);
+        }
+        #endif
 
     #ifndef DOXYGEN_GENERATING_OUTPUT
     protected:
diff --git a/src/Magnum/Shaders/DistanceFieldVector.h b/src/Magnum/Shaders/DistanceFieldVector.h
index e16a09b16..24b382d96 100644
--- a/src/Magnum/Shaders/DistanceFieldVector.h
+++ b/src/Magnum/Shaders/DistanceFieldVector.h
@@ -47,7 +47,7 @@ rendered outlook will greatly depend on radius of input distance field and
 value passed to @ref setSmoothness(). You need to provide @ref Position and
 @ref TextureCoordinates attributes in your triangle mesh and call at least
 @ref setTransformationProjectionMatrix(), @ref setColor() and
-@ref setVectorTexture().
+@ref bindVectorTexture().
 
 @image html shaders-distancefieldvector.png
 
@@ -152,10 +152,15 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT DistanceFieldVector
 
         #ifndef DOXYGEN_GENERATING_OUTPUT
         /* Overloads to remove WTF-factor from method chaining order */
-        DistanceFieldVector<dimensions>& setVectorTexture(Texture2D& texture) {
-            AbstractVector<dimensions>::setVectorTexture(texture);
+        DistanceFieldVector<dimensions>& bindVectorTexture(Texture2D& texture) {
+            AbstractVector<dimensions>::bindVectorTexture(texture);
             return *this;
         }
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        CORRADE_DEPRECATED("use bindVectorTexture() instead") DistanceFieldVector<dimensions>& setVectorTexture(Texture2D& texture) {
+            return bindVectorTexture(texture);
+        }
+        #endif
         #endif
 
     private:
diff --git a/src/Magnum/Shaders/Flat.cpp b/src/Magnum/Shaders/Flat.cpp
index d56bf6a7f..a5fdc0049 100644
--- a/src/Magnum/Shaders/Flat.cpp
+++ b/src/Magnum/Shaders/Flat.cpp
@@ -105,7 +105,7 @@ template<UnsignedInt dimensions> Flat<dimensions>::Flat(const Flags flags): _fla
     #endif
 }
 
-template<UnsignedInt dimensions> Flat<dimensions>& Flat<dimensions>::setTexture(Texture2D& texture) {
+template<UnsignedInt dimensions> Flat<dimensions>& Flat<dimensions>::bindTexture(Texture2D& texture) {
     if(_flags & Flag::Textured)  texture.bind(TextureLayer);
     return *this;
 }
diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h
index d516b9491..65f9d6b64 100644
--- a/src/Magnum/Shaders/Flat.h
+++ b/src/Magnum/Shaders/Flat.h
@@ -53,7 +53,7 @@ need to provide @ref Position attribute in your triangle mesh and call at least
 
 If you want to use texture, you need to provide also @ref TextureCoordinates
 attribute. Pass @ref Flag::Textured to constructor and then at render time
-don't forget to set also the texture via @ref setTexture(). The texture is
+don't forget to set also the texture via @ref bindTexture(). The texture is
 multipled by the color, which is by default set to fully opaque white if
 texturing is enabled.
 
@@ -161,7 +161,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public Abstra
          * If @ref Flag::Textured is set, default value is
          * @cpp 0xffffffff_rgbaf @ce and the color will be multiplied with
          * texture.
-         * @see @ref setTexture()
+         * @see @ref bindTexture()
          */
         Flat<dimensions>& setColor(const Color4& color){
             setUniform(_colorUniform, color);
@@ -169,13 +169,22 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public Abstra
         }
 
         /**
-         * @brief Set texture
+         * @brief Bind texture
          * @return Reference to self (for method chaining)
          *
          * Has effect only if @ref Flag::Textured is set.
          * @see @ref setColor()
          */
-        Flat<dimensions>& setTexture(Texture2D& texture);
+        Flat<dimensions>& bindTexture(Texture2D& texture);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindTexture()
+         * @deprecated Use @ref bindTexture() instead.
+         */
+        CORRADE_DEPRECATED("use bindTexture() instead") Flat<dimensions>& setTexture(Texture2D& texture) {
+            return bindTexture(texture);
+        }
+        #endif
 
     private:
         Flags _flags;
diff --git a/src/Magnum/Shaders/Phong.cpp b/src/Magnum/Shaders/Phong.cpp
index bba5e8dd2..34d01f81e 100644
--- a/src/Magnum/Shaders/Phong.cpp
+++ b/src/Magnum/Shaders/Phong.cpp
@@ -124,22 +124,22 @@ Phong::Phong(const Flags flags): _flags(flags) {
     #endif
 }
 
-Phong& Phong::setAmbientTexture(Texture2D& texture) {
+Phong& Phong::bindAmbientTexture(Texture2D& texture) {
     if(_flags & Flag::AmbientTexture) texture.bind(AmbientTextureLayer);
     return *this;
 }
 
-Phong& Phong::setDiffuseTexture(Texture2D& texture) {
+Phong& Phong::bindDiffuseTexture(Texture2D& texture) {
     if(_flags & Flag::DiffuseTexture) texture.bind(DiffuseTextureLayer);
     return *this;
 }
 
-Phong& Phong::setSpecularTexture(Texture2D& texture) {
+Phong& Phong::bindSpecularTexture(Texture2D& texture) {
     if(_flags & Flag::SpecularTexture) texture.bind(SpecularTextureLayer);
     return *this;
 }
 
-Phong& Phong::setTextures(Texture2D* ambient, Texture2D* diffuse, Texture2D* specular) {
+Phong& Phong::bindTextures(Texture2D* ambient, Texture2D* diffuse, Texture2D* specular) {
     AbstractTexture::bind(AmbientTextureLayer, {ambient, diffuse, specular});
     return *this;
 }
diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h
index 9448d507a..f81a1b36b 100644
--- a/src/Magnum/Shaders/Phong.h
+++ b/src/Magnum/Shaders/Phong.h
@@ -47,10 +47,10 @@ call at least @ref setTransformationMatrix(), @ref setNormalMatrix(),
 
 If you want to use textures, you need to provide also @ref TextureCoordinates
 attribute. Pass appropriate @ref Flags to constructor and then at render time
-don't forget to also call appropriate subset of @ref setAmbientTexture(),
-@ref setDiffuseTexture() and @ref setSpecularTexture(). The texture is
-multipled by the color, which is by default set to fully opaque white for
-enabled textures.
+don't forget to also call appropriate subset of @ref bindAmbientTexture(),
+@ref bindDiffuseTexture() and @ref bindSpecularTexture() (or the combined
+@ref bindTextures()). The texture is multipled by the color, which is by
+default set to fully opaque white for enabled textures.
 
 @image html shaders-phong.png
 
@@ -159,7 +159,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
          * If @ref Flag::AmbientTexture is set, default value is
          * @cpp 0xffffffff_rgbaf @ce and the color will be multiplied with
          * ambient texture, otherwise default value is @cpp 0x000000ff_rgbaf @ce.
-         * @see @ref setAmbientTexture()
+         * @see @ref bindAmbientTexture()
          */
         Phong& setAmbientColor(const Color4& color) {
             setUniform(_ambientColorUniform, color);
@@ -167,13 +167,22 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
         }
 
         /**
-         * @brief Set ambient texture
+         * @brief Bind ambient texture
          * @return Reference to self (for method chaining)
          *
          * Has effect only if @ref Flag::AmbientTexture is set.
-         * @see @ref setTextures(), @ref setAmbientColor()
+         * @see @ref bindTextures(), @ref setAmbientColor()
          */
-        Phong& setAmbientTexture(Texture2D& texture);
+        Phong& bindAmbientTexture(Texture2D& texture);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindAmbientTexture()
+         * @deprecated Use @ref bindAmbientTexture() instead.
+         */
+        CORRADE_DEPRECATED("use bindAmbientTexture() instead") Phong& setAmbientTexture(Texture2D& texture) {
+            return bindAmbientTexture(texture);
+        }
+        #endif
 
         /**
          * @brief Set diffuse color
@@ -182,7 +191,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
          * If @ref Flag::DiffuseTexture is set, default value is
          * @cpp 0xffffffff_rgbaf @ce and the color will be multiplied with
          * diffuse texture.
-         * @see @ref setDiffuseTexture()
+         * @see @ref bindDiffuseTexture()
          */
         Phong& setDiffuseColor(const Color4& color) {
             setUniform(_diffuseColorUniform, color);
@@ -190,13 +199,22 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
         }
 
         /**
-         * @brief Set diffuse texture
+         * @brief Bind diffuse texture
          * @return Reference to self (for method chaining)
          *
          * Has effect only if @ref Flag::DiffuseTexture is set.
-         * @see @ref setTextures(), @ref setDiffuseColor()
+         * @see @ref bindTextures(), @ref setDiffuseColor()
          */
-        Phong& setDiffuseTexture(Texture2D& texture);
+        Phong& bindDiffuseTexture(Texture2D& texture);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindDiffuseTexture()
+         * @deprecated Use @ref bindDiffuseTexture() instead.
+         */
+        CORRADE_DEPRECATED("use bindDiffuseTexture() instead") Phong& setDiffuseTexture(Texture2D& texture) {
+            return bindDiffuseTexture(texture);
+        }
+        #endif
 
         /**
          * @brief Set specular color
@@ -204,7 +222,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
          *
          * Default value is @cpp 0xffffffff_rgbaf @ce. Color will be multiplied
          * with specular texture if @ref Flag::SpecularTexture is set.
-         * @see @ref setSpecularTexture()
+         * @see @ref bindSpecularTexture()
          */
         Phong& setSpecularColor(const Color4& color) {
             setUniform(_specularColorUniform, color);
@@ -212,25 +230,43 @@ class MAGNUM_SHADERS_EXPORT Phong: public AbstractShaderProgram {
         }
 
         /**
-         * @brief Set specular texture
+         * @brief Bind specular texture
          * @return Reference to self (for method chaining)
          *
          * Has effect only if @ref Flag::SpecularTexture is set.
          * @see @ref setTextures(), @ref setSpecularColor()
          */
-        Phong& setSpecularTexture(Texture2D& texture);
+        Phong& bindSpecularTexture(Texture2D& texture);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindSpecularTexture()
+         * @deprecated Use @ref bindSpecularTexture() instead.
+         */
+        CORRADE_DEPRECATED("use bindSpecularTexture() instead") Phong& setSpecularTexture(Texture2D& texture) {
+            return bindSpecularTexture(texture);
+        }
+        #endif
 
         /**
-         * @brief Set textures
+         * @brief Bind textures
          * @return Reference to self (for method chaining)
          *
          * A particular texture has effect only if particular texture flag from
          * @ref Phong::Flag "Flag" is set, you can use `nullptr` for the rest.
          * More efficient than setting each texture separately.
-         * @see @ref setAmbientTexture(), @ref setDiffuseTexture(),
-         *      @ref setSpecularTexture()
+         * @see @ref bindAmbientTexture(), @ref bindDiffuseTexture(),
+         *      @ref bindSpecularTexture()
          */
-        Phong& setTextures(Texture2D* ambient, Texture2D* diffuse, Texture2D* specular);
+        Phong& bindTextures(Texture2D* ambient, Texture2D* diffuse, Texture2D* specular);
+
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /** @brief @copybrief bindTextures()
+         * @deprecated Use @ref bindTextures() instead.
+         */
+        CORRADE_DEPRECATED("use bindTextures() instead") Phong& setTextures(Texture2D* ambient, Texture2D* diffuse, Texture2D* specular) {
+            return bindTextures(ambient, diffuse, specular);
+        }
+        #endif
 
         /**
          * @brief Set shininess
diff --git a/src/Magnum/Shaders/Vector.h b/src/Magnum/Shaders/Vector.h
index 281ee7ab0..62598c0d4 100644
--- a/src/Magnum/Shaders/Vector.h
+++ b/src/Magnum/Shaders/Vector.h
@@ -46,7 +46,7 @@ for more advanced effects. For rendering unchanged texture you can use the
 @ref Flat shader. You need to provide @ref Position and @ref TextureCoordinates
 attributes in your triangle mesh and call at least
 @ref setTransformationProjectionMatrix(), @ref setColor() and
-@ref setVectorTexture().
+@ref bindVectorTexture().
 
 @image html shaders-vector.png
 @image latex shaders-vector.png
@@ -118,10 +118,15 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Vector: public Abst
 
         #ifndef DOXYGEN_GENERATING_OUTPUT
         /* Overloads to remove WTF-factor from method chaining order */
-        Vector<dimensions>& setVectorTexture(Texture2D& texture) {
-            AbstractVector<dimensions>::setVectorTexture(texture);
+        Vector<dimensions>& bindVectorTexture(Texture2D& texture) {
+            AbstractVector<dimensions>::bindVectorTexture(texture);
             return *this;
         }
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        CORRADE_DEPRECATED("use bindVectorTexture() instead") Vector<dimensions>& setVectorTexture(Texture2D& texture) {
+            return bindVectorTexture(texture);
+        }
+        #endif
         #endif
 
     private: