mirror of https://github.com/mosra/magnum.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1232 lines
59 KiB
1232 lines
59 KiB
#ifndef Magnum_Text_Renderer_h |
|
#define Magnum_Text_Renderer_h |
|
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, |
|
2020, 2021, 2022, 2023, 2024, 2025 |
|
Vladimír Vondruš <mosra@centrum.cz> |
|
|
|
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. |
|
*/ |
|
|
|
/** @file |
|
* @brief Class @ref Magnum::Text::RendererCore, @ref Magnum::Text::AbstractRenderer, typedef @ref Magnum::Text::Renderer2D, @ref Magnum::Text::Renderer3D, function @ref Magnum::Text::renderLineGlyphPositionsInto(), @ref Magnum::Text::renderGlyphQuadsInto(), @ref Magnum::Text::glyphQuadBounds(), @ref Magnum::Text::alignRenderedLine(), @ref Magnum::Text::alignRenderedBlock(), @ref Magnum::Text::renderGlyphQuadIndicesInto(), @ref Magnum::Text::glyphRangeForBytes() |
|
*/ |
|
|
|
#include <initializer_list> |
|
#include <Corrade/Containers/Pointer.h> |
|
|
|
#include "Magnum/Magnum.h" |
|
#include "Magnum/Text/Text.h" |
|
#include "Magnum/Text/visibility.h" |
|
|
|
#ifdef MAGNUM_TARGET_GL |
|
#include <Corrade/Utility/StlForwardTuple.h> |
|
#include <Corrade/Utility/StlForwardVector.h> |
|
#include <Corrade/Utility/StlForwardString.h> |
|
|
|
#include "Magnum/DimensionTraits.h" |
|
#include "Magnum/Math/Range.h" |
|
#include "Magnum/GL/Buffer.h" |
|
#include "Magnum/GL/Mesh.h" |
|
#include "Magnum/Text/Alignment.h" |
|
|
|
#ifdef CORRADE_TARGET_EMSCRIPTEN |
|
#include <Corrade/Containers/Array.h> |
|
#endif |
|
#endif |
|
|
|
namespace Magnum { namespace Text { |
|
|
|
/** |
|
@brief Text renderer core flag |
|
@m_since_latest |
|
|
|
@see @ref RendererFlags, @ref Renderer |
|
*/ |
|
enum class RendererCoreFlag: UnsignedByte { |
|
/** |
|
* Populate glyph cluster info in @ref RendererCore::glyphClusters() for |
|
* text selection and editing purposes. |
|
*/ |
|
GlyphClusters = 1 << 0, |
|
}; |
|
|
|
/** |
|
* @debugoperatorenum{RendererCoreFlag} |
|
* @m_since_latest |
|
*/ |
|
MAGNUM_TEXT_EXPORT Debug& operator<<(Debug& output, RendererCoreFlag value); |
|
|
|
/** |
|
@brief Text renderer core flags |
|
@m_since_latest |
|
|
|
@see @ref Renderer |
|
*/ |
|
typedef Containers::EnumSet<RendererCoreFlag> RendererCoreFlags; |
|
|
|
CORRADE_ENUMSET_OPERATORS(RendererCoreFlags) |
|
|
|
/** |
|
* @debugoperatorenum{RendererCoreFlags} |
|
* @m_since_latest |
|
*/ |
|
MAGNUM_TEXT_EXPORT Debug& operator<<(Debug& output, RendererCoreFlags value); |
|
|
|
/** |
|
@brief Text renderer core |
|
@m_since_latest |
|
*/ |
|
class MAGNUM_TEXT_EXPORT RendererCore { |
|
public: |
|
/** |
|
* @brief Construct |
|
* @param glyphCache Glyph cache to use for glyph ID mapping |
|
* @param flags Opt-in feature flags |
|
* |
|
* By default, the renderer allocates the memory for glyph and run data |
|
* internally. Use the overload below to supply external allocators. |
|
* @todoc the damn thing can't link to functions taking functions |
|
*/ |
|
explicit RendererCore(const AbstractGlyphCache& glyphCache, RendererCoreFlags flags = {}): RendererCore{glyphCache, nullptr, nullptr, nullptr, nullptr, flags} {} |
|
|
|
/** |
|
* @brief Construct with external allocators |
|
* @param glyphCache Glyph cache to use for glyph ID mapping |
|
* @param glyphAllocator Glyph allocator function or |
|
* @cpp nullptr @ce |
|
* @param glyphAllocatorState State pointer to pass to |
|
* @p glyphAllocator |
|
* @param runAllocator Run allocator function or @cpp nullptr @ce |
|
* @param runAllocatorState State pointer to pass to @p runAllocator |
|
* @param flags Opt-in feature flags |
|
* |
|
* The @p glyphAllocator gets called with desired @p glyphCount every |
|
* time @ref glyphCount() reaches @ref glyphCapacity(). Size of |
|
* passed-in @p glyphPositions, @p glyphIds and @p glyphClusters views |
|
* matches @ref glyphCount(). The @p glyphAdvances view is a temporary |
|
* storage with contents that don't need to be preserved on |
|
* reallocation and is thus passed in empty. If the renderer wasn't |
|
* constructed with @ref RendererCoreFlag::GlyphClusters, the |
|
* @p glyphClusters is @cpp nullptr @ce to indicate it's not meant to |
|
* be allocated. The allocator is expected to replace all passed views |
|
* with new views that are larger by *at least* @p glyphCount, pointing |
|
* to a reallocated memory with contents from the original view |
|
* preserved. Initially @ref glyphCount() is @cpp 0 @ce and the views |
|
* are all passed in empty, every subsequent time the views match a |
|
* prefix of views previously returned by the allocator. To save |
|
* memory, the renderer guarantees that @p glyphIds and |
|
* @p glyphClusters are only filled once @p glyphAdvances were merged |
|
* into @p glyphPositions. In other words, the @p glyphAdvances can |
|
* alias a suffix of @p glyphIds and @p glyphClusters. |
|
* |
|
* The @p runAllocator gets called with desired @p runCount every time |
|
* @ref runCount() reaches @ref runCapacity(). Size of passed-in |
|
* @p runScales and @p runEnds views matches @ref runCount(). The |
|
* allocator is expected to replace the views with new views that are |
|
* larger by *at least* @p runCount, pointing to a reallocated memory |
|
* with contents from the original views preserved. Initially |
|
* @ref runCount() is @cpp 0 @ce and the views are passed in empty, |
|
* every subsequent time the views match a prefix of views previously |
|
* returned by the allocator. |
|
* |
|
* The renderer always requests only exactly the desired size and the |
|
* growth strategy is up to the allocators themselves --- the returned |
|
* views can be larger than requested and aren't all required to all |
|
* have the same size. The minimum of size increases across all views |
|
* is then treated as the new @ref glyphCapacity() / @ref runCapacity(). |
|
* |
|
* As a special case, when @ref clear() or @ref reset() is called, the |
|
* allocators are called with empty views and @p glyphCount / |
|
* @p runCount being @cpp 0 @ce. This is to allow the allocators to |
|
* perform any needed reset as well. |
|
* |
|
* If @p glyphAllocator or @p runAllocator is @cpp nullptr @ce, |
|
* @p glyphAllocatorState or @p runAllocatorState is ignored and |
|
* default builtin allocator get used for either. Passing |
|
* @cpp nullptr @ce for both is equivalent to calling the |
|
* @ref RendererCore(const AbstractGlyphCache&, RendererCoreFlags) |
|
* constructor. |
|
*/ |
|
explicit RendererCore(const AbstractGlyphCache& glyphCache, void(*glyphAllocator)(void* state, UnsignedInt glyphCount, Containers::StridedArrayView1D<Vector2>& glyphPositions, Containers::StridedArrayView1D<UnsignedInt>& glyphIds, Containers::StridedArrayView1D<UnsignedInt>* glyphClusters, Containers::StridedArrayView1D<Vector2>& glyphAdvances), void* glyphAllocatorState, void(*runAllocator)(void* state, UnsignedInt runCount, Containers::StridedArrayView1D<Float>& runScales, Containers::StridedArrayView1D<UnsignedInt>& runEnds), void* runAllocatorState, RendererCoreFlags flags = {}); |
|
|
|
/** |
|
* @brief Construct without creating the internal state |
|
* @m_since_latest |
|
* |
|
* The constructed instance is equivalent to moved-from state, i.e. no |
|
* APIs can be safely called on the object. Useful in cases where you |
|
* will overwrite the instance later anyway. Move another object over |
|
* it to make it useful. |
|
* |
|
* Note that this is a low-level and a potentially dangerous API, see |
|
* the documentation of @ref NoCreate for alternatives. |
|
*/ |
|
explicit RendererCore(NoCreateT) noexcept; |
|
|
|
/** @brief Copying is not allowed */ |
|
RendererCore(RendererCore&) = delete; |
|
|
|
/** |
|
* @brief Move constructor |
|
* |
|
* Performs a destructive move, i.e. the original object isn't usable |
|
* afterwards anymore. |
|
*/ |
|
RendererCore(RendererCore&&) noexcept; |
|
|
|
~RendererCore(); |
|
|
|
/** @brief Copying is not allowed */ |
|
RendererCore& operator=(RendererCore&) = delete; |
|
|
|
/** @brief Move assignment */ |
|
RendererCore& operator=(RendererCore&&) noexcept; |
|
|
|
/** @brief Glyph cache associated with the renderer */ |
|
const AbstractGlyphCache& glyphCache() const; |
|
|
|
/** @brief Flags */ |
|
RendererCoreFlags flags() const; |
|
|
|
/** |
|
* @brief Total count of rendered glyphs |
|
* |
|
* Does *not* include glyphs from the current in-progress rendering, if |
|
* any, as their contents are not finalized yet. Use |
|
* @ref renderingGlyphCount() to query the count including the |
|
* in-progress glyphs. |
|
* @see @ref isRendering(), @ref runCount() |
|
*/ |
|
UnsignedInt glyphCount() const; |
|
|
|
/** |
|
* @brief Glyph capacity |
|
* |
|
* @see @ref glyphCount(), @ref runCapacity(), @ref reserve() |
|
*/ |
|
UnsignedInt glyphCapacity() const; |
|
|
|
/** |
|
* @brief Total count of rendered runs |
|
* |
|
* Does *not* include runs from the current in-progress rendering, if |
|
* any, as their contents are not finalized yet. Use |
|
* @ref renderingRunCount() to query the count including the |
|
* in-progress runs. |
|
* @see @ref isRendering(), @ref glyphCount() |
|
*/ |
|
UnsignedInt runCount() const; |
|
|
|
/** |
|
* @brief Run capacity |
|
* |
|
* @see @ref runCount(), @ref glyphCapacity() @ref reserve() |
|
*/ |
|
UnsignedInt runCapacity() const; |
|
|
|
/** |
|
* @brief Whether text rendering is currently in progress |
|
* |
|
* Returns @cpp true @ce if there are any @ref add() calls not yet |
|
* followed by a @ref render(), @cpp false @ce otherwise. If rendering |
|
* is in progress, @ref setCursor(), @ref setAlignment() and |
|
* @ref setLayoutDirection() cannot be called. The @ref glyphCount(), |
|
* @ref runCount() and all data accessors don't include the |
|
* yet-to-be-finalized contents. |
|
*/ |
|
bool isRendering() const; |
|
|
|
/** |
|
* @brief Total count of glyphs including current in-progress rendering |
|
* |
|
* Can be used for example to query which glyphs correspond to the last |
|
* @ref add() call. If @ref isRendering() is @cpp false @ce, the |
|
* returned value is the same as @ref glyphCount(). |
|
*/ |
|
UnsignedInt renderingGlyphCount() const; |
|
|
|
/** |
|
* @brief Total count of runs including current in-progress rendering |
|
* |
|
* Can be used for example to query which runs correspond to the last |
|
* @ref add() call. If @ref isRendering() is @cpp false @ce, the |
|
* returned value is the same as @ref runCount(). |
|
*/ |
|
UnsignedInt renderingRunCount() const; |
|
|
|
/** |
|
* @brief Cursor position |
|
* |
|
* Note that this does *not* return the current position at which an |
|
* in-progress rendering is happening --- the way the glyphs get placed |
|
* before they're aligned to their final position is internal to the |
|
* implementation and querying such in-progress state would be of |
|
* little use. |
|
*/ |
|
Vector2 cursor() const; |
|
|
|
/** |
|
* @brief Set cursor position for the next rendered text |
|
* @return Reference to self (for method chaining) |
|
* |
|
* The next rendered text is placed according to specified @p cursor, |
|
* @ref alignment() and @ref lineAdvance(). Expects that rendering is |
|
* currently not in progress, meaning that the cursor can be only |
|
* specified before rendering a particular piece of text. Initial value |
|
* is @cpp {0.0f, 0.0f} @ce. |
|
* @see @ref isRendering() |
|
*/ |
|
RendererCore& setCursor(const Vector2& cursor); |
|
|
|
/** @brief Text alignment */ |
|
Alignment alignment() const; |
|
|
|
/** |
|
* @brief Set alignment for the next rendered text |
|
* @return Reference to self (for method chaining) |
|
* |
|
* The next rendered text is placed according to specified |
|
* @ref cursor(), @p alignment and @ref lineAdvance(). Expects that |
|
* rendering is currently not in progress, meaning that the alignment |
|
* can be only specified before rendering a particular piece of text. |
|
* Initial value is @ref Alignment::MiddleCenter. |
|
* @see @ref isRendering() |
|
*/ |
|
RendererCore& setAlignment(Alignment alignment); |
|
|
|
/** @brief Line advance */ |
|
Float lineAdvance() const; |
|
|
|
/** |
|
* @brief Set line advance for the next rendered text |
|
* @return Reference to self (for method chaining) |
|
* |
|
* The next rendered text is placed according to specified |
|
* @ref cursor(), @ref alignment and @p advance. The advance value is |
|
* used according to @ref layoutDirection() and in a coordinate system |
|
* matching @ref AbstractFont::ascent() and |
|
* @relativeref{AbstractFont,descent()}, so for example causes the next |
|
* line to be shifted in a negative Y direction for |
|
* @ref LayoutDirection::HorizontalTopToBottom. Expects that rendering |
|
* is currently not in progress, meaning that the line advance can be |
|
* only specified before rendering a particular piece of text. If set |
|
* to @cpp 0.0f @ce, the line advance is picked metrics of the first |
|
* font a corresponding size passed to @ref add(). |
|
* @see @ref isRendering(), @ref AbstractFont::lineHeight() |
|
*/ |
|
RendererCore& setLineAdvance(Float advance); |
|
|
|
/** @brief Layout direction */ |
|
LayoutDirection layoutDirection() const; |
|
|
|
/** |
|
* @brief Set layout direction |
|
* @return Reference to self (for method chaining) |
|
* |
|
* Expects that rendering is currently not in progress. Currently |
|
* expected to always be @ref LayoutDirection::HorizontalTopToBottom. |
|
* Initial value is @ref LayoutDirection::HorizontalTopToBottom. |
|
* @see @ref isRendering() |
|
*/ |
|
RendererCore& setLayoutDirection(LayoutDirection direction); |
|
|
|
/** |
|
* @brief Glyph positions |
|
* |
|
* The returned view has a size of @ref glyphCount(). Note that the |
|
* contents are not guaranteed to be meaningful if custom glyph |
|
* allocator is used, as the user code is free to perform subsequent |
|
* operations on those. |
|
*/ |
|
Containers::StridedArrayView1D<const Vector2> glyphPositions() const; |
|
|
|
/** |
|
* @brief Glyph IDs |
|
* |
|
* The returned view has a size of @ref glyphCount(). Note that the |
|
* contents are not guaranteed to be meaningful if custom glyph |
|
* allocator is used, as the user code is free to perform subsequent |
|
* operations on those. |
|
*/ |
|
Containers::StridedArrayView1D<const UnsignedInt> glyphIds() const; |
|
|
|
/** |
|
* @brief Glyph cluster IDs |
|
* |
|
* Expects that the renderer was constructed with |
|
* @ref RendererCoreFlag::GlyphClusters. The returned view has a size |
|
* of @ref glyphCount(). Note that the contents are not guaranteed to |
|
* be meaningful if custom glyph allocator is used, as the user code is |
|
* free to perform subsequent operations on those. |
|
*/ |
|
Containers::StridedArrayView1D<const UnsignedInt> glyphClusters() const; |
|
|
|
/** |
|
* @brief Text run scales |
|
* |
|
* The returned view has a size of @ref runCount(). Note that the |
|
* contents are not guaranteed to be meaningful if custom run allocator |
|
* is used, as the user code is free to perform subsequent operations |
|
* on those. |
|
*/ |
|
Containers::StridedArrayView1D<const Float> runScales() const; |
|
|
|
/** |
|
* @brief Text run end glyph offsets |
|
* |
|
* The returned view has a size of @ref runCount(), the last value is |
|
* equal to @ref glyphCount(), and the values index the |
|
* @ref glyphPositions(), @ref glyphIds() and @ref glyphClusters() |
|
* views. The first text run glyphs start at offset @cpp 0 @ce and end |
|
* at @cpp runEnds()[0] @ce, the second text run glyphs start at offset |
|
* @cpp runEnds()[0] @ce and end at @cpp runEnds()[1] @ce, etc. See |
|
* also the @ref glyphsForRuns() function which provides a convenient |
|
* way to get a range of glyphs corresponding to a range of runs |
|
* without having to deal with edge cases. |
|
* |
|
* Note that the contents of the returned view are not guaranteed to be |
|
* meaningful if custom run allocator is used, as the user code is free |
|
* to perform subsequent operations on those. |
|
*/ |
|
Containers::StridedArrayView1D<const UnsignedInt> runEnds() const; |
|
|
|
/** |
|
* @brief Range of glyphs corresponding to a range of runs |
|
* |
|
* With @p runRange being for example the second value returned by |
|
* @ref render(), returns a begin and end glyph offset for given run |
|
* range, which can then be used to index the @ref glyphPositions(), |
|
* @ref glyphIds() and @ref glyphClusters() views. Expects that both |
|
* the min and max @p runRange value are less than or equal to |
|
* @ref renderingRunCount(). |
|
* |
|
* Note that the returned value is not guaranteed to be meaningful if |
|
* custom run allocator is used, as the user code is free to perform |
|
* subsequent operations on the run data. |
|
* @see @ref runEnds() |
|
*/ |
|
Range1Dui glyphsForRuns(const Range1Dui& runRange) const; |
|
|
|
/** |
|
* @brief Reserve capacity for given glyph and run count |
|
* @return Reference to self (for method chaining) |
|
* |
|
* @see @ref glyphCapacity(), @ref glyphCount(), |
|
* @ref runCapacity(), @ref runCount() |
|
*/ |
|
RendererCore& reserve(UnsignedInt glyphCapacity, UnsignedInt runCapacity); |
|
|
|
/** |
|
* @brief Clear rendered glyphs and runs |
|
* @return Reference to self (for method chaining) |
|
* |
|
* The @ref glyphCount() and @ref runCount() becomes @cpp 0 @ce after |
|
* this call and any in-progress rendering is discarded, making |
|
* @ref isRendering() return @cpp false @ce. If custom glyph or run |
|
* allocators are used, they get called with empty views and zero |
|
* sizes. |
|
* |
|
* Depending on allocator used, @ref glyphCapacity() and |
|
* @ref runCapacity() may stay non-zero. The @ref cursor(), |
|
* @ref alignment(), @ref lineAdvance() and @ref layoutDirection() are |
|
* left untouched, use @ref reset() to reset those to their default |
|
* values as well. |
|
*/ |
|
RendererCore& clear(); |
|
|
|
/** |
|
* @brief Reset internal renderer state |
|
* @return Reference to self (for method chaining) |
|
* |
|
* Calls @ref clear(), and additionally @ref cursor(), |
|
* @ref alignment(), @ref lineAdvance() and @ref layoutDirection() are |
|
* reset to their default values. Apart from @ref glyphCapacity() and |
|
* @ref runCapacity(), which may stay non-zero depending on allocator |
|
* used, the instance is equivalent to a default-constructed state. |
|
*/ |
|
RendererCore& reset(); |
|
|
|
/** |
|
* @brief Add to the currently rendered text |
|
* @param shaper Shaper instance to render with |
|
* @param size Font size |
|
* @param text Text in UTF-8 |
|
* @param begin Beginning byte in the input text |
|
* @param end (One byte after) the end byte in the input text |
|
* @param features Typographic features to apply for the whole text or |
|
* its subranges |
|
* @return Reference to self (for method chaining) |
|
* |
|
* Splits @p text into individual lines and shapes each with given |
|
* @p shaper. Places and aligns the text according to @ref cursor(), |
|
* @ref alignment() and @ref layoutDirection(), continuing from the |
|
* state left after the previous @ref add(), if any. |
|
* |
|
* After calling this function, @ref isRendering() returns |
|
* @cpp true @ce, @ref renderingGlyphCount() and @ref renderingRunCount() |
|
* are updated with the count of newly added glyphs and runs, and |
|
* @ref setCursor(), @ref setAlignment() or @ref setLayoutDirection() |
|
* cannot be called anymore. Call @ref add() more times and wrap up |
|
* with @ref render() to perform the final alignment and other steps |
|
* necessary to finalize the rendering. If you only need to render the |
|
* whole text at once, you can use |
|
* @ref render(AbstractShaper&, Float, Containers::StringView, Containers::ArrayView<const FeatureRange>) |
|
* instead. |
|
* |
|
* The function assumes that the @p shaper has either appropriate |
|
* script, language and shape direction set, or has them left at |
|
* defaults in order let them be autodetected. In order to allow the |
|
* implementation to perform shaping aware of surrounding context, such |
|
* as picking correct glyphs for beginning, middle or end of a word or a |
|
* paragraph, the individual @ref add() calls should ideally be made |
|
* with the same @p text view and the slices defined by @p begin and |
|
* @p end. Use the @ref add(AbstractShaper&, Float, Containers::StringView, Containers::ArrayView<const FeatureRange>) |
|
* overload to pass a string as a whole. |
|
* |
|
* The function uses @ref AbstractShaper::shape(), |
|
* @ref renderLineGlyphPositionsInto(), @ref alignRenderedLine() and |
|
* @ref glyphQuadBounds() internally, see their documentation for more |
|
* information. |
|
*/ |
|
#ifdef DOXYGEN_GENERATING_OUTPUT |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, UnsignedInt begin, UnsignedInt end, Containers::ArrayView<const FeatureRange> features = {}); |
|
#else |
|
/* To not have to include ArrayView */ |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, UnsignedInt begin, UnsignedInt end); |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, UnsignedInt begin, UnsignedInt end, Containers::ArrayView<const FeatureRange> features); |
|
#endif |
|
|
|
/** @overload */ |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, UnsignedInt begin, UnsignedInt end, std::initializer_list<FeatureRange> features); |
|
|
|
/** |
|
* @brief Add a whole string to the currently rendered text |
|
* |
|
* Equivalent to @ref add(AbstractShaper&, Float, Containers::StringView, UnsignedInt, UnsignedInt, Containers::ArrayView<const FeatureRange>) |
|
* with @p begin set to @cpp 0 @ce and @p end to size of @p text. |
|
*/ |
|
#ifdef DOXYGEN_GENERATING_OUTPUT |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, Containers::ArrayView<const FeatureRange> features = {}); |
|
#else |
|
/* To not have to include ArrayView */ |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text); |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, Containers::ArrayView<const FeatureRange> features); |
|
#endif |
|
|
|
/** @overload */ |
|
RendererCore& add(AbstractShaper& shaper, Float size, Containers::StringView text, std::initializer_list<FeatureRange> features); |
|
|
|
/** |
|
* @brief Wrap up rendering of all text added so far |
|
* |
|
* Performs a final alignment of the text block added by preceding |
|
* @ref add() calls and wraps up the rendering. After calling this |
|
* function, @ref isRendering() returns @cpp false @ce, |
|
* @ref glyphCount() and @ref runCount() are updated with the count of |
|
* all rendered glyphs and runs, and @ref setCursor(), |
|
* @ref setAlignment() or @ref setLayoutDirection() can be called again |
|
* for the next text to be rendered. |
|
* |
|
* The function returns a bounding box and a range of runs of the |
|
* currently rendered text, the run range can then be used to index |
|
* the @ref runScales() and @ref runEnds() views. Note that it's |
|
* possible for the render to produce an empty range, such as when an |
|
* empty text was passed or when it was just newlines. You can use |
|
* @ref glyphsForRuns() to convert the returned run range to a begin |
|
* and end glyph offset, which can be then used to index the |
|
* @ref glyphPositions(), @ref glyphIds() and @ref glyphClusters() |
|
* views. |
|
* |
|
* The rendered glyph range is not touched or used by the renderer in |
|
* any way afterwards. If the renderer was created with custom |
|
* allocators, the caller can thus perform further operations on the |
|
* allocated data. |
|
* |
|
* Use @ref clear() or @ref reset() to discard all text rendered so |
|
* far. The function uses @ref alignRenderedBlock() internally, see its |
|
* documentation for more information. |
|
*/ |
|
Containers::Pair<Range2D, Range1Dui> render(); |
|
|
|
/** |
|
* @brief Render a whole text at once |
|
* |
|
* A convenience shortcut for rendering a single piece of text that's |
|
* equivalent to calling @ref add(AbstractShaper&, Float, Containers::StringView, Containers::ArrayView<const FeatureRange>) |
|
* followed by @ref render(). See their documentation for more |
|
* information. |
|
* |
|
* After calling this function, @ref isRendering() returns |
|
* @cpp false @ce. If this function is called while rendering is in |
|
* progress, the glyphs rendered so far are included in the result as |
|
* well. |
|
*/ |
|
#ifdef DOXYGEN_GENERATING_OUTPUT |
|
Containers::Pair<Range2D, Range1Dui> render(AbstractShaper& shaper, Float size, Containers::StringView text, Containers::ArrayView<const FeatureRange> features = {}); |
|
#else |
|
/* To not have to include ArrayView */ |
|
Containers::Pair<Range2D, Range1Dui> render(AbstractShaper& shaper, Float size, Containers::StringView text); |
|
Containers::Pair<Range2D, Range1Dui> render(AbstractShaper& shaper, Float size, Containers::StringView text, Containers::ArrayView<const FeatureRange> features); |
|
#endif |
|
|
|
/** @overload */ |
|
Containers::Pair<Range2D, Range1Dui> render(AbstractShaper& shaper, Float size, Containers::StringView text, std::initializer_list<FeatureRange> features); |
|
|
|
#ifdef DOXYGEN_GENERATING_OUTPUT |
|
private: |
|
#else |
|
protected: |
|
#endif |
|
struct State; |
|
struct AllocatorState; |
|
Containers::Pointer<State> _state; |
|
|
|
/* Called by reset() */ |
|
MAGNUM_TEXT_LOCAL void resetInternal(); |
|
|
|
private: |
|
/* While the allocators get just size to grow by, these functions get |
|
the total count */ |
|
MAGNUM_TEXT_LOCAL void allocateGlyphs( |
|
#ifndef CORRADE_NO_ASSERT |
|
const char* messagePrefix, |
|
#endif |
|
UnsignedInt totalGlyphCount); |
|
MAGNUM_TEXT_LOCAL void allocateRuns( |
|
#ifndef CORRADE_NO_ASSERT |
|
const char* messagePrefix, |
|
#endif |
|
UnsignedInt totalRunCount); |
|
MAGNUM_TEXT_LOCAL void alignAndFinishLine(); |
|
}; |
|
|
|
/** |
|
@brief Render glyph positions for a (part of a) single line |
|
@param[in] font Font to query metrics from |
|
@param[in] size Size to render the glyphs at |
|
@param[in] direction Layout direction. Currently expected to always be |
|
@ref LayoutDirection::HorizontalTopToBottom. |
|
@param[in] glyphOffsets Glyph offsets coming from @ref AbstractShaper |
|
instance(s) associated with @p font |
|
@param[in] glyphAdvances Glyph advances coming from @ref AbstractShaper |
|
instance(s) associated with @p font |
|
@param[in,out] cursor Initial cursor position. Is updated to a final |
|
cursor position after all glyphs are rendered. |
|
@param[out] glyphPositions Where to put output absolute glyph positions |
|
@return Rectangle spanning the rendered cursor range in one direction and font |
|
descent to ascent in the other |
|
@m_since_latest |
|
|
|
The output of this function are just glyph positions alone, which is useful for |
|
example when the actual glyph quad expansion is done by a shader or when the |
|
glyphs get subsequently rasterized some other way than applying a glyph texture |
|
to a sequence of quads. Use @ref renderGlyphQuadsInto() on the resulting |
|
@p glyphPositions array to form actual glyph quads together with texture |
|
coordinates. |
|
|
|
The @p glyphOffsets, @p glyphAdvances and @p glyphPositions views are all |
|
expected to have the same size. It's possible to use the same view for |
|
@p glyphOffsets and @p glyphPositions, which will turn the input relative glyph |
|
offsets into absolute positions. |
|
|
|
Calls to this function don't strictly need to match calls to |
|
@ref AbstractShaper::shape(). For example if multiple text runs on a single |
|
line differ just by script, language or direction but not by a font or |
|
rendering size, they can be shaped into consecutive portions of a larger |
|
@p glyphOffsets and @p glyphAdvances array and this function can be then called |
|
just once for all runs together. If the font or rendering size changes between |
|
text runs however, you have to call this function for each such run separately |
|
and each time use the updated @p cursor value as an input for the next |
|
@ref renderLineGlyphPositionsInto() call. |
|
|
|
@m_class{m-note m-warning} |
|
|
|
@par |
|
This function only works on a single line of text. When rendering a |
|
multi-line text, you have to split it by lines and then shape, render and |
|
align each individually, and adjust @p cursor for each new line as |
|
appropriate. |
|
|
|
Once the whole line is rendered, @ref Math::join() the rectangles returned from |
|
all calls to this function and pass them together with positions for the whole |
|
line to @ref alignRenderedLine(). Finally, to align a multi-line block, join |
|
rectangles returned from all @ref alignRenderedLine() calls and pass them |
|
together with positions for the whole text to @ref alignRenderedBlock(). |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D renderLineGlyphPositionsInto(const AbstractFont& font, Float size, LayoutDirection direction, const Containers::StridedArrayView1D<const Vector2>& glyphOffsets, const Containers::StridedArrayView1D<const Vector2>& glyphAdvances, Vector2& cursor, const Containers::StridedArrayView1D<Vector2>& glyphPositions); |
|
|
|
/** |
|
@brief Render glyph quads for a (part of a) single line from font-specific glyph IDs |
|
@param[in] font Font the glyphs are coming from |
|
@param[in] size Size to render the glyphs at |
|
@param[in] cache Glyph cache to query for glyph rectangles |
|
@param[in] glyphPositions Glyph positions coming from an earlier call to |
|
@ref renderLineGlyphPositionsInto() |
|
@param[in] fontGlyphIds Glyph IDs coming from @ref AbstractShaper |
|
instance(s) associated with @p font |
|
@param[out] vertexPositions Where to put output vertex positions |
|
@param[out] vertexTextureCoordinates Where to put output texture coordinates |
|
@return Rectangle spanning the rendered glyph quads |
|
@m_since_latest |
|
|
|
Produces a sequence of quad corner positions and texture coordinates in order |
|
as shown below. The @p glyphPositions and @p glyphIds views are expected to |
|
have the same size, the @p vertexPositions and @p vertexTextureCoordinates |
|
views are then expected to be four times larger than @p glyphPositions and |
|
@p glyphIds, in order to ultimately contain four corner vertices for each |
|
glyph. To optimize memory use, it's possible to alias @p glyphPositions with |
|
@cpp vertexPositions.every(4) @ce and @p glyphIds with |
|
@cpp vertexTextureCoordinates.every(4) @ce. The @p vertexTextureCoordinates are |
|
temporarily used to store resolved cache-global glyph IDs, the rendering is |
|
then performed in a way that first reads the position and ID for each glyph and |
|
only then fills in the vertex data. |
|
|
|
@verbatim |
|
2---3 |
|
| | |
|
| | |
|
| | |
|
0---1 |
|
@endverbatim |
|
|
|
If the text doesn't need to be aligned based on the actual glyph bounds (i.e., |
|
the desired @ref Alignment isn't `*GlyphBounds`), it's possible to call this |
|
function even on a multi-line text run provided that @ref alignRenderedLine() |
|
was called on the @p glyphPositions before to align lines relatively to each |
|
other. Otherwise this function should be called on each line individually and |
|
then the @p vertexPositions passed further to @ref alignRenderedLine(). |
|
|
|
Expects that @p font is contained in @p cache. Glyph IDs not found in the cache |
|
are replaced with the cache-global invalid glyph. If the @p cache is only 2D, |
|
you can use the @ref renderGlyphQuadsInto(const AbstractFont&, Float, const AbstractGlyphCache&, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector2>&) |
|
overload to get just 2D texture coordinates out. Use the |
|
@ref renderGlyphQuadsInto(const AbstractGlyphCache&, Float, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector2>&) |
|
overload if you already have cache-global glyph IDs. Use |
|
@ref renderGlyphQuadIndicesInto() to populate the corresponding index array. |
|
@see @ref glyphQuadBounds() |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D renderGlyphQuadsInto(const AbstractFont& font, Float size, const AbstractGlyphCache& cache, const Containers::StridedArrayView1D<const Vector2>& glyphPositions, const Containers::StridedArrayView1D<const UnsignedInt>& fontGlyphIds, const Containers::StridedArrayView1D<Vector2>& vertexPositions, const Containers::StridedArrayView1D<Vector3>& vertexTextureCoordinates); |
|
|
|
/** |
|
@brief Render glyph quads for a (part of a) single line from font-specific glyph IDs and a 2D glyph cache |
|
@m_since_latest |
|
|
|
Compared to @ref renderGlyphQuadsInto(const AbstractFont&, Float, const AbstractGlyphCache&, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector3>&) |
|
outputs just 2D texture coordinates. Expects that @ref AbstractGlyphCache::size() |
|
depth is @cpp 1 @ce. |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D renderGlyphQuadsInto(const AbstractFont& font, Float size, const AbstractGlyphCache& cache, const Containers::StridedArrayView1D<const Vector2>& glyphPositions, const Containers::StridedArrayView1D<const UnsignedInt>& fontGlyphIds, const Containers::StridedArrayView1D<Vector2>& vertexPositions, const Containers::StridedArrayView1D<Vector2>& vertexTextureCoordinates); |
|
|
|
/** |
|
@brief Render glyph quads for a (part of a) single line from cache-global glyph IDs |
|
@param[in] cache Glyph cache to query for glyph rectangles |
|
@param[in] scale Size to render the glyphs at divided by size of |
|
the input font |
|
@param[in] glyphPositions Glyph positions coming from an earlier call to |
|
@ref renderLineGlyphPositionsInto() |
|
@param[in] glyphIds Cache-global glyph IDs |
|
@param[out] vertexPositions Where to put output vertex positions |
|
@param[out] vertexTextureCoordinates Where to put output texture coordinates |
|
@return Rectangle spanning the rendered glyph quads |
|
@m_since_latest |
|
|
|
Compared to @ref renderGlyphQuadsInto(const AbstractFont&, Float, const AbstractGlyphCache&, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector3>&) |
|
this function operates takes cache-global glyph IDs as an input, i.e. no |
|
mapping from font-specific glyph IDs to cache-global IDs happens in this case. |
|
As with the above overload, to optimize memory use, it's possible to alias |
|
@p glyphPositions and @p glyphIds with @cpp vertexPositions.every(4) @ce and |
|
@cpp vertexTextureCoordinates.every(4) @ce. |
|
@see @ref AbstractGlyphCache::glyphIdsInto(), @ref glyphQuadBounds() |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D renderGlyphQuadsInto(const AbstractGlyphCache& cache, Float scale, const Containers::StridedArrayView1D<const Vector2>& glyphPositions, const Containers::StridedArrayView1D<const UnsignedInt>& glyphIds, const Containers::StridedArrayView1D<Vector2>& vertexPositions, const Containers::StridedArrayView1D<Vector3>& vertexTextureCoordinates); |
|
|
|
/** |
|
@brief Render glyph quads for a (part of a) single line from cache-global glyph IDs and a 2D glyph cache |
|
@m_since_latest |
|
|
|
Compared to @ref renderGlyphQuadsInto(const AbstractGlyphCache&, Float, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector3>&) |
|
outputs just 2D texture coordinates. Expects that @ref AbstractGlyphCache::size() |
|
depth is @cpp 1 @ce. |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D renderGlyphQuadsInto(const AbstractGlyphCache& cache, Float scale, const Containers::StridedArrayView1D<const Vector2>& glyphPositions, const Containers::StridedArrayView1D<const UnsignedInt>& glyphIds, const Containers::StridedArrayView1D<Vector2>& vertexPositions, const Containers::StridedArrayView1D<Vector2>& vertexTextureCoordinates); |
|
|
|
/** |
|
@brief Calculate glyph quad bounds from cache-global glyph IDs |
|
@param[in] cache Glyph cache to query for glyph rectangles |
|
@param[in] scale Size to render the glyphs at divided by size of |
|
the input font |
|
@param[in] glyphPositions Glyph positions coming from an earlier call to |
|
@ref renderLineGlyphPositionsInto() |
|
@param[in] glyphIds Cache-global glyph IDs |
|
@return Rectangle spanning the glyph quads |
|
@m_since_latest |
|
|
|
Returns the same rectangle as @ref renderGlyphQuadsInto(const AbstractGlyphCache&, Float, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector3>&) |
|
but without actually generating the glyph quads. Use the returned value for |
|
@ref alignRenderedLine() with a `*GlyphBounds` @ref Alignment value. |
|
|
|
Note that, unlike with @ref renderGlyphQuadsInto(const AbstractFont&, Float, const AbstractGlyphCache&, const Containers::StridedArrayView1D<const Vector2>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<Vector2>&, const Containers::StridedArrayView1D<Vector3>&), |
|
this function doesn't have an overload taking font-local glyph IDs, as it |
|
doesn't have any scratch space to store them. Use |
|
@ref AbstractGlyphCache::glyphIdsInto() instead to convert them to cache-global |
|
and then call this function with the result. |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D glyphQuadBounds(const AbstractGlyphCache& cache, Float scale, const Containers::StridedArrayView1D<const Vector2>& glyphPositions, const Containers::StridedArrayView1D<const UnsignedInt>& glyphIds); |
|
|
|
/** |
|
@brief Align a rendered line |
|
@param[in] lineRectangle Rectangle spanning the whole line |
|
@param[in] direction Layout direction. Currently expected to always be |
|
@ref LayoutDirection::HorizontalTopToBottom. |
|
@param[in] alignment Desired alignment. Only the part in direction of |
|
the line is used. |
|
@param[in,out] positions Positions of glyphs or glyph quad vertices on the |
|
whole line to be aligned |
|
@return The @p lineRectangle, translated in the direction of the line based on |
|
the alignment. |
|
@m_since_latest |
|
|
|
Expects that @p alignment isn't `*Start` or `*End`, those values have to be |
|
resolved to `*Left` or `*Right` based on desired or detected |
|
@ref ShapeDirection using @ref alignmentForDirection() before being passed to |
|
this function. |
|
|
|
If @p alignment isn't `*GlyphBounds`, this function should get glyph |
|
@p positions for the whole line coming from @ref renderLineGlyphPositionsInto() |
|
and @p lineRectangle being all rectangles returned by that function combined |
|
together with @ref Math::join(). |
|
|
|
If @p alignment is `*GlyphBounds`, this function should get glyph @p positions |
|
for the whole line coming from @ref renderLineGlyphPositionsInto() and a |
|
@p lineRectangle being generated with @ref glyphQuadBounds() from those |
|
positions. Alternatively, it should get vertex @p positions for a whole line |
|
coming from @ref renderGlyphQuadsInto() and @p lineRectangle being all |
|
rectangles returned by that function combined together with |
|
@ref Math::join(). |
|
|
|
The @p positions are translated in one axis based on the @p inputRectangle and |
|
the part of @p alignment matching line direction in @p direction. Values of the |
|
@p positions themselves aren't considered when calculating the alignment. To |
|
align a multi-line block, join rectangles returned from all calls to this |
|
function and pass them together with positions for the whole block to |
|
@ref alignRenderedBlock(). |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D alignRenderedLine(const Range2D& lineRectangle, LayoutDirection direction, Alignment alignment, const Containers::StridedArrayView1D<Vector2>& positions); |
|
|
|
/** |
|
@brief Align a rendered block |
|
@param[in] blockRectangle Rectangle spanning all lines in the block |
|
@param[in] direction Layout direction. Currently expected to always be |
|
@ref LayoutDirection::HorizontalTopToBottom. |
|
@param[in] alignment Desired alignment. Only the part in direction of |
|
the line is used. |
|
@param[in,out] positions Positions of glyphs or glyph quad vertices on the |
|
whole line to be aligned |
|
@return The @p blockRectangle, translated in the direction of the layout |
|
advance based on the alignment. |
|
@m_since_latest |
|
|
|
Expects that @p alignment isn't `*Start` or `*End`, those values have to be |
|
resolved to `*Left` or `*Right` based on desired or detected |
|
@ref ShapeDirection using @ref alignmentForDirection() before being passed to |
|
this function. |
|
|
|
This function should get glyph or vertex @p positions for all lines as aligned |
|
by calls to @ref alignRenderedLine(), and @p blockRectangle being all line |
|
rectangles returned by that function combined together with @ref Math::join(). |
|
|
|
The @p positions are translated in one axis based on the @p inputRectangle and |
|
the part of @p alignment matching layout advance in @p direction. Values of the |
|
@p positions themselves aren't considered when calculating the translation. |
|
*/ |
|
MAGNUM_TEXT_EXPORT Range2D alignRenderedBlock(const Range2D& blockRectangle, LayoutDirection direction, Alignment alignment, const Containers::StridedArrayView1D<Vector2>& positions); |
|
|
|
/** |
|
@brief Render 32-bit glyph quad indices |
|
@param[in] glyphOffset Offset of the first glyph to generate indices for |
|
@param[out] indices Where to put the generated indices |
|
@m_since_latest |
|
|
|
Produces a sequence of quad indices in order as shown below, with the index |
|
values being shifted by @cpp glyphOffset*4 @ce. Expects that the @p indices |
|
view size is divisible by @cpp 6 @ce and the value range fits into the output |
|
type. |
|
|
|
@verbatim |
|
2---3 2 3---5 |
|
| | |\ \ | |
|
| | | \ \ | |
|
| | | \ \| |
|
0---1 0---1 4 |
|
@endverbatim |
|
*/ |
|
MAGNUM_TEXT_EXPORT void renderGlyphQuadIndicesInto(UnsignedInt glyphOffset, const Containers::StridedArrayView1D<UnsignedInt>& indices); |
|
|
|
/** |
|
@brief Render 16-bit glyph quad indices |
|
@m_since_latest |
|
|
|
See @ref renderGlyphQuadIndicesInto(UnsignedInt, const Containers::StridedArrayView1D<UnsignedInt>&) |
|
for more information. |
|
*/ |
|
MAGNUM_TEXT_EXPORT void renderGlyphQuadIndicesInto(UnsignedInt glyphOffset, const Containers::StridedArrayView1D<UnsignedShort>& indices); |
|
|
|
/** |
|
@brief Render 8-bit glyph quad indices |
|
@m_since_latest |
|
|
|
See @ref renderGlyphQuadIndicesInto(UnsignedInt, const Containers::StridedArrayView1D<UnsignedInt>&) |
|
for more information. |
|
*/ |
|
MAGNUM_TEXT_EXPORT void renderGlyphQuadIndicesInto(UnsignedInt glyphOffset, const Containers::StridedArrayView1D<UnsignedByte>& indices); |
|
|
|
/** |
|
@brief Find a glyph range corresponding to given byte range in the input text |
|
@m_since_latest |
|
|
|
Assuming @p clusters is a view containing cluster IDs returned from |
|
@ref AbstractShaper::glyphClustersInto() and @p begin and @p end are byte |
|
positions in the text passed to @ref AbstractShaper::shape() for which the |
|
cluster IDs were retrieved, returns a range in the glyph array that contains |
|
given range. Assumes that @p clusters are either monotonically non-decreasing |
|
or non-increasing. |
|
|
|
If @p clusters are empty or @p end is less or equal to all @p clusters, returns |
|
@cpp {0, 0} @ce. If @p begin is greater than all @p clusters are, both return |
|
values are set to @p clusters size. In both cases the empty returned range |
|
means there are no glyphs corresponding to given byte. Otherwise, if the input |
|
range is non-empty, the returned range is always at least one glyph. The |
|
returned range always points to cluster boundaries, even if the input is inside |
|
a multi-byte character or ligature or inside a multi-glyph cluster. |
|
|
|
If @p begin is greater than @p end, the first value of the output is also |
|
greater than the second. Otherwise, the first value of the output is always |
|
less than or equal to the second. |
|
|
|
At the moment, the lookup is done with an @f$ \mathcal{O}(n) @f$ complexity, |
|
with @f$ n @f$ being size of the @p clusters view. |
|
|
|
Mapping in the other direction, from glyphs to input bytes, is simply |
|
@cpp clusters[i] @ce. See @ref AbstractShaper::glyphClustersInto() for more |
|
information about how the cluster IDs may look like depending on the input and |
|
shaper features used. |
|
*/ |
|
MAGNUM_TEXT_EXPORT Containers::Pair<UnsignedInt, UnsignedInt> glyphRangeForBytes(const Containers::StridedArrayView1D<const UnsignedInt>& clusters, UnsignedInt begin, UnsignedInt end); |
|
|
|
#ifdef MAGNUM_TARGET_GL |
|
/** |
|
@brief Base for OpenGL text renderers |
|
|
|
Not meant to be used directly, see the @ref BasicRenderer class for more |
|
information. |
|
|
|
@note This class is available only if Magnum is compiled with |
|
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
|
for more information. |
|
|
|
@see @ref Renderer2D, @ref Renderer3D |
|
*/ |
|
class MAGNUM_TEXT_EXPORT AbstractRenderer { |
|
public: |
|
/** |
|
* @brief Render text |
|
* @param font Font |
|
* @param cache Glyph cache |
|
* @param size Font size in points |
|
* @param text Text to render |
|
* @param alignment Text alignment |
|
* |
|
* Returns a tuple with vertex positions, texture coordinates, indices |
|
* and rectangle spanning the rendered text. Expects that @p font is |
|
* present in @p cache and that @p cache isn't an array. |
|
*/ |
|
static std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>, Range2D> render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, Alignment alignment = Alignment::LineLeft); |
|
|
|
/** |
|
* @brief Capacity for rendered glyphs |
|
* |
|
* @see @ref reserve() |
|
*/ |
|
UnsignedInt capacity() const { return _capacity; } |
|
|
|
/** |
|
* @brief Font size in points |
|
* @m_since_latest |
|
*/ |
|
Float fontSize() const { return _fontSize; } |
|
|
|
/** @brief Rectangle spanning the rendered text */ |
|
Range2D rectangle() const { return _rectangle; } |
|
|
|
/** @brief Vertex buffer */ |
|
GL::Buffer& vertexBuffer() { return _vertexBuffer; } |
|
|
|
/** @brief Index buffer */ |
|
GL::Buffer& indexBuffer() { return _indexBuffer; } |
|
|
|
/** @brief Mesh */ |
|
GL::Mesh& mesh() { return _mesh; } |
|
|
|
/** |
|
* @brief Reserve capacity for rendered glyphs |
|
* |
|
* Reallocates memory in buffers to hold @p glyphCount glyphs and |
|
* prefills index buffer. Consider using appropriate @p vertexBufferUsage |
|
* if the text will be changed frequently. Index buffer is changed |
|
* only by calling this function, thus @p indexBufferUsage generally |
|
* doesn't need to be so dynamic if the capacity won't be changed much. |
|
* |
|
* Initially zero capacity is reserved. |
|
* @see @ref capacity() |
|
*/ |
|
void reserve(UnsignedInt glyphCount, GL::BufferUsage vertexBufferUsage, GL::BufferUsage indexBufferUsage); |
|
|
|
/** |
|
* @brief Render text |
|
* |
|
* Renders the text to vertex buffer, reusing index buffer already |
|
* filled with @ref reserve(). Rectangle spanning the rendered text is |
|
* available through @ref rectangle(). |
|
* |
|
* Initially no text is rendered. |
|
* @attention The capacity must be large enough to contain all glyphs, |
|
* see @ref reserve() for more information. |
|
*/ |
|
void render(const std::string& text); |
|
|
|
#ifndef DOXYGEN_GENERATING_OUTPUT |
|
protected: |
|
#else |
|
private: |
|
#endif |
|
explicit MAGNUM_TEXT_LOCAL AbstractRenderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment); |
|
|
|
~AbstractRenderer(); |
|
|
|
GL::Mesh _mesh; |
|
GL::Buffer _vertexBuffer, _indexBuffer; |
|
#ifdef CORRADE_TARGET_EMSCRIPTEN |
|
Containers::Array<UnsignedByte> _vertexBufferData, _indexBufferData; |
|
#endif |
|
|
|
private: |
|
AbstractFont& font; |
|
const AbstractGlyphCache& cache; |
|
Float _fontSize; |
|
Alignment _alignment; |
|
UnsignedInt _capacity; |
|
Range2D _rectangle; |
|
|
|
#if defined(MAGNUM_TARGET_GLES2) && !defined(CORRADE_TARGET_EMSCRIPTEN) |
|
typedef void*(*BufferMapImplementation)(GL::Buffer&, GLsizeiptr); |
|
static MAGNUM_TEXT_LOCAL void* bufferMapImplementationFull(GL::Buffer& buffer, GLsizeiptr length); |
|
static MAGNUM_TEXT_LOCAL void* bufferMapImplementationRange(GL::Buffer& buffer, GLsizeiptr length); |
|
static BufferMapImplementation bufferMapImplementation; |
|
#else |
|
#ifndef CORRADE_TARGET_EMSCRIPTEN |
|
static |
|
#else |
|
MAGNUM_TEXT_LOCAL |
|
#endif |
|
void* bufferMapImplementation(GL::Buffer& buffer, GLsizeiptr length); |
|
#endif |
|
|
|
#if defined(MAGNUM_TARGET_GLES2) && !defined(CORRADE_TARGET_EMSCRIPTEN) |
|
typedef void(*BufferUnmapImplementation)(GL::Buffer&); |
|
static MAGNUM_TEXT_LOCAL void bufferUnmapImplementationDefault(GL::Buffer& buffer); |
|
static MAGNUM_TEXT_LOCAL BufferUnmapImplementation bufferUnmapImplementation; |
|
#else |
|
#ifndef CORRADE_TARGET_EMSCRIPTEN |
|
static |
|
#else |
|
MAGNUM_TEXT_LOCAL |
|
#endif |
|
void bufferUnmapImplementation(GL::Buffer& buffer); |
|
#endif |
|
}; |
|
|
|
/** |
|
@brief OpenGL text renderer |
|
|
|
Lays out the text into mesh using given font. Use of ligatures, kerning etc. |
|
depends on features supported by particular font and its layouter. |
|
|
|
@section Text-BasicRenderer-usage Usage |
|
|
|
Immutable text (e.g. menu items, credits) can be simply rendered using static |
|
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 Text-gl.cpp BasicRenderer-usage1 |
|
|
|
See @ref render(AbstractFont&, const AbstractGlyphCache&, Float, const std::string&, Alignment) |
|
and @ref render(AbstractFont&, const AbstractGlyphCache&, Float, const std::string&, GL::Buffer&, GL::Buffer&, GL::BufferUsage, Alignment) |
|
for more information. |
|
|
|
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 Text-gl.cpp BasicRenderer-usage2 |
|
|
|
@subsection Text-BasicRenderer-usage-font-size Font size |
|
|
|
As mentioned in @ref Text-AbstractFont-font-size "AbstractFont class documentation", |
|
the size at which the font is loaded is decoupled from the size at which a |
|
concrete text is rendered. In particular, with a concrete projection matrix, |
|
the size you pass to either @ref render() or to the @ref BasicRenderer() |
|
constructor will always result in the same size of the rendered text, |
|
independently of the size the font was loaded in. Size of the loaded font is |
|
the size at which the glyphs get prerendered into the glyph cache, affecting |
|
visual quality. |
|
|
|
When rendering the text, there are two common approaches --- either setting up |
|
the size to match a global user interface scale, or having the text size |
|
proportional to the window size. The first approach results in e.g. a 12 pt |
|
font matching a 12 pt font in other applications, and is what's shown in the |
|
above snippets. The most straightforward way to achieve that is to set up the |
|
projection matrix size to match actual window pixels, such as @ref Platform::Sdl2Application::windowSize() "Platform::*Application::windowSize()". |
|
If using the regular @ref GlyphCacheGL, for best visual quality it should be |
|
created with the @ref AbstractFont loaded at the same size as the text to be |
|
rendered, although often a double supersampling achieves a crisper result. |
|
I.e., loading the font with 24 pt, but rendering with 12 pt. See below for |
|
@ref Text-BasicRenderer-usage-font-size-dpi "additional considerations for proper DPI awareness". |
|
|
|
The second approach, with text size being relative to the window size, is for |
|
cases where the text is meant to match surrounding art, such as in a game menu. |
|
In this case the projection size is usually something arbitrary that doesn't |
|
match window pixels, and the text point size then has to be relative to that. |
|
For this use case a @ref DistanceFieldGlyphCacheGL is the better match, as it |
|
can provide text at different sizes with minimal quality loss. See its |
|
documentation for details about picking the right font size and other |
|
parameters for best results. |
|
|
|
@subsection Text-BasicRenderer-usage-font-size-dpi DPI awareness |
|
|
|
To achieve crisp rendering and/or text size matching other applications on |
|
HiDPI displays, additional steps need to be taken. There are two separate |
|
concepts for DPI-aware rendering: |
|
|
|
- Interface size --- size at which the interface elements are positioned on |
|
the screen. Often, for simplicity, the interface is using some "virtual |
|
units", so a 12 pt font is still a 12 pt font independently of how the |
|
interface is scaled compared to actual display properties (for example by |
|
setting a global 150% scale in the desktop environment, or by zooming a |
|
browser window). The size used by the @ref BasicRenderer "Renderer*D" |
|
should match these virtual units. |
|
- Framebuffer size --- how many pixels is actually there. If a 192 DPI |
|
display has a 200% interface scale, a 12 pt font would be 32 pixels. But if |
|
it only has a 150% scale, all interface elements will be smaller, and a 12 |
|
pt font would be only 24 pixels. The size used by the @ref AbstractFont and |
|
@ref GlyphCacheGL should be chosen with respect to the actual physical |
|
pixels. |
|
|
|
When using for example @ref Platform::Sdl2Application or other `*Application` |
|
implementations, you usually have three values at your disposal --- |
|
@ref Platform::Sdl2Application::windowSize() "windowSize()", |
|
@ref Platform::Sdl2Application::framebufferSize() "framebufferSize()" and |
|
@ref Platform::Sdl2Application::dpiScaling() "dpiScaling()". Their relation is |
|
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 Text-gl.cpp BasicRenderer-dpi-interface-size |
|
|
|
And a multiplier for the @ref AbstractFont and @ref GlyphCacheGL font size like |
|
this. The @ref BasicRenderer "Renderer*D" keeps using the size without this |
|
multiplier. |
|
|
|
@snippet Text-gl.cpp BasicRenderer-dpi-size-multiplier |
|
|
|
@section Text-BasicRenderer-required-opengl-functionality Required OpenGL functionality |
|
|
|
Mutable text rendering requires @gl_extension{ARB,map_buffer_range} on desktop |
|
OpenGL (also part of OpenGL ES 3.0). If @gl_extension{EXT,map_buffer_range} is not |
|
available in ES 2.0, at least @gl_extension{OES,mapbuffer} must be supported for |
|
asynchronous buffer updates. There is no similar extension in WebGL, thus plain |
|
(and slow) buffer updates are used there. |
|
|
|
@note This class is available only if Magnum is compiled with |
|
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
|
for more information. |
|
|
|
@see @ref Renderer2D, @ref Renderer3D, @ref AbstractFont, |
|
@ref Shaders::VectorGL, @ref Shaders::DistanceFieldVectorGL |
|
*/ |
|
template<UnsignedInt dimensions> class MAGNUM_TEXT_EXPORT BasicRenderer: public AbstractRenderer { |
|
public: |
|
/** |
|
* @brief Render text |
|
* @param font Font |
|
* @param cache Glyph cache |
|
* @param size Font size |
|
* @param text Text to render |
|
* @param vertexBuffer Buffer where to store vertices |
|
* @param indexBuffer Buffer where to store indices |
|
* @param usage Usage of vertex and index buffer |
|
* @param alignment Text alignment |
|
* |
|
* Returns a mesh prepared for use with @ref Shaders::VectorGL or |
|
* @ref Shaders::DistanceFieldVectorGL and a rectangle spanning the |
|
* rendered text. Expects that @p font is present in @p cache and that |
|
* @p cache isn't an array. |
|
*/ |
|
static std::tuple<GL::Mesh, Range2D> render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment = Alignment::LineLeft); |
|
|
|
/** |
|
* @brief Constructor |
|
* @param font Font |
|
* @param cache Glyph cache |
|
* @param size Font size |
|
* @param alignment Text alignment |
|
*/ |
|
explicit BasicRenderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft); |
|
BasicRenderer(AbstractFont&, AbstractGlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */ |
|
|
|
#ifndef DOXYGEN_GENERATING_OUTPUT |
|
using AbstractRenderer::render; |
|
#endif |
|
}; |
|
|
|
/** |
|
@brief Two-dimensional text renderer |
|
|
|
@note This class is available only if Magnum is compiled with |
|
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
|
for more information. |
|
*/ |
|
typedef BasicRenderer<2> Renderer2D; |
|
|
|
/** |
|
@brief Three-dimensional text renderer |
|
|
|
@note This class is available only if Magnum is compiled with |
|
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
|
for more information. |
|
*/ |
|
typedef BasicRenderer<3> Renderer3D; |
|
#endif |
|
|
|
}} |
|
|
|
#endif
|
|
|