Shaders: define reasonable uniform defaults for all shaders.

Plus a bit of cleanup / fixing broken English.

doc/changelog.dox

@@ -157,6 +157,8 @@ See also:
 
 @subsubsection changelog-latest-changes-shaders Shaders library
 
+-   All shaders now have reasonable default values for uniforms in order to
+    further simplify and remove friction from quick prototyping use cases
 -   @ref Shaders::Flat::bindTexture(), @ref Shaders::Phong::bindAmbientTexture(),
     @ref Shaders::Phong::bindDiffuseTexture(),
     @ref Shaders::Phong::bindSpecularTexture() and

doc/shaders.dox

@@ -63,8 +63,11 @@ usage examples. Example mesh configuration for @ref Shaders::Phong shader:
 Each shader then has its own set of configuration functions. Some configuration
 is static, specified commonly as flags in constructor, directly affecting
 compiled shader code. Other configuration is specified through uniforms and
-various binding points, commonly exposed through various setters. Example
+various binding points, commonly exposed through various setters. All shader
-configuration and rendering using @link Shaders::Phong @endlink:
+uniforms have a reasonable defaults so you are able to see at least something
+when using the shader directly without any further configuration, but in most
+cases you may want to specify at least the transformation/projection matrices.
+Example configuration and rendering using @link Shaders::Phong @endlink:
 
 @snippet MagnumShaders.cpp shaders-rendering
 

src/Magnum/Shaders/AbstractVector2D.vert

@@ -31,7 +31,11 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat3 transformationProjectionMatrix;
+uniform highp mat3 transformationProjectionMatrix
+    #ifndef GL_ES
+    = mat3(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)

src/Magnum/Shaders/AbstractVector3D.vert

@@ -31,7 +31,11 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat4 transformationProjectionMatrix;
+uniform highp mat4 transformationProjectionMatrix
+    #ifndef GL_ES
+    = mat4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)

src/Magnum/Shaders/DistanceFieldVector.cpp

@@ -99,6 +99,8 @@ template<UnsignedInt dimensions> DistanceFieldVector<dimensions>::DistanceFieldV
 
     /* Set defaults in OpenGL ES (for desktop they are set in shader code itself) */
     #ifdef MAGNUM_TARGET_GLES
+    setTransformationProjectionMatrix({});
+    setColor(Color4{1.0f}); /* Outline color is zero by default */
     setOutlineRange(0.5f, 1.0f);
     setSmoothness(0.04f);
     #endif

src/Magnum/Shaders/DistanceFieldVector.frag

@@ -32,12 +32,16 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 1)
 #endif
-uniform lowp vec4 color;
+uniform lowp vec4 color
+    #ifndef GL_ES
+    = vec4(1.0, 1.0, 1.0, 1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 2)
 #endif
-uniform lowp vec4 outlineColor;
+uniform lowp vec4 outlineColor; /* defaults to zero */
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 3)

src/Magnum/Shaders/DistanceFieldVector.h

@@ -41,13 +41,15 @@ namespace Magnum { namespace Shaders {
 /**
 @brief Distance field vector shader
 
-Renders vector graphics in form of signed distance field. See
+Renders vector graphics in a form of signed distance field. See
 @ref TextureTools::distanceField() for more information. Note that the final
 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 bindVectorTexture(). By default, the shader renders the distance field
-@ref bindVectorTexture().
+texture with a white color in an identity transformation, use
+@ref setTransformationProjectionMatrix(), @ref setColor() and others to
+configure the shader.
 
 @image html shaders-distancefieldvector.png
 
@@ -102,6 +104,8 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT DistanceFieldVector
         /**
          * @brief Set transformation and projection matrix
          * @return Reference to self (for method chaining)
+         *
+         * Initial value is an identity matrix.
          */
         DistanceFieldVector& setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) {
             GL::AbstractShaderProgram::setUniform(_transformationProjectionMatrixUniform, matrix);
@@ -112,6 +116,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT DistanceFieldVector
          * @brief Set fill color
          * @return Reference to self (for method chaining)
          *
+         * Initial value is @cpp 0xffffffff_rgbaf @ce.
          * @see @ref setOutlineColor()
          */
         DistanceFieldVector& setColor(const Color4& color) {
@@ -123,6 +128,8 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT DistanceFieldVector
          * @brief Set outline color
          * @return Reference to self (for method chaining)
          *
+         * Initial value is @cpp 0x00000000_rgbaf @ce and the outline is not
+         * drawn --- see @ref setOutlineRange() for more information.
          * @see @ref setOutlineRange(), @ref setColor()
          */
         DistanceFieldVector& setOutlineColor(const Color4& color) {
@@ -134,11 +141,11 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT DistanceFieldVector
          * @brief Set outline range
          * @return Reference to self (for method chaining)
          *
-         * Parameter @p start describes where fill ends and possible outline
+         * The @p start parameter describes where fill ends and possible
-         * starts. Initial value is @cpp 0.5f @ce, larger values will make the
+         * outline starts. Initial value is @cpp 0.5f @ce, larger values will
-         * vector art look thinner, smaller will make it look thicker.
+         * make the vector art look thinner, smaller will make it look thicker.
          *
-         * Parameter @p end describes where outline ends. If set to value
+         * The @p end parameter describes where outline ends. If set to value
          * larger than @p start the outline is not drawn. Initial value is
          * @cpp 1.0f @ce.
          *

src/Magnum/Shaders/Flat.cpp

@@ -102,8 +102,8 @@ template<UnsignedInt dimensions> Flat<dimensions>::Flat(const Flags flags): _fla
 
     /* Set defaults in OpenGL ES (for desktop they are set in shader code itself) */
     #ifdef MAGNUM_TARGET_GLES
-    /* Default to fully opaque white so we can see the texture */
+    setTransformationProjectionMatrix({});
-    if(flags & Flag::Textured) setColor(Color4(1.0f));
+    setColor(Color4{1.0f});
     if(flags & Flag::AlphaMask) setAlphaMask(0.5f);
     #endif
 }

src/Magnum/Shaders/Flat.h

@@ -50,15 +50,16 @@ namespace Implementation {
 /**
 @brief Flat shader
 
-Draws whole mesh with given unshaded color or texture. For colored mesh you
+Draws the whole mesh with given color or texture. For a colored mesh you need
-need to provide @ref Position attribute in your triangle mesh and call at least
+to provide the @ref Position attribute in your triangle mesh. By default, the
-@ref setTransformationProjectionMatrix() and @ref setColor().
+shader renders the mesh with a white color in an identity transformation.
+Use @ref setTransformationProjectionMatrix(), @ref setColor() and others to
+configure the shader.
 
-If you want to use texture, you need to provide also @ref TextureCoordinates
+If you want to use a texture, you need to provide also @ref TextureCoordinates
-attribute. Pass @ref Flag::Textured to constructor and then at render time
+attribute. Pass @ref Flag::Textured to the constructor and then at render time
-don't forget to set also the texture via @ref bindTexture(). The texture is
+don't forget to bind also the texture via @ref bindTexture(). The texture is
-multipled by the color, which is by default set to fully opaque white if
+multipled by the color, which is by default set to @cpp 0xffffffff_rgbaf @ce.
-texturing is enabled.
 
 For coloring the texture based on intensity you can use the @ref Vector shader.
 
@@ -191,6 +192,8 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
         /**
          * @brief Set transformation and projection matrix
          * @return Reference to self (for method chaining)
+         *
+         * Initial value is an identity matrix.
          */
         Flat<dimensions>& setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) {
             setUniform(_transformationProjectionMatrixUniform, matrix);
@@ -201,7 +204,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
          * @brief Set color
          * @return Reference to self (for method chaining)
          *
-         * If @ref Flag::Textured is set, default value is
+         * If @ref Flag::Textured is set, initial value is
          * @cpp 0xffffffff_rgbaf @ce and the color will be multiplied with
          * texture.
          * @see @ref bindTexture()
@@ -212,7 +215,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
         }
 
         /**
-         * @brief Bind texture
+         * @brief Bind a color texture
          * @return Reference to self (for method chaining)
          *
          * Expects that the shader was created with @ref Flag::Textured
@@ -227,7 +230,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
          *
          * Expects that the shader was created with @ref Flag::AlphaMask
          * enabled. Fragments with alpha values smaller than the mask value
-         * will be discarded. Default is @cpp 0.5f @ce. See the flag
+         * will be discarded. Initial value is @cpp 0.5f @ce. See the flag
          * documentation for further information.
          */
         Flat<dimensions>& setAlphaMask(Float mask);

src/Magnum/Shaders/Flat2D.vert

@@ -31,7 +31,11 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat3 transformationProjectionMatrix;
+uniform highp mat3 transformationProjectionMatrix
+    #ifndef GL_ES
+    = mat3(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)

src/Magnum/Shaders/Flat3D.vert

@@ -31,7 +31,11 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat4 transformationProjectionMatrix;
+uniform highp mat4 transformationProjectionMatrix
+    #ifndef GL_ES
+    = mat4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)

src/Magnum/Shaders/Generic.h

@@ -36,10 +36,9 @@ namespace Magnum { namespace Shaders {
 /**
 @brief Generic shader definition
 
-Definitions common for majority of shaders in @ref Shaders namespace, allowing
+Definitions common for majority of shaders in the @ref Shaders namespace,
-mesh configured for the generic shader to be used with any of them. See
+allowing mesh configured for a generic shader to be used with any of them.
-@ref shaders-generic for more information.
+See @ref shaders-generic for more information.
-
 @see @ref shaders, @ref Generic2D, @ref Generic3D
 */
 #ifndef DOXYGEN_GENERATING_OUTPUT

src/Magnum/Shaders/MeshVisualizer.cpp

@@ -141,9 +141,11 @@ MeshVisualizer::MeshVisualizer(const Flags flags): _flags{flags} {
 
     /* Set defaults in OpenGL ES (for desktop they are set in shader code itself) */
     #ifdef MAGNUM_TARGET_GLES
+    setTransformationProjectionMatrix({});
     setColor(Color3(1.0f));
     if(_flags & Flag::Wireframe) {
-        setWireframeColor(Color3(0.0f));
+        /* Viewport size is zero by default */
+        setWireframeColor(Color3{0.0f});
         setWireframeWidth(1.0f);
         setSmoothness(2.0f);
     }

src/Magnum/Shaders/MeshVisualizer.geom

@@ -37,7 +37,7 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 1)
 #endif
-uniform lowp vec2 viewportSize;
+uniform lowp vec2 viewportSize; /* defaults to zero */
 
 layout(triangles) in;
 

src/Magnum/Shaders/MeshVisualizer.h

@@ -40,8 +40,10 @@ namespace Magnum { namespace Shaders {
 @brief Mesh visualization shader
 
 Uses geometry shader to visualize wireframe of 3D meshes. You need to provide
-@ref Position attribute in your triangle mesh and call at least
+the @ref Position attribute in your triangle mesh. By default, the shader
-@ref setTransformationProjectionMatrix() to be able to render.
+renders the mesh with a white color in an identity transformation. Use
+@ref setTransformationProjectionMatrix(), @ref setColor() and others to
+configure the shader.
 
 @image html shaders-meshvisualizer.png
 
@@ -59,8 +61,8 @@ If you have geometry shaders available, you don't need to do anything else.
 
 If you don't have geometry shaders, you need to set @ref Flag::NoGeometryShader
 (it's enabled by default in OpenGL ES 2.0) and use only **non-indexed** triangle
-meshes (see @ref MeshTools::duplicate() for possible solution). Additionaly, if
+meshes (see @ref MeshTools::duplicate() for a possible solution). Additionaly,
-you have OpenGL < 3.1 or OpenGL ES 2.0, you need to provide also
+if you have OpenGL < 3.1 or OpenGL ES 2.0, you need to provide also the
 @ref VertexIndex attribute.
 
 @requires_gles30 Extension @gl_extension{OES,standard_derivatives} for
@@ -186,6 +188,8 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram {
         /**
          * @brief Set transformation and projection matrix
          * @return Reference to self (for method chaining)
+         *
+         * Initial value is an identity matrix.
          */
         MeshVisualizer& setTransformationProjectionMatrix(const Matrix4& matrix) {
             setUniform(_transformationProjectionMatrixUniform, matrix);
@@ -197,7 +201,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram {
          * @return Reference to self (for method chaining)
          *
          * Has effect only if @ref Flag::Wireframe is enabled and geometry
-         * shaders are used.
+         * shaders are used. Initial value is a zero vector.
          */
         MeshVisualizer& setViewportSize(const Vector2& size) {
             if(_flags & Flag::Wireframe && !(_flags & Flag::NoGeometryShader))
@@ -209,7 +213,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram {
          * @brief Set base object color
          * @return Reference to self (for method chaining)
          *
-         * Initial value is fully opaque white.
+         * Initial value is @cpp 0xffffffff_rgbaf @ce.
          */
         MeshVisualizer& setColor(const Color4& color) {
             setUniform(_colorUniform, color);
@@ -220,7 +224,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram {
          * @brief Set wireframe color
          * @return Reference to self (for method chaining)
          *
-         * Initial value is fully opaque black. Has effect only if
+         * Initial value is @cpp 0x000000ff_rgbaf @ce. Has effect only if
          * @ref Flag::Wireframe is enabled.
          */
         MeshVisualizer& setWireframeColor(const Color4& color) {

src/Magnum/Shaders/MeshVisualizer.vert

@@ -31,7 +31,11 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat4 transformationProjectionMatrix;
+uniform highp mat4 transformationProjectionMatrix
+    #ifndef GL_ES
+    = mat4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)

src/Magnum/Shaders/Phong.cpp

@@ -95,7 +95,7 @@ Phong::Phong(const Flags flags): _flags(flags) {
         _transformationMatrixUniform = uniformLocation("transformationMatrix");
         _projectionMatrixUniform = uniformLocation("projectionMatrix");
         _normalMatrixUniform = uniformLocation("normalMatrix");
-        _lightUniform = uniformLocation("light");
+        _lightPositionUniform = uniformLocation("lightPosition");
         _ambientColorUniform = uniformLocation("ambientColor");
         _diffuseColorUniform = uniformLocation("diffuseColor");
         _specularColorUniform = uniformLocation("specularColor");
@@ -118,13 +118,16 @@ Phong::Phong(const Flags flags): _flags(flags) {
     /* Default to fully opaque white so we can see the textures */
     if(flags & Flag::AmbientTexture) setAmbientColor(Color4{1.0f});
     else setAmbientColor(Color4{0.0f, 1.0f});
-
+    setDiffuseColor(Color4{1.0f});
-    if(flags & Flag::DiffuseTexture) setDiffuseColor(Color4{1.0f});
-
     setSpecularColor(Color4{1.0f});
     setLightColor(Color4{1.0f});
     setShininess(80.0f);
     if(flags & Flag::AlphaMask) setAlphaMask(0.5f);
+
+    setTransformationMatrix({});
+    setProjectionMatrix({});
+    setNormalMatrix({});
+    /* Light position is zero by default */
     #endif
 }
 

src/Magnum/Shaders/Phong.frag

@@ -64,7 +64,7 @@ uniform lowp sampler2D diffuseTexture;
 layout(location = 5)
 #endif
 uniform lowp vec4 diffuseColor
-    #if !defined(GL_ES) && defined(DIFFUSE_TEXTURE)
+    #ifndef GL_ES
     = vec4(1.0)
     #endif
     ;

src/Magnum/Shaders/Phong.h

@@ -41,9 +41,11 @@ namespace Magnum { namespace Shaders {
 @brief Phong shader
 
 Uses ambient, diffuse and specular color or texture. For colored mesh you need
-to provide @ref Position and @ref Normal attributes in your triangle mesh and
+to provide the @ref Position and @ref Normal attributes in your triangle mesh.
-call at least @ref setTransformationMatrix(), @ref setNormalMatrix(),
+By default, the shader renders the mesh with a white color in an identity
-@ref setProjectionMatrix(), @ref setDiffuseColor() and @ref setLightPosition().
+transformation. Use @ref setTransformationMatrix(), @ref setNormalMatrix(),
+@ref setProjectionMatrix(), @ref setLightPosition() and others to configure
+the shader.
 
 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
@@ -216,7 +218,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         }
 
         /**
-         * @brief Bind ambient texture
+         * @brief Bind an ambient texture
          * @return Reference to self (for method chaining)
          *
          * Expects that the shader was created with @ref Flag::AmbientTexture
@@ -238,9 +240,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @brief Set diffuse color
          * @return Reference to self (for method chaining)
          *
-         * If @ref Flag::DiffuseTexture is set, default value is
+         * Initial value is @cpp 0xffffffff_rgbaf @ce.
-         * @cpp 0xffffffff_rgbaf @ce and the color will be multiplied with
-         * diffuse texture.
          * @see @ref bindDiffuseTexture()
          */
         Phong& setDiffuseColor(const Color4& color) {
@@ -249,7 +249,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         }
 
         /**
-         * @brief Bind diffuse texture
+         * @brief Bind a diffuse texture
          * @return Reference to self (for method chaining)
          *
          * Expects that the shader was created with @ref Flag::DiffuseTexture
@@ -271,10 +271,10 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @brief Set specular color
          * @return Reference to self (for method chaining)
          *
-         * Default value is @cpp 0xffffffff_rgbaf @ce. Color will be multiplied
+         * Initial value is @cpp 0xffffffff_rgbaf @ce. Color will be multiplied
          * with specular texture if @ref Flag::SpecularTexture is set. If you
          * want to have a fully diffuse material, set specular color to
-         * @cpp 0x000000_rgbf @ce.
+         * @cpp 0x000000ff_rgbaf @ce.
          * @see @ref bindSpecularTexture()
          */
         Phong& setSpecularColor(const Color4& color) {
@@ -283,7 +283,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         }
 
         /**
-         * @brief Bind specular texture
+         * @brief Bind a specular texture
          * @return Reference to self (for method chaining)
          *
          * Expects that the shader was created with @ref Flag::SpecularTexture
@@ -306,8 +306,8 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @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.
+         * @ref Phong::Flag "Flag" is set, you can use @cpp nullptr @ce for the
-         * Expects that the shader was created with at least one of
+         * rest. Expects that the shader was created with at least one of
          * @ref Flag::AmbientTexture, @ref Flag::DiffuseTexture or
          * @ref Flag::SpecularTexture enabled. More efficient than setting each
          * texture separately.
@@ -330,7 +330,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @return Reference to self (for method chaining)
          *
          * The larger value, the harder surface (smaller specular highlight).
-         * If not set, default value is @cpp 80.0f @ce.
+         * Initial value is @cpp 80.0f @ce.
          */
         Phong& setShininess(Float shininess) {
             setUniform(_shininessUniform, shininess);
@@ -343,7 +343,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          *
          * Expects that the shader was created with @ref Flag::AlphaMask
          * enabled. Fragments with alpha values smaller than the mask value
-         * will be discarded. Default is @cpp 0.5f @ce. See the flag
+         * will be discarded. Initial value is @cpp 0.5f @ce. See the flag
          * documentation for further information.
          */
         Phong& setAlphaMask(Float mask);
@@ -351,6 +351,9 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         /**
          * @brief Set transformation matrix
          * @return Reference to self (for method chaining)
+         *
+         * You need to set also @ref setNormalMatrix() with a corresponding
+         * value. Initial value is an identity matrix.
          */
         Phong& setTransformationMatrix(const Matrix4& matrix) {
             setUniform(_transformationMatrixUniform, matrix);
@@ -362,7 +365,9 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @return Reference to self (for method chaining)
          *
          * The matrix doesn't need to be normalized, as the renormalization
-         * must be done in the shader anyway.
+         * must be done in the shader anyway. You need to set also
+         * @ref setTransformationMatrix() with a corresponding value. Initial
+         * value is an identity matrix.
          */
         Phong& setNormalMatrix(const Matrix3x3& matrix) {
             setUniform(_normalMatrixUniform, matrix);
@@ -372,6 +377,10 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         /**
          * @brief Set projection matrix
          * @return Reference to self (for method chaining)
+         *
+         * Initial value is an identity matrix (i.e., an orthographic
+         * projection of the default @f$ [ -\boldsymbol{1} ; \boldsymbol{1} ] @f$
+         * cube).
          */
         Phong& setProjectionMatrix(const Matrix4& matrix) {
             setUniform(_projectionMatrixUniform, matrix);
@@ -381,9 +390,13 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         /**
          * @brief Set light position
          * @return Reference to self (for method chaining)
+         *
+         * Initial value is a zero vector --- that will in most cases cause the
+         * object to be rendered black (or in the ambient color), as the light
+         * is inside of it.
          */
         Phong& setLightPosition(const Vector3& light) {
-            setUniform(_lightUniform, light);
+            setUniform(_lightPositionUniform, light);
             return *this;
         }
 
@@ -391,7 +404,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @brief Set light color
          * @return Reference to self (for method chaining)
          *
-         * If not set, default value is @cpp 0xffffffff_rgbaf @ce.
+         * Initial value is @cpp 0xffffffff_rgbaf @ce.
          */
         Phong& setLightColor(const Color4& color) {
             setUniform(_lightColorUniform, color);
@@ -403,7 +416,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
         Int _transformationMatrixUniform{0},
             _projectionMatrixUniform{1},
             _normalMatrixUniform{2},
-            _lightUniform{3},
+            _lightPositionUniform{3},
             _ambientColorUniform{4},
             _diffuseColorUniform{5},
             _specularColorUniform{6},

src/Magnum/Shaders/Phong.vert

@@ -31,22 +31,34 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 0)
 #endif
-uniform highp mat4 transformationMatrix;
+uniform highp mat4 transformationMatrix
+    #ifndef GL_ES
+    = mat4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 1)
 #endif
-uniform highp mat4 projectionMatrix;
+uniform highp mat4 projectionMatrix
+    #ifndef GL_ES
+    = mat4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 2)
 #endif
-uniform mediump mat3 normalMatrix;
+uniform mediump mat3 normalMatrix
+    #ifndef GL_ES
+    = mat3(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 3)
 #endif
-uniform highp vec3 light;
+uniform highp vec3 lightPosition; /* defaults to zero */
 
 #ifdef EXPLICIT_ATTRIB_LOCATION
 layout(location = POSITION_ATTRIBUTE_LOCATION)
@@ -80,7 +92,7 @@ void main() {
     transformedNormal = normalMatrix*normal;
 
     /* Direction to the light */
-    lightDirection = normalize(light - transformedPosition);
+    lightDirection = normalize(lightPosition - transformedPosition);
 
     /* Direction to the camera */
     cameraDirection = -transformedPosition;

src/Magnum/Shaders/Vector.cpp

@@ -93,6 +93,12 @@ template<UnsignedInt dimensions> Vector<dimensions>::Vector() {
     {
         GL::AbstractShaderProgram::setUniform(GL::AbstractShaderProgram::uniformLocation("vectorTexture"), AbstractVector<dimensions>::VectorTextureLayer);
     }
+
+    /* Set defaults in OpenGL ES (for desktop they are set in shader code itself) */
+    #ifdef MAGNUM_TARGET_GLES
+    setTransformationProjectionMatrix({});
+    setColor(Color4{1.0f}); /* Background color is zero by default */
+    #endif
 }
 
 template class Vector<2>;

src/Magnum/Shaders/Vector.frag

@@ -32,12 +32,16 @@
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 1)
 #endif
-uniform lowp vec4 backgroundColor;
+uniform lowp vec4 backgroundColor; /* defaults to zero */
 
 #ifdef EXPLICIT_UNIFORM_LOCATION
 layout(location = 2)
 #endif
-uniform lowp vec4 color;
+uniform lowp vec4 color
+    #ifndef GL_ES
+    = vec4(1.0)
+    #endif
+    ;
 
 #ifdef EXPLICIT_TEXTURE_LAYER
 layout(binding = 15)

src/Magnum/Shaders/Vector.h

@@ -42,11 +42,13 @@ namespace Magnum { namespace Shaders {
 @brief Vector shader
 
 Renders vector art in plain grayscale form. See also @ref DistanceFieldVector
-for more advanced effects. For rendering unchanged texture you can use the
+for more advanced effects. For rendering an unchanged texture you can use the
-@ref Flat shader. You need to provide @ref Position and @ref TextureCoordinates
+@ref Flat shader. You need to provide the @ref Position and
-attributes in your triangle mesh and call at least
+@ref TextureCoordinates attributes in your triangle mesh and call at least
-@ref setTransformationProjectionMatrix(), @ref setColor() and
+@ref bindVectorTexture(). By default, the shader renders the texture with a
-@ref bindVectorTexture().
+white color in an identity transformation. Use
+@ref setTransformationProjectionMatrix(), @ref setColor() and others to
+configure the shader.
 
 @image html shaders-vector.png
 @image latex shaders-vector.png
@@ -99,6 +101,8 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Vector: public Abst
         /**
          * @brief Set transformation and projection matrix
          * @return Reference to self (for method chaining)
+         *
+         * Default is an identity matrix.
          */
         Vector<dimensions>& setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) {
             GL::AbstractShaderProgram::setUniform(_transformationProjectionMatrixUniform, matrix);
@@ -109,7 +113,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Vector: public Abst
          * @brief Set background color
          * @return Reference to self (for method chaining)
          *
-         * Default is transparent black.
+         * Default is @cpp 0x00000000_rgbaf @ce.
          * @see @ref setColor()
          */
         Vector<dimensions>& setBackgroundColor(const Color4& color) {
@@ -121,6 +125,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Vector: public Abst
          * @brief Set fill color
          * @return Reference to self (for method chaining)
          *
+         * Default is @cpp 0xffffffff_rgbaf @ce.
          * @see @ref setBackgroundColor()
          */
         Vector<dimensions>& setColor(const Color4& color) {

src/Magnum/Shaders/VertexColor.h

@@ -43,8 +43,9 @@ namespace Magnum { namespace Shaders {
 @brief Vertex color shader
 
 Draws vertex-colored mesh. You need to provide @ref Position and @ref Color
-attributes in your triangle mesh and call at least
+attributes in your triangle mesh. By default, the shader renders the mesh in
-@ref setTransformationProjectionMatrix().
+an identity transformation. Use @ref setTransformationProjectionMatrix() to
+configure the shader.
 
 @image html shaders-vertexcolor.png
 
@@ -126,7 +127,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT VertexColor: public
          * @brief Set transformation and projection matrix
          * @return Reference to self (for method chaining)
          *
-         * Default is identity matrix.
+         * Default is an identity matrix.
          */
         VertexColor<dimensions>& setTransformationProjectionMatrix(const MatrixTypeFor<dimensions, Float>& matrix) {
             setUniform(_transformationProjectionMatrixUniform, matrix);