Text: document Renderer usage in 3D.

doc/snippets/Text-gl.cpp

@@ -30,6 +30,7 @@
 #include "Magnum/PixelFormat.h"
 #include "Magnum/Math/Color.h"
 #include "Magnum/Math/Matrix3.h"
+#include "Magnum/Math/Matrix4.h"
 #include "Magnum/Math/Range.h"
 #include "Magnum/GL/MeshView.h"
 #include "Magnum/GL/Renderer.h"
@@ -173,6 +174,36 @@ shader
 /* [Renderer-usage-draw] */
 }
 
+{
+Text::GlyphCacheGL cache{PixelFormat::R8Unorm, {256, 256}};
+Text::RendererGL renderer{cache};
+/* [Renderer-usage-draw-3d] */
+Matrix4 projection = DOXYGEN_ELLIPSIS({});
+Matrix4 transformation = DOXYGEN_ELLIPSIS({});
+
+Shaders::VectorGL3D shader;
+shader
+    .setTransformationProjectionMatrix(projection*transformation)
+    .bindVectorTexture(cache.texture())
+    .draw(renderer.mesh());
+/* [Renderer-usage-draw-3d] */
+}
+
+{
+Text::GlyphCacheGL cache{PixelFormat::R8Unorm, {256, 256}};
+Text::RendererGL renderer{cache};
+Matrix4 projection, transformation;
+/* [Renderer-usage-draw-3d-screen-space] */
+Shaders::VectorGL2D shader;
+shader
+    .setTransformationProjectionMatrix(
+        Matrix3::projection(Vector2{windowSize()})*
+        Matrix3::translation((projection*transformation).transformPoint({}).xy()))
+    .bindVectorTexture(cache.texture())
+    .draw(renderer.mesh());
+/* [Renderer-usage-draw-3d-screen-space] */
+}
+
 {
 
 PluginManager::Manager<Text::AbstractFont> manager;

src/Magnum/Text/Renderer.h

@@ -785,6 +785,19 @@ slightly different, see their documentation for examples.
 
 @snippet Text-gl.cpp Renderer-usage-draw
 
+The text is rendered with 2D positions but you can draw it with a 3D shader if
+you want perspective projection applied to it --- the third position coordinate
+will be implicitly @cpp 0.0f @ce in that case:
+
+@snippet Text-gl.cpp Renderer-usage-draw-3d
+
+However, if you want to place the text into 3D space but want it to always face
+the camera and be of the same size regardless of depth, use a 2D shader and
+apply the perspective projection to the 3D position it's being rendered at,
+turning it into a 2D screen-space position:
+
+@snippet Text-gl.cpp Renderer-usage-draw-3d-screen-space
+
 If you use just the base @ref Renderer, the rendered index and vertex data are
 exposed through @ref indices(), @ref vertexPositions() and
 @ref vertexTextureCoordinates() / @ref vertexTextureArrayCoordinates(), which