Skip to main content

TextRenderable.ixx File

High-level text component for scene integration. More...

Included Headers​

#include <memory> #include <optional> #include <stdexcept> #include <utility> #include <helios.rendering.text.TextMesh> #include <helios.rendering.text.TextShaderPropertiesOverride> #include <helios.rendering.text.TextRenderPrototype> #include <helios.rendering.RenderQueue> #include <helios.rendering.shader.UniformValueMap> #include <helios.rendering.text.TextRenderCommand> #include <helios.rendering.Renderable>

Namespaces Index​

namespacehelios
namespacerendering

Graphics rendering infrastructure. More...

namespacetext

Text rendering abstractions and data types. More...

Classes Index​

classTextRenderable

High-level text component that can be attached to game objects. More...

Description​

High-level text component for scene integration.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file TextRenderable.ixx
3 * @brief High-level text component for scene integration.
4 */
5module;
6
7#include <memory>
8#include <optional>
9#include <stdexcept>
10#include <utility>
11
12
13export module helios.rendering.text.TextRenderable;
14
15import helios.rendering.Renderable;
16import helios.rendering.RenderQueue;
17
18import helios.rendering.text.TextRenderCommand;
19
20import helios.rendering.text.TextRenderPrototype;
21import helios.rendering.text.TextShaderPropertiesOverride;
22import helios.rendering.text.TextMesh;
23
24import helios.rendering.shader.UniformValueMap;
25
26
27export namespace helios::rendering::text {
28
29 /**
30 * @brief High-level text component that can be attached to game objects.
31 *
32 * `TextRenderable` represents a piece of text that can be rendered in the scene.
33 * It combines a `TextRenderPrototype` (shader and font configuration) with
34 * instance-specific data like the text string and positioning.
35 *
36 * ## Responsibilities
37 *
38 * - Hold the text string to be rendered.
39 * - Reference a shared `TextRenderPrototype` for shader and font settings.
40 * - Store instance-specific `TextMesh` (position, scale, font).
41 * - Allow property overrides via `TextShaderPropertiesOverride`.
42 *
43 * ## Usage
44 *
45 * ```cpp
46 * auto prototype = std::make_shared<TextRenderPrototype>(shader, textProps);
47 * TextMesh drawProps{FontId{1}, {100.0f, 200.0f}, 1.0f};
48 *
49 * TextRenderable text("Score: 0", prototype, drawProps);
50 * text.setText("Score: 100"); // Update dynamically
51 * ```
52 *
53 * @see TextRenderPrototype
54 * @see TextRenderCommand
55 * @see TextMesh
56 */
57 class TextRenderable final : public helios::rendering::Renderable {
58
59 protected:
60
61 /**
62 * @brief Shared prototype containing shader and text properties.
63 */
64 std::shared_ptr<const helios::rendering::text::TextRenderPrototype> textRenderPrototype_ = nullptr;
65
66
67 /**
68 * @brief Optional overrides for text shader properties.
69 */
70 std::optional<helios::rendering::text::TextShaderPropertiesOverride> textShaderPropertiesOverride_;
71
72 /**
73 * @brief Positioning and styling data (font, position, scale).
74 */
75 std::unique_ptr<helios::rendering::text::TextMesh> textMesh_;
76
77
78 public:
79
80 /**
81 * @brief Constructs a TextRenderable with the given text mesh and configuration.
82 *
83 * @param textMesh Unique pointer to the text mesh containing text content, font, and layout data.
84 * @param renderPrototype Shared prototype with shader and font configuration.
85 * @param textShaderPropertiesOverride Optional overrides for shader properties (e.g., text color).
86 *
87 * @throws std::invalid_argument If `renderPrototype` is null.
88 */
89 explicit TextRenderable(
90 std::unique_ptr<helios::rendering::text::TextMesh> textMesh,
91 std::shared_ptr<const helios::rendering::text::TextRenderPrototype> renderPrototype,
92 const std::optional<helios::rendering::text::TextShaderPropertiesOverride>& textShaderPropertiesOverride = std::nullopt
93 ) :
94 textRenderPrototype_(std::move(renderPrototype)),
95 textMesh_(std::move(textMesh)),
96 textShaderPropertiesOverride_(textShaderPropertiesOverride)
97 {
98
99 if (!textRenderPrototype_) {
100 throw std::invalid_argument("Unexpected nullptr for TextRenderPrototype");
101 }
102
103 }
104
105 /**
106 * @brief Returns the optional shader properties override.
107 *
108 * @return Optional containing the override if set.
109 */
110 [[nodiscard]] std::optional<helios::rendering::text::TextShaderPropertiesOverride> textShaderPropertiesOverride() noexcept {
111 return textShaderPropertiesOverride_;
112 }
113
114 /**
115 * @brief Sets the shader properties override.
116 *
117 * @param textShaderPropertiesOverride The override to apply.
118 */
119 void setTextShaderPropertiesOverride(helios::rendering::text::TextShaderPropertiesOverride textShaderPropertiesOverride) noexcept {
120 textShaderPropertiesOverride_ = textShaderPropertiesOverride;
121 }
122
123 /**
124 * @brief Returns the local-space axis-aligned bounding box.
125 *
126 * The AABB is computed based on the text layout and font metrics.
127 *
128 * @return Reference to the local-space AABB.
129 */
130 [[nodiscard]] const helios::math::aabbf& localAABB() const noexcept override {
131 return textMesh_->localAABB(textRenderPrototype_->fontResourceProvider());
132 }
133
134 /**
135 * @brief Updates the text string.
136 *
137 * @param text The new text to render.
138 */
139 void setText(std::string text) noexcept {
140 textMesh_->setText(std::move(text));
141 }
142
143 /**
144 * @brief Returns the current text string.
145 *
146 * @return View of the text string.
147 */
148 [[nodiscard]] std::string_view text() const noexcept {
149 return textMesh_->text();
150 }
151
152 /**
153 * @brief Returns the text render prototype.
154 *
155 * **PERF-NOTE:** This method returns a copy of the `shared_ptr`, triggering atomic
156 * reference counting. For read-only access in rendering loops, consider using
157 * `textRenderPrototype_.get()` directly or adding a `const TextRenderPrototype&`
158 * overload.
159 *
160 * @return Shared pointer to the prototype.
161 */
162 [[nodiscard]] std::shared_ptr<const helios::rendering::text::TextRenderPrototype> shareTextRenderPrototype() const noexcept {
163 return textRenderPrototype_;
164 }
165
166 /**
167 * @brief Returns a const ref to the TextRenderPrototype used by this TextRenderable.
168 *
169 * This method provides direct access to the prototype without incrementing the
170 * reference count, making it suitable for use in hot rendering paths.
171 *
172 * @return A const ref to the TextRenderPrototype.
173 */
174 [[nodiscard]] const helios::rendering::text::TextRenderPrototype& textRenderPrototype() const noexcept {
175 return *textRenderPrototype_;
176 }
177
178 /**
179 * @brief Returns the text mesh.
180 *
181 * The text mesh contains the text content, font, and cached layout data.
182 *
183 * @return Reference to the text mesh.
184 */
185 [[nodiscard]] const helios::rendering::text::TextMesh& textMesh() const noexcept {
186 return *textMesh_;
187 }
188
189 /**
190 * @brief Returns a mutable reference to the text mesh.
191 *
192 * @return Mutable reference to the text mesh.
193 */
194 [[nodiscard]] helios::rendering::text::TextMesh& textMesh() noexcept {
195 return *textMesh_;
196 }
197
198 /**
199 * @brief Writes uniform values to the given map.
200 *
201 * Applies the prototype's text properties first, then any instance-specific
202 * overrides. Used by the render pipeline to configure the text shader.
203 *
204 * @param uniformValueMap The map to write uniform values to.
205 */
206 void writeUniformValues(helios::rendering::shader::UniformValueMap& uniformValueMap) const noexcept override {
207 textRenderPrototype_->textProperties().writeUniformValues(uniformValueMap);
208
209 if (textShaderPropertiesOverride_) {
210 textShaderPropertiesOverride_->writeUniformValues(uniformValueMap);
211 }
212 }
213
214 /**
215 * @brief Emits a text render command to the render queue.
216 *
217 * Creates a `TextRenderCommand` with the current text, prototype, and uniform
218 * values, then adds it to the render queue for processing by the `TextRenderer`.
219 *
220 * @param renderQueue The render queue to emit the command to.
221 * @param objectUniformValues Object-specific uniform values (e.g., model matrix).
222 * @param materialUniformValues Material uniform values (will be merged with text properties).
223 */
224 void emit(
225 helios::rendering::RenderQueue& renderQueue,
226 helios::rendering::shader::UniformValueMap& objectUniformValues,
227 helios::rendering::shader::UniformValueMap& materialUniformValues) const override {
228
229
230 writeUniformValues(materialUniformValues);
231
232 renderQueue.add(helios::rendering::text::TextRenderCommand(
233 textMesh_.get(),
234 textRenderPrototype_.get(),
235 objectUniformValues,
236 materialUniformValues
237 ));
238 };
239
240
241 };
242
243}
244

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.