diff --git a/doc/changelog.dox b/doc/changelog.dox index 15763d611..2db8ddfe6 100644 --- a/doc/changelog.dox +++ b/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)) diff --git a/doc/snippets/MagnumGL.cpp b/doc/snippets/MagnumGL.cpp index ce3fa2ace..545c6406c 100644 --- a/doc/snippets/MagnumGL.cpp +++ b/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] */ diff --git a/src/Magnum/GL/Renderer.h b/src/Magnum/GL/Renderer.h index 616456b5b..04049628c 100644 --- a/src/Magnum/GL/Renderer.h +++ b/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} diff --git a/src/Magnum/Shaders/DistanceFieldVector.h b/src/Magnum/Shaders/DistanceFieldVector.h index 742872733..1abb87603 100644 --- a/src/Magnum/Shaders/DistanceFieldVector.h +++ b/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 diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h index 78ea0dced..9489b698f 100644 --- a/src/Magnum/Shaders/Flat.h +++ b/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 -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. +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. + +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 diff --git a/src/Magnum/Shaders/MeshVisualizer.h b/src/Magnum/Shaders/MeshVisualizer.h index cc6157983..c2cfee7d0 100644 --- a/src/Magnum/Shaders/MeshVisualizer.h +++ b/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: diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h index 8b66448e4..234328cda 100644 --- a/src/Magnum/Shaders/Phong.h +++ b/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 -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. +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. + +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 diff --git a/src/Magnum/Shaders/Vector.h b/src/Magnum/Shaders/Vector.h index 942de64a1..6524f3117 100644 --- a/src/Magnum/Shaders/Vector.h +++ b/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: diff --git a/src/Magnum/Shaders/VertexColor.h b/src/Magnum/Shaders/VertexColor.h index e206a84a5..bb166ff43 100644 --- a/src/Magnum/Shaders/VertexColor.h +++ b/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