Shared class
#include <Magnum/Ui/TextLayer.h>
Shared state for the text layer.
Contains a set of fonts and a glyph cache used by all of them. In order to use the layer it's expected that setGlyphCache() was called and at least one font was added with addFont(). In order to update or draw the layer it's expected that setStyle() was called.
Pre-filling the glyph cache with appropriate glyphs for a particular font is the user responsibility, the implementation currently won't perform that on its own, neither it does any on-demand cache filling.
Base classes
- class Magnum::Ui::AbstractVisualLayer::Shared
- Base shared state for visual data layers.
Derived classes
- class Shared
- Shared state for the OpenGL implementation of the text layer.
Public types
- class Configuration
- Configuration of a base layer shared state.
Public functions
- auto styleUniformCount() const -> UnsignedInt
- Style uniform count.
- auto editingStyleCount() const -> UnsignedInt
- Editing style count.
- auto editingStyleUniformCount() const -> UnsignedInt
- Editing style uniform count.
- auto hasEditingStyles() const -> bool
- Whether the layer has any editing styles.
- auto hasGlyphCache() const -> bool
- Whether a glyph cache has been set.
-
auto glyphCache() -> Text::
AbstractGlyphCache& - Glyph cache instance.
-
auto glyphCache() const -> const Text::
AbstractGlyphCache& -
auto fontCount() const -> std::
size_t - Count of added fonts.
- auto isHandleValid(FontHandle handle) const -> bool
- Whether a font handle is valid.
-
auto addFont(Text::
AbstractFont& font, Float size) -> FontHandle - Add a font.
-
auto addFont(Containers::
Pointer<Text:: AbstractFont>&& font, Float size) -> FontHandle - Add a font and take over its ownership.
- auto addInstancelessFont(UnsignedInt glyphCacheFontId, Float scale) -> FontHandle
- Add an instance-less font.
- auto glyphCacheFontId(FontHandle handle) const -> UnsignedInt
- ID of a font in a glyph cache.
- auto hasFontInstance(FontHandle handle) const -> bool
- Whether a font has an instance.
-
auto font(FontHandle handle) -> Text::
AbstractFont& - Font instance.
-
auto font(FontHandle handle) const -> const Text::
AbstractFont& -
auto setStyle(const TextLayerCommonStyleUniform& commonUniform,
Containers::
ArrayView<const TextLayerStyleUniform> uniforms, const Containers:: StridedArrayView1D<const FontHandle>& fonts, const Containers:: StridedArrayView1D<const Text:: Alignment>& alignments, Containers:: ArrayView<const TextFeatureValue> features, const Containers:: StridedArrayView1D<const UnsignedInt>& featureOffsets, const Containers:: StridedArrayView1D<const UnsignedInt>& featureCounts, const Containers:: StridedArrayView1D<const Int>& cursorStyles, const Containers:: StridedArrayView1D<const Int>& selectionStyles, const Containers:: StridedArrayView1D<const Vector4>& paddings) -> Shared& - Set style data with implicit mapping between styles and uniforms.
-
auto setStyle(const TextLayerCommonStyleUniform& commonUniform,
std::
initializer_list<TextLayerStyleUniform> uniforms, std:: initializer_list<FontHandle> fonts, std:: initializer_list<Text:: Alignment> alignments, std:: initializer_list<TextFeatureValue> features, std:: initializer_list<UnsignedInt> featureOffsets, std:: initializer_list<UnsignedInt> featureCounts, std:: initializer_list<Int> cursorStyles, std:: initializer_list<Int> selectionStyles, std:: initializer_list<Vector4> paddings) -> Shared& -
auto setStyle(const TextLayerCommonStyleUniform& commonUniform,
Containers::
ArrayView<const TextLayerStyleUniform> uniforms, const Containers:: StridedArrayView1D<const UnsignedInt>& styleToUniform, const Containers:: StridedArrayView1D<const FontHandle>& styleFonts, const Containers:: StridedArrayView1D<const Text:: Alignment>& styleAlignments, Containers:: ArrayView<const TextFeatureValue> styleFeatures, const Containers:: StridedArrayView1D<const UnsignedInt>& styleFeatureOffsets, const Containers:: StridedArrayView1D<const UnsignedInt>& styleFeatureCounts, const Containers:: StridedArrayView1D<const Int>& styleCursorStyles, const Containers:: StridedArrayView1D<const Int>& styleSelectionStyles, const Containers:: StridedArrayView1D<const Vector4>& stylePaddings) -> Shared& - Set style data.
-
auto setStyle(const TextLayerCommonStyleUniform& commonUniform,
std::
initializer_list<TextLayerStyleUniform> uniforms, std:: initializer_list<UnsignedInt> styleToUniform, std:: initializer_list<FontHandle> styleFonts, std:: initializer_list<Text:: Alignment> styleAlignments, std:: initializer_list<TextFeatureValue> styleFeatures, std:: initializer_list<UnsignedInt> styleFeatureOffsets, std:: initializer_list<UnsignedInt> styleFeatureCounts, std:: initializer_list<Int> styleCursorStyles, std:: initializer_list<Int> styleSelectionStyles, std:: initializer_list<Vector4> stylePaddings) -> Shared& -
auto setEditingStyle(const TextLayerCommonEditingStyleUniform& commonUniform,
Containers::
ArrayView<const TextLayerEditingStyleUniform> uniforms, const Containers:: StridedArrayView1D<const Int>& textUniforms, const Containers:: StridedArrayView1D<const Vector4>& paddings) -> Shared& - Set editing style data with implicit mapping between styles and uniforms.
-
auto setEditingStyle(const TextLayerCommonEditingStyleUniform& commonUniform,
std::
initializer_list<TextLayerEditingStyleUniform> uniforms, std:: initializer_list<Int> textUniforms, std:: initializer_list<Vector4> paddings) -> Shared& -
auto setEditingStyle(const TextLayerCommonEditingStyleUniform& commonUniform,
Containers::
ArrayView<const TextLayerEditingStyleUniform> uniforms, const Containers:: StridedArrayView1D<const UnsignedInt>& styleToUniform, const Containers:: StridedArrayView1D<const Int>& styleTextUniforms, const Containers:: StridedArrayView1D<const Vector4>& stylePaddings) -> Shared& - Set editing style data.
-
auto setEditingStyle(const TextLayerCommonEditingStyleUniform& commonUniform,
std::
initializer_list<TextLayerEditingStyleUniform> uniforms, std:: initializer_list<UnsignedInt> styleToUniform, std:: initializer_list<Int> styleTextUniforms, std:: initializer_list<Vector4> stylePaddings) -> Shared&
Protected functions
-
auto setGlyphCache(Text::
AbstractGlyphCache& cache) -> Shared& - Set a glyph cache instance.
Function documentation
UnsignedInt Magnum::
Style uniform count.
Size of the style uniform buffer excluding dynamic styles. May or may not be the same as styleCount(). For dynamic styles, the style uniform count is the same as dynamicStyleCount().
UnsignedInt Magnum::
Editing style count.
Count of editing styles used by all layers referencing this Shared instance. If dynamic styles include editing styles, IDs greater than editingStyleCount() are then dynamic editing styles, with their count being twice of dynamicStyleCount().
UnsignedInt Magnum::
Editing style uniform count.
Size of the editing style uniform buffer excluding dynamic styles. May or may not be the same as styleCount(). For dynamic styles, if they include editing styles, the style uniform count is twice dynamicStyleCount(), as each dynamic style can have at most two associated editing styles — one for the cursor and one for the selection.
bool Magnum::
Whether the layer has any editing styles.
Returns true if either editingStyleCount() is non-zero or dynamicStyleCount() is non-zero and editing styles were explicitly enabled with Configuration::
bool Magnum::
Whether a glyph cache has been set.
Text::
Glyph cache instance.
Expects that a glyph cache was set with setGlyphCache().
const Text::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
std::
Count of added fonts.
Can be at most 32768.
bool Magnum::
Whether a font handle is valid.
A handle is valid if it has been returned from addFont() before. Note that the implementation has no way to distinguish between handles returned from different TextLayer::false.
FontHandle Magnum::
Add a font.
| Parameters | |
|---|---|
| font | Font instance |
| size | Size at which to render the font |
| Returns | New font handle |
Expects that glyphCache() is set and contains font. Doesn't perform any operation with the glyph cache, pre-filling is left to the caller. The returned handle can be subsequently assigned to a particular style via setStyle(), or passed to TextProperties::
It's the caller responsibility to ensure font stays in scope for as long as the shared state is used. Use the addFont(Containers::
FontHandle Magnum::
Add a font and take over its ownership.
| Parameters | |
|---|---|
| font | Font instance |
| size | Size at which to render the font |
| Returns | New font handle |
Like addFont(Text::
FontHandle Magnum::
Add an instance-less font.
| Parameters | |
|---|---|
| glyphCacheFontId | ID of the font in the glyph cache |
| scale | Scale to apply to glyph rectangles coming from the glyph cache |
| Returns | New font handle |
Makes it possible to render arbitrary custom glyphs added to the glyph cache, such as icons or other image data.
Expects that glyphCache() is set, glyphCacheFontId is less than Text::nullptr for glyphCacheFontId. Doesn't perform any operation with the glyph cache, the caller is expected to populate the cache with desired data. The resulting handle can be subsequently assigned to a particular style via setStyle(), or passed to TextProperties::
UnsignedInt Magnum::
ID of a font in a glyph cache.
Returns ID under which given font glyphs are stored in the glyphCache(). For fonts with an instance is equivalent to the ID returned from Text::handle is valid.
bool Magnum::
Whether a font has an instance.
Returns true if the font was created with addFont(), false if with addInstancelessFont(). Expects that handle is valid.
Text::
Font instance.
Expects that handle is valid and has a font instance, i.e. was created with addFont() and not addInstancelessFont().
const Text::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Shared& Magnum::
Set style data with implicit mapping between styles and uniforms.
| Parameters | |
|---|---|
| commonUniform | Common style uniform data |
| uniforms | Style uniforms |
| fonts | Font handles corresponding to style uniforms |
| alignments | Text alignment corresponding to style uniforms |
| features | Font feature data for all styles |
| featureOffsets | Offsets into features corresponding to style uniforms |
| featureCounts | Counts into features corresponding to style uniforms |
| cursorStyles | Cursor style IDs corresponding to style uniforms |
| selectionStyles | Selection style IDs corresponding to style uniforms |
| paddings | Padding inside the node in order left, top, right, bottom corresponding to style uniforms |
| Returns | Reference to self (for method chaining) |
The uniforms view is expected to have the same size as styleUniformCount(), the fonts and alignments views the same size as styleCount(). All font handles are expected to be either FontHandle::alignments values are expected to not be *GlyphBounds as the implementation can only align based on font metrics and cursor position, not actual glyph bounds. See TextProperties::
The featureOffsets and featureCounts views are expected to both either have a size of styleCount(), or both be empty. If non-empty, they contain offsets and counts into the features view for each style, with the ranges expected to fit into the view size. The ranges are allowed to overlap, i.e. multiple styles can share the same default feature set. If empty, the features view is expected to be empty as well and no default font features are specified for any styles. Features coming from TextProperties are appended after these, making it possible to override them.
The cursorStyles and selectionStyles views are expected to either have the same size as styleCount() or be empty. If non-empty, they're expected to either contain non-negative indices less than editingStyleCount() or -1 denoting that given style doesn't have the cursor or selection visible. If empty, no styles have cursor or selection visible.
The paddings view is expected to either have the same size as styleCount() or be empty, in which case all paddings are implicitly zero.
Can only be called if styleUniformCount() and styleCount() were set to the same value in Configuration passed to the constructor, otherwise you have to additionally provide a mapping from styles to uniforms using setStyle(const TextLayerCommonStyleUniform&, Containers::
Calling this function causes LayerState::
Shared& Magnum::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Shared& Magnum::
Set style data.
| Parameters | |
|---|---|
| commonUniform | Common style uniform data |
| uniforms | Style uniforms |
| styleToUniform | Style to style uniform mapping |
| styleFonts | Per-style font handles |
| styleAlignments | Per-style text alignment |
| styleFeatures | Font feature data for all styles |
| styleFeatureOffsets | Per-style offsets into styleFeatures |
| styleFeatureCounts | Per-style counts into styleFeatures |
| styleCursorStyles | Per-style cursor style IDs |
| styleSelectionStyles | Per-style selection style IDs |
| stylePaddings | Per-style padding inside the node in order left, top, right, bottom |
| Returns | Reference to self (for method chaining) |
The uniforms view is expected to have the same size as styleUniformCount(), the styleToUniform, styleFonts and styleAlignments views the same size as styleCount(). All uniform indices are expected to be less than styleUniformCount(), all font handles are expected to be either FontHandle::styleAlignments values are expected to not be *GlyphBounds as the implementation can only align based on font metrics and cursor position, not actual glyph bounds. See TextProperties::
The styleFeatureOffsets and styleFeatureCounts views are expected to both either have a size of styleCount(), or both be empty. If non-empty, they contain offsets and counts into the styleFeatures view for each style, with the ranges expected to fit into the view size. The ranges are allowed to overlap, i.e. multiple styles can share the same default feature set. If empty, the styleFeatures view is expected to be empty as well and no default font features are specified for any styles. Features coming from TextProperties are appended after these, making it possible to override them.
The styleCursorStyles and styleSelectionStyles views are expected to either have the same size as styleCount() or be empty. If non-empty, they're expected to either contain non-negative indices less than editingStyleCount() or -1 denoting that given style doesn't have the cursor or selection visible. If empty, no styles have cursor or selection visible.
The stylePaddings view is expected to either have the same size as styleCount() or be empty, in which case all paddings are implicitly zero.
Value of styleToUniform[i] should give back an index into the uniforms array for style i. If styleUniformCount() and styleCount() is the same and the mapping is implicit, you can use the setStyle(const TextLayerCommonStyleUniform&, Containers::
Calling this function causes LayerState::
Shared& Magnum::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Shared& Magnum::
Set editing style data with implicit mapping between styles and uniforms.
| Parameters | |
|---|---|
| commonUniform | Common style uniform data |
| uniforms | Style uniforms |
| textUniforms | Base style uniform IDs to use for selected portions of the text. Not used if given style is for a cursor. |
| paddings | Paddings outside the cursor or selection rectangle in order begin, top, end, bottom corresponding to style uniforms |
| Returns | Reference to self (for method chaining) |
The uniforms view is expected to have the same size as editingStyleUniformCount(), the paddings views the same size as editingStyleCount().
The textUniforms are expected to either have the same size as editingStyleCount() or be empty. The indices point into the uniform array supplied by setStyle(), in which case selected portions of the text are switched to be drawn with given uniform ID instead, or are -1, in which case the original style uniform ID is used unchanged. If the view is empty, it's the same as all values being -1.
The order in which paddings get used depends on direction of given text — for Text::
Can only be called if editingStyleUniformCount() and editingStyleCount() were set to the same value in Configuration::
Note that while for selection styles the paddings are merely a way to visually fine-tune the appearance, for cursor styles the padding has to be non-zero horizontally to actually be visible at all. This is also why, unlike setStyle(), the paddings can't be left empty.
Shared& Magnum::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Shared& Magnum::
Set editing style data.
| Parameters | |
|---|---|
| commonUniform | Common style uniform data |
| uniforms | Style uniforms |
| styleToUniform | Style to style uniform mapping |
| styleTextUniforms | Base style uniform IDs to use for selected portions of the text. Not used if given style is for a cursor. |
| stylePaddings | Per-style margins outside the cursor or selection rectangle in order left, top, right, bottom |
| Returns | Reference to self (for method chaining) |
The uniforms view is expected to have the same size as editingStyleUniformCount(), the styleToUniform and stylePaddings views the same size as editingStyleCount(). All styleToUniform indices are expected to be less than editingStyleUniformCount().
Value of styleToUniform[i] should give back an index into the uniforms array for style i. If editingStyleUniformCount() and editingStyleCount() is the same and the mapping is implicit, you can use the setEditingStyle(const TextLayerCommonEditingStyleUniform&, Containers::
The styleTextUniforms are expected to either have the same size as editingStyleCount() or be empty. If non-empty, they're expected to either be non-negative indices less than styleUniformCount(), pointing into the uniform array supplied by setStyle() in which case selected portions of the text are switched to be drawn with given uniform ID instead, or be -1, in which case the original style uniform ID is used unchanged. If the view is empty, it's the same as all values being -1.
Note that while for selection styles the paddings are merely a way to visually fine-tune the appearance, for cursor styles the paddings have to be non-zero horizontally to actually be visible at all. This is also why, unlike setStyle(), the stylePaddings can't be left empty.
Shared& Magnum::
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Shared& Magnum::
Set a glyph cache instance.
| Returns | Reference to self (for method chaining) |
|---|
Has to be called before any addFont(), is expected to be called exactly once. You'll most probably want to set it through the public TextLayerGL::