doc: show how to set up blending for alpha / transparency.

Hopefully more discoverable now also.

doc/changelog.dox

@@ -658,8 +658,9 @@ See also:
 
 @subsection changelog-latest-documentation Documentation
 
--   Various fixes and clarifications (see
+-   Various fixes, improvements and clarifications (see
     [mosra/magnum#390](https://github.com/mosra/magnum/pull/390),
+    [mosra/magnum#394](https://github.com/mosra/magnum/pull/394),
     [mosra/magnum#418](https://github.com/mosra/magnum/pull/418),
     [mosra/magnum#424](https://github.com/mosra/magnum/pull/424))
 

doc/snippets/MagnumGL.cpp

@@ -1330,6 +1330,15 @@ enabled ? GL::Renderer::enable(feature) : GL::Renderer::disable(feature)
 ;
 }
 
+{
+/* [Renderer-setBlendFunction] */
+GL::Renderer::enable(GL::Renderer::Feature::Blending);
+GL::Renderer::setBlendFunction(
+    GL::Renderer::BlendFunction::One, /* or SourceAlpha for non-premultiplied */
+    GL::Renderer::BlendFunction::OneMinusSourceAlpha);
+/* [Renderer-setBlendFunction] */
+}
+
 #if !(defined(MAGNUM_TARGET_GLES2) && defined(MAGNUM_TARGET_WEBGL))
 {
 /* [SampleQuery-usage] */

src/Magnum/GL/Renderer.h

@@ -1000,7 +1000,7 @@ class MAGNUM_GL_EXPORT Renderer {
         /**
          * @{ @name Blending
          *
-         * You have to enable blending with @ref enable() first.
+         * You have to enable @ref Feature::Blending first.
          * @todo Blending for given draw buffer
          */
 
@@ -1433,6 +1433,20 @@ class MAGNUM_GL_EXPORT Renderer {
          * @param destination   How the destination blending factor is
          *      computed from framebuffer. Initial value is @ref BlendFunction::Zero.
          *
+         * @m_keyword{Alpha blending,,}
+         * @m_keywords{Blending Transparency}
+         *
+         * Common setup for alpha blending is the following, depending on
+         * whether your colors / textures have a [premultiplied alpha](https://developer.nvidia.com/content/alpha-blending-pre-or-not-pre)
+         * (RGB channels always less than or equal to the alpha) or not:
+         *
+         * @snippet MagnumGL.cpp Renderer-setBlendFunction
+         *
+         * Note that in 3D you need to sort and render transparent objects
+         * back-to-front after all opaque objects in order for them to appear
+         * correctly. Alternatively, builtin shaders such as @ref Shaders::Flat
+         * or @ref Shaders::Phong support alpha masking, which works without
+         * alpha blending enabled and doesn't require depth sorting.
          * @see @ref Feature::Blending, @ref setBlendFunction(BlendFunction, BlendFunction, BlendFunction, BlendFunction),
          *      @ref setBlendEquation(), @ref setBlendColor(),
          *      @fn_gl_keyword{BlendFunc}

src/Magnum/Shaders/DistanceFieldVector.h

@@ -55,6 +55,11 @@ texture with a white color in an identity transformation, use
 @ref setTransformationProjectionMatrix(), @ref setColor() and others to
 configure the shader.
 
+Alpha / transparency is supported by the shader implicitly, but to have it
+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.
+
 @image html shaders-distancefieldvector.png width=256px
 
 @section Shaders-DistanceFieldVector-usage Example usage

src/Magnum/Shaders/Flat.h

@@ -96,12 +96,17 @@ texturing makes this shader equivalent to @ref VertexColor.
 
 @section Shaders-Flat-alpha Alpha blending and masking
 
-Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple
+Alpha / transparency is supported by the shader implicitly, but to have it
-binary alpha-masked drawing that doesn't require depth sorting or blending
+working on the framebuffer, you need to enable
-enabled. Note that this feature is implemented using the GLSL @glsl discard @ce
+@ref GL::Renderer::Feature::Blending and set up the blending function. See
-operation which is known to have considerable performance impact on some
+@ref GL::Renderer::setBlendFunction() for details.
-platforms. With proper depth sorting and blending you'll usually get much
+
-better performance and output quality.
+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
+@glsl discard @ce operation which is known to have considerable performance
+impact on some platforms. With proper depth sorting and blending you'll usually
+get much better performance and output quality.
 
 @section Shaders-Flat-object-id Object ID output
 

src/Magnum/Shaders/MeshVisualizer.h

@@ -381,6 +381,12 @@ If using geometry shaders on OpenGL ES, @gl_extension{NV,shader_noperspective_in
 is optionally used for improving line appearance. On desktop OpenGL this is
 done implicitly.
 
+If you want to render just the wireframe on top of an existing mesh, call
+@ref setColor() with @cpp 0x00000000_rgbaf @ce. Alpha / transparency is
+supported by the shader implicitly, but to have it 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.
+
 @subsection Shaders-MeshVisualizer-wireframe-geom Example setup with a geometry shader (desktop GL, OpenGL ES 3.2)
 
 Common mesh setup:

src/Magnum/Shaders/Phong.h

@@ -75,12 +75,17 @@ Common rendering setup:
 
 @section Shaders-Phong-alpha Alpha blending and masking
 
-Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple
+Alpha / transparency is supported by the shader implicitly, but to have it
-binary alpha-masked drawing that doesn't require depth sorting or blending
+working on the framebuffer, you need to enable
-enabled. Note that this feature is implemented using the GLSL @glsl discard @ce
+@ref GL::Renderer::Feature::Blending and set up the blending function. See
-operation which is known to have considerable performance impact on some
+@ref GL::Renderer::setBlendFunction() for details.
-platforms. With proper depth sorting and blending you'll usually get much
+
-better performance and output quality.
+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
+@glsl discard @ce operation which is known to have considerable performance
+impact on some platforms. With proper depth sorting and blending you'll usually
+get much better performance and output quality.
 
 For general alpha-masked drawing you need to provide an ambient texture with
 alpha channel and set alpha channel of the diffuse/specular color to @cpp 0.0f @ce

src/Magnum/Shaders/Vector.h

@@ -56,6 +56,11 @@ configure the shader.
 
 @image html shaders-vector.png width=256px
 
+Alpha / transparency is supported by the shader implicitly, but to have it
+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.
+
 @section Shaders-Vector-usage Example usage
 
 Common mesh setup:

src/Magnum/Shaders/VertexColor.h

@@ -51,6 +51,11 @@ enabled; the 3D version of this shader is equivalent to @ref Phong with
 @ref Phong::Flag::VertexColor enabled. In both cases this implementation is
 much simpler and thus likely also faster.
 
+Alpha / transparency is supported by the shader implicitly, but to have it
+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.
+
 @section Shaders-VertexColor-example Example usage
 
 Common mesh setup. The shader accepts either three- or four-component color