Shaders,Trade: clarify use{less,ful}ness of specular alpha.

src/Magnum/Shaders/Phong.cpp

@@ -208,7 +208,7 @@ Phong::Phong(const Flags flags, const UnsignedInt lightCount): _flags{flags}, _l
     setProjectionMatrix({});
     if(lightCount) {
         setDiffuseColor(Magnum::Color4{1.0f});
-        setSpecularColor(Magnum::Color4{1.0f});
+        setSpecularColor(Magnum::Color4{1.0f, 0.0f});
         setShininess(80.0f);
         setLightColors(Containers::Array<Magnum::Color4>{Containers::DirectInit, lightCount, Magnum::Color4{1.0f}});
         /* Light position is zero by default */

src/Magnum/Shaders/Phong.frag

@@ -93,7 +93,7 @@ layout(location = 6)
 #endif
 uniform lowp vec4 specularColor
     #ifndef GL_ES
-    = vec4(1.0)
+    = vec4(1.0, 1.0, 1.0, 0.0)
     #endif
     ;
 

src/Magnum/Shaders/Phong.h

@@ -80,6 +80,11 @@ working on the framebuffer, you need to enable
 @ref GL::Renderer::Feature::Blending and set up the blending function. See
 @ref GL::Renderer::setBlendFunction() for details.
 
+To avoid specular highlights on transparent areas, specular alpha should be
+always set to @cpp 0.0f @ce. On the other hand, non-zero specular alpha can be
+for example used to render transparent materials which are still expected to
+have specular highlights such as glass or soap bubbles.
+
 An alternative is to enable @ref Flag::AlphaMask and tune @ref setAlphaMask()
 for simple binary alpha-masked drawing that doesn't require depth sorting or
 blending enabled. Note that this feature is implemented using the GLSL
@@ -525,10 +530,10 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
          * @brief Set specular color
          * @return Reference to self (for method chaining)
          *
-         * Initial value is @cpp 0xffffffff_rgbaf @ce. Color will be multiplied
+         * Initial value is @cpp 0xffffff00_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 0x000000ff_rgbaf @ce. If @ref lightCount() is zero, this
+         * @cpp 0x00000000_rgbaf @ce. If @ref lightCount() is zero, this
          * function is a no-op, as specular color doesn't contribute to the
          * output in that case.
          * @see @ref bindSpecularTexture()

src/Magnum/Trade/PhongMaterialData.h

@@ -114,7 +114,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public AbstractMaterialData {
          * @param diffuseTexture    Diffuse texture ID. Ignored if @p flags
          *      doesn't have @ref Flag::DiffuseTexture
          * @param specularColor     Specular color. Use
-         *      @cpp 0xffffffff_rgbaf @ce for a default value for both a
+         *      @cpp 0xffffff00_rgbaf @ce for a default value for both a
          *      non-textured and a textured material.
          * @param specularTexture   Specular texture ID. Ignored if @p flags
          *      doesn't have @ref Flag::SpecularTexture.
@@ -155,7 +155,7 @@ class MAGNUM_TRADE_EXPORT PhongMaterialData: public AbstractMaterialData {
          * @param diffuseTextureCoordinates Diffuse texture coordinate set.
          *      Ignored if @p flags doesn't have @ref Flag::DiffuseTexture
          * @param specularColor         Specular color. Use
-         *      @cpp 0xffffffff_rgbaf @ce for a default value for both a
+         *      @cpp 0xffffff00_rgbaf @ce for a default value for both a
          *      non-textured and a textured material.
          * @param specularTexture       Specular texture ID. Ignored if
          *      @p flags doesn't have @ref Flag::SpecularTexture.