diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt index 3254eb7eb..41321f9d2 100644 --- a/doc/snippets/CMakeLists.txt +++ b/doc/snippets/CMakeLists.txt @@ -92,7 +92,7 @@ if(MAGNUM_WITH_GL) MagnumGL.cpp MagnumMeshTools-gl.cpp MagnumShaders-gl.cpp - MagnumText.cpp) + MagnumText-gl.cpp) target_link_libraries(snippets-MagnumGL PRIVATE MagnumGL) if(CORRADE_TESTSUITE_TEST_TARGET) add_dependencies(${CORRADE_TESTSUITE_TEST_TARGET} snippets-MagnumGL) @@ -117,6 +117,15 @@ if(MAGNUM_WITH_SHADERTOOLS) endif() endif() +if(MAGNUM_WITH_TEXT) + add_library(snippets-MagnumText STATIC ${EXCLUDE_FROM_ALL_IF_TEST_TARGET} + MagnumText.cpp) + target_link_libraries(snippets-MagnumText PRIVATE MagnumText) + if(CORRADE_TESTSUITE_TEST_TARGET) + add_dependencies(${CORRADE_TESTSUITE_TEST_TARGET} snippets-MagnumText) + endif() +endif() + if(MAGNUM_WITH_TEXTURETOOLS) add_library(snippets-MagnumTextureTools STATIC ${EXCLUDE_FROM_ALL_IF_TEST_TARGET} MagnumTextureTools.cpp) diff --git a/doc/snippets/MagnumText-gl.cpp b/doc/snippets/MagnumText-gl.cpp new file mode 100644 index 000000000..91f7b2350 --- /dev/null +++ b/doc/snippets/MagnumText-gl.cpp @@ -0,0 +1,163 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, + 2020, 2021, 2022, 2023 Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +#include +#include + +#include "Magnum/Math/Color.h" +#include "Magnum/Math/Matrix3.h" +#include "Magnum/Shaders/VectorGL.h" +#include "Magnum/Text/AbstractFont.h" +#include "Magnum/Text/DistanceFieldGlyphCache.h" +#include "Magnum/Text/Renderer.h" + +#define DOXYGEN_ELLIPSIS(...) __VA_ARGS__ + +using namespace Magnum; +using namespace Magnum::Math::Literals; + +namespace { + Vector2i windowSize() { return {}; } + Vector2i framebufferSize() { return {}; } + Vector2 dpiScaling() { return {}; } +} + +int main() { + +{ +/* [AbstractFont-usage] */ +PluginManager::Manager manager; +Containers::Pointer font = + manager.loadAndInstantiate("StbTrueTypeFont"); +if(!font->openFile("font.ttf", 12.0f)) + Fatal{} << "Can't open font.ttf with StbTrueTypeFont"; + +Text::GlyphCache cache{Vector2i{128}}; +font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789?!:;,. "); +/* [AbstractFont-usage] */ +} + +{ +/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize + the font pointer. I don't care, I just want you to check compilation errors, + not more! */ +PluginManager::Manager manager; +/* [DistanceFieldGlyphCache-usage] */ +Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); +font->openFile("font.ttf", 96.0f); + +Text::DistanceFieldGlyphCache cache{Vector2i{1024}, Vector2i{128}, 12}; +font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789?!:;,. "); +/* [DistanceFieldGlyphCache-usage] */ +} + +{ +/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize + the font pointer. I don't care, I just want you to check compilation errors, + not more! */ +PluginManager::Manager manager; +/* [GlyphCache-usage] */ +Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); +font->openFile("font.ttf", 12.0f); + +Text::GlyphCache cache{Vector2i{128}}; +font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789?!:;,. "); +/* [GlyphCache-usage] */ +} + +{ +/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize + the font pointer. I don't care, I just want you to check compilation errors, + not more! */ +PluginManager::Manager manager; +/* [Renderer-usage1] */ +/* Font instance, received from a plugin manager */ +Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); + +/* Open a 12 pt font */ +font->openFile("font.ttf", 12.0f); + +/* Populate a glyph cache */ +Text::GlyphCache cache{Vector2i{128}}; +font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789?!:;,. "); + +Shaders::VectorGL2D shader; +GL::Buffer vertexBuffer, indexBuffer; +GL::Mesh mesh; + +/* Render a 12 pt text, centered */ +std::tie(mesh, std::ignore) = Text::Renderer2D::render(*font, cache, 12.0f, + "Hello World!", vertexBuffer, indexBuffer, GL::BufferUsage::StaticDraw, + Text::Alignment::LineCenter); + +/* Projection matrix is matching application window size to have the size match + 12 pt in other applications, assuming a 96 DPI display and no UI scaling. */ +Matrix3 projectionMatrix = Matrix3::projection(Vector2{windowSize()}); + +/* Draw the text on the screen */ +shader + .setTransformationProjectionMatrix(projectionMatrix) + .setColor(0xffffff_rgbf) + .bindVectorTexture(cache.texture()) + .draw(mesh); +/* [Renderer-usage1] */ + +/* [Renderer-usage2] */ +/* Initialize the renderer and reserve memory for enough glyphs */ +Text::Renderer2D renderer{*font, cache, 12.0f, Text::Alignment::LineCenter}; +renderer.reserve(32, GL::BufferUsage::DynamicDraw, GL::BufferUsage::StaticDraw); + +/* Update the text occasionally */ +renderer.render("Hello World Countdown: 10"); + +/* Draw the text on the screen */ +shader.setTransformationProjectionMatrix(projectionMatrix) + .setColor(0xffffff_rgbf) + .bindVectorTexture(cache.texture()) + .draw(renderer.mesh()); +/* [Renderer-usage2] */ +} + +{ +/* [Renderer-dpi-interface-size] */ +Vector2 interfaceSize = Vector2{windowSize()}/dpiScaling(); +/* [Renderer-dpi-interface-size] */ +/* [Renderer-dpi-size-multiplier] */ +Float sizeMultiplier = + (Vector2{framebufferSize()}*dpiScaling()/Vector2{windowSize()}).max(); +/* [Renderer-dpi-size-multiplier] */ +static_cast(interfaceSize); +static_cast(sizeMultiplier); +} + +} diff --git a/doc/snippets/MagnumText.cpp b/doc/snippets/MagnumText.cpp index b28831685..3c521ed68 100644 --- a/doc/snippets/MagnumText.cpp +++ b/doc/snippets/MagnumText.cpp @@ -27,6 +27,8 @@ affect anything else. */ #define CORRADE_STATIC_PLUGIN +#include +#include #include #include #include @@ -38,11 +40,8 @@ #include "Magnum/FileCallback.h" #include "Magnum/Math/Color.h" #include "Magnum/Math/Matrix3.h" -#include "Magnum/Shaders/VectorGL.h" #include "Magnum/Text/AbstractFont.h" #include "Magnum/Text/AbstractFontConverter.h" -#include "Magnum/Text/DistanceFieldGlyphCache.h" -#include "Magnum/Text/Renderer.h" #define DOXYGEN_ELLIPSIS(...) __VA_ARGS__ @@ -80,29 +79,8 @@ CORRADE_PLUGIN_REGISTER(MyFontConverter, MyNamespace::MyFontConverter, MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE) /* [MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE] */ -namespace { - Vector2i windowSize() { return {}; } - Vector2i framebufferSize() { return {}; } - Vector2 dpiScaling() { return {}; } -} - int main() { -{ -/* [AbstractFont-usage] */ -PluginManager::Manager manager; -Containers::Pointer font = - manager.loadAndInstantiate("StbTrueTypeFont"); -if(!font->openFile("font.ttf", 12.0f)) - Fatal{} << "Can't open font.ttf with StbTrueTypeFont"; - -Text::GlyphCache cache{Vector2i{128}}; -font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789?!:;,. "); -/* [AbstractFont-usage] */ -} - { PluginManager::Manager manager; Containers::Pointer font = @@ -184,103 +162,4 @@ font->setFileCallback([](const std::string& filename, /* [AbstractFont-setFileCallback-template] */ } -{ -/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize - the font pointer. I don't care, I just want you to check compilation errors, - not more! */ -PluginManager::Manager manager; -/* [DistanceFieldGlyphCache-usage] */ -Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); -font->openFile("font.ttf", 96.0f); - -Text::DistanceFieldGlyphCache cache{Vector2i{1024}, Vector2i{128}, 12}; -font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789?!:;,. "); -/* [DistanceFieldGlyphCache-usage] */ -} - -{ -/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize - the font pointer. I don't care, I just want you to check compilation errors, - not more! */ -PluginManager::Manager manager; -/* [GlyphCache-usage] */ -Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); -font->openFile("font.ttf", 12.0f); - -Text::GlyphCache cache{Vector2i{128}}; -font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789?!:;,. "); -/* [GlyphCache-usage] */ -} - -{ -/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize - the font pointer. I don't care, I just want you to check compilation errors, - not more! */ -PluginManager::Manager manager; -/* [Renderer-usage1] */ -/* Font instance, received from a plugin manager */ -Containers::Pointer font = DOXYGEN_ELLIPSIS(manager.loadAndInstantiate("")); - -/* Open a 12 pt font */ -font->openFile("font.ttf", 12.0f); - -/* Populate a glyph cache */ -Text::GlyphCache cache{Vector2i{128}}; -font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz" - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "0123456789?!:;,. "); - -Shaders::VectorGL2D shader; -GL::Buffer vertexBuffer, indexBuffer; -GL::Mesh mesh; - -/* Render a 12 pt text, centered */ -std::tie(mesh, std::ignore) = Text::Renderer2D::render(*font, cache, 12.0f, - "Hello World!", vertexBuffer, indexBuffer, GL::BufferUsage::StaticDraw, - Text::Alignment::LineCenter); - -/* Projection matrix is matching application window size to have the size match - 12 pt in other applications, assuming a 96 DPI display and no UI scaling. */ -Matrix3 projectionMatrix = Matrix3::projection(Vector2{windowSize()}); - -/* Draw the text on the screen */ -shader - .setTransformationProjectionMatrix(projectionMatrix) - .setColor(0xffffff_rgbf) - .bindVectorTexture(cache.texture()) - .draw(mesh); -/* [Renderer-usage1] */ - -/* [Renderer-usage2] */ -/* Initialize the renderer and reserve memory for enough glyphs */ -Text::Renderer2D renderer{*font, cache, 12.0f, Text::Alignment::LineCenter}; -renderer.reserve(32, GL::BufferUsage::DynamicDraw, GL::BufferUsage::StaticDraw); - -/* Update the text occasionally */ -renderer.render("Hello World Countdown: 10"); - -/* Draw the text on the screen */ -shader.setTransformationProjectionMatrix(projectionMatrix) - .setColor(0xffffff_rgbf) - .bindVectorTexture(cache.texture()) - .draw(renderer.mesh()); -/* [Renderer-usage2] */ -} - -{ -/* [Renderer-dpi-interface-size] */ -Vector2 interfaceSize = Vector2{windowSize()}/dpiScaling(); -/* [Renderer-dpi-interface-size] */ -/* [Renderer-dpi-size-multiplier] */ -Float sizeMultiplier = - (Vector2{framebufferSize()}*dpiScaling()/Vector2{windowSize()}).max(); -/* [Renderer-dpi-size-multiplier] */ -static_cast(interfaceSize); -static_cast(sizeMultiplier); -} - } diff --git a/src/Magnum/Text/AbstractFont.h b/src/Magnum/Text/AbstractFont.h index 531ca0a12..027459d14 100644 --- a/src/Magnum/Text/AbstractFont.h +++ b/src/Magnum/Text/AbstractFont.h @@ -109,7 +109,7 @@ In the following example a font is loaded from the filesystem using the @ref StbTrueTypeFont plugin, prerendering all needed glyphs, completely with all error handling: -@snippet MagnumText.cpp AbstractFont-usage +@snippet MagnumText-gl.cpp AbstractFont-usage See @ref plugins for more information about general plugin usage and the list of @m_class{m-doc} [derived classes](#derived-classes) for available font diff --git a/src/Magnum/Text/DistanceFieldGlyphCache.h b/src/Magnum/Text/DistanceFieldGlyphCache.h index e8d299e19..356412ec2 100644 --- a/src/Magnum/Text/DistanceFieldGlyphCache.h +++ b/src/Magnum/Text/DistanceFieldGlyphCache.h @@ -66,7 +66,7 @@ outlining, thinning, thickening or shadow effects will be used when rendering, using them leads to precision loss when the distance field is stored in 8-bit channels. -@snippet MagnumText.cpp DistanceFieldGlyphCache-usage +@snippet MagnumText-gl.cpp DistanceFieldGlyphCache-usage @note This class is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features diff --git a/src/Magnum/Text/GlyphCache.h b/src/Magnum/Text/GlyphCache.h index 7c5318175..6f22960fb 100644 --- a/src/Magnum/Text/GlyphCache.h +++ b/src/Magnum/Text/GlyphCache.h @@ -47,7 +47,7 @@ Contains font glyphs rendered into a texture atlas. Create the @ref GlyphCache object with sufficient size and then call @ref AbstractFont::createGlyphCache() to fill it with glyphs. -@snippet MagnumText.cpp GlyphCache-usage +@snippet MagnumText-gl.cpp GlyphCache-usage See the @ref Renderer class for information about text rendering. diff --git a/src/Magnum/Text/Renderer.h b/src/Magnum/Text/Renderer.h index fda88e09f..56beaa791 100644 --- a/src/Magnum/Text/Renderer.h +++ b/src/Magnum/Text/Renderer.h @@ -188,7 +188,7 @@ methods, returning result either as data arrays or as fully configured mesh. The text can be then drawn as usual by configuring the shader and drawing the mesh: -@snippet MagnumText.cpp Renderer-usage1 +@snippet MagnumText-gl.cpp Renderer-usage1 See @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, GL::Buffer&, GL::Buffer&, GL::BufferUsage, Alignment) @@ -198,7 +198,7 @@ While this method is sufficient for one-shot rendering of static texts, for mutable texts (e.g. FPS counters, chat messages) there is another approach that doesn't recreate everything on each text change: -@snippet MagnumText.cpp Renderer-usage2 +@snippet MagnumText-gl.cpp Renderer-usage2 @subsection Text-Renderer-usage-font-size Font size @@ -260,12 +260,12 @@ documented thoroughly in @ref Platform-Sdl2Application-dpi, for this particular case a scaled interface size, used instead of window size for the projection, would be calculated like this: -@snippet MagnumText.cpp Renderer-dpi-interface-size +@snippet MagnumText-gl.cpp Renderer-dpi-interface-size And a multiplier for the @ref AbstractFont and @ref GlyphCache font size like this. The @ref Renderer keeps using the size without this multiplier. -@snippet MagnumText.cpp Renderer-dpi-size-multiplier +@snippet MagnumText-gl.cpp Renderer-dpi-size-multiplier @section Text-Renderer-required-opengl-functionality Required OpenGL functionality