Skip to main content

TextRenderPrototype.ixx File

Shared, immutable configuration for text rendering. More...

Included Headers​

#include <memory> #include <stdexcept> #include <string> #include <helios.engine.core.data.FontId> #include <helios.rendering.shader.Shader> #include <helios.rendering.text.FontResourceProvider> #include <helios.rendering.text.TextShaderProperties>

Namespaces Index​

namespacehelios
namespacerendering

Graphics rendering infrastructure. More...

namespacetext

Text rendering abstractions and data types. More...

Classes Index​

classTextRenderPrototype

Immutable, shared prototype for text rendering configuration. More...

Description​

Shared, immutable configuration for text rendering.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file TextRenderPrototype.ixx
3 * @brief Shared, immutable configuration for text rendering.
4 */
5module;
6
7#include <memory>
8#include <stdexcept>
9#include <string>
10
11export module helios.rendering.text.TextRenderPrototype;
12
13
14import helios.rendering.text.TextShaderProperties;
15
16import helios.rendering.text.FontResourceProvider;
17import helios.rendering.shader.Shader;
18import helios.engine.core.data.FontId;
19
20export namespace helios::rendering::text {
21
22 /**
23 * @brief Immutable, shared prototype for text rendering configuration.
24 *
25 * `TextRenderPrototype` holds the shader and text properties that are shared
26 * across multiple `TextRenderable` instances. This reduces memory usage and
27 * allows efficient batching of text with the same configuration.
28 *
29 * ## Design
30 *
31 * - **Immutable:** Configuration cannot be changed after construction.
32 * - **Shared:** Multiple `TextRenderable` objects can reference the same prototype.
33 * - **Reduced Duplication:** Avoids redundant storage of shader and property data.
34 *
35 * ## Usage
36 *
37 * ```cpp
38 * auto shader = std::make_shared<OpenGLShader>(...);
39 * auto textProps = std::make_shared<TextShaderProperties>(textColor);
40 *
41 * // Get font provider from rendering device
42 * auto& fontProvider = device.fontResourceProvider();
43 * fontProvider.loadFont(FontId{"roboto"}, "fonts/Roboto.ttf");
44 *
45 * auto prototype = std::make_shared<TextRenderPrototype>(shader, textProps, &fontProvider);
46 *
47 * // Share prototype across multiple renderables
48 * TextRenderable title(std::make_unique<TextMesh>("Title", fontId), prototype);
49 * TextRenderable score(std::make_unique<TextMesh>("Score: 0", fontId), prototype);
50 * ```
51 *
52 * ## Performance Considerations
53 *
54 * **PERF-NOTE: shared_ptr for shader and properties**
55 *
56 * The `shader_` and `textProperties_` members use `std::shared_ptr`. Since prototypes
57 * are typically long-lived and shared across many renderables, the ref-counting
58 * overhead is amortized. However:
59 *
60 * - Avoid copying `TextRenderPrototype` shared_ptrs in tight loops. The prototype
61 * getters return references, which is the correct pattern.
62 * - The `fontResourceProvider_` uses a raw pointer intentionally to avoid circular
63 * references and unnecessary ref-counting—this is the preferred pattern for
64 * service-like dependencies with well-defined lifetimes.
65 *
66 * @see TextRenderable
67 * @see TextShaderProperties
68 * @see FontResourceProvider
69 * @see Shader
70 */
71 class TextRenderPrototype final {
72
73 private:
74
75 /**
76 * @brief The shader used for rendering text.
77 */
78 std::shared_ptr <const helios::rendering::shader::Shader> shader_;
79
80 /**
81 * @brief Text-specific shader properties (e.g., color).
82 */
83 std::shared_ptr <const helios::rendering::text::TextShaderProperties> textProperties_;
84
85 /**
86 * @brief Provider for loading fonts and retrieving glyph data.
87 *
88 * Non-owning raw pointer. The font resource provider must remain valid
89 * for the lifetime of this prototype.
90 */
91 helios::rendering::text::FontResourceProvider* fontResourceProvider_;
92
93 public:
94
95 /**
96 * @brief Constructs a text render prototype.
97 *
98 * @param shader The shader to use for text rendering.
99 * @param textProperties Text-specific shader properties.
100 * @param fontResourceProvider Raw pointer to the font resource provider
101 * (must remain valid for the lifetime of this prototype).
102 *
103 * @throws std::invalid_argument If `shader`, `textProperties`, or `fontResourceProvider` is null.
104 */
105 explicit TextRenderPrototype(
106 std::shared_ptr<const helios::rendering::shader::Shader> shader,
107 std::shared_ptr<const helios::rendering::text::TextShaderProperties> textProperties,
108 helios::rendering::text::FontResourceProvider* fontResourceProvider
109
110 ) :
111 shader_(std::move(shader)),
112 textProperties_(std::move(textProperties)),
113 fontResourceProvider_(fontResourceProvider) {
114
115 if (!shader_) {
116 throw std::invalid_argument("RenderPrototype received null shader");
117 }
118
119 if (!fontResourceProvider_) {
120 throw std::invalid_argument("RenderPrototype received null fontResourceProvider");
121 }
122
123 if (!textProperties_) {
124 throw std::invalid_argument("RenderPrototype received null textProperties");
125 }
126
127 }
128
129 /**
130 * @brief Returns the shader.
131 *
132 * @return Reference to the shader used for text rendering.
133 */
134 [[nodiscard]] const helios::rendering::shader::Shader& shader() const noexcept {
135 return *shader_;
136 }
137
138 /**
139 * @brief Returns the font resource provider.
140 *
141 * The font resource provider is used to load fonts and retrieve glyph data
142 * for text layout and rendering.
143 *
144 * @return Reference to the font resource provider.
145 */
146 [[nodiscard]] helios::rendering::text::FontResourceProvider& fontResourceProvider() const noexcept {
147 return *fontResourceProvider_;
148 }
149
150 /**
151 * @brief Returns the text shader properties.
152 *
153 * @return Reference to the text-specific properties.
154 */
155 [[nodiscard]] const helios::rendering::text::TextShaderProperties& textProperties() const noexcept {
156 return *textProperties_;
157 }
158
159 };
160
161
162}
163

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.