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> textPropertiesOverride_;
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 textPropertiesOverride 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>& textPropertiesOverride = std::nullopt
93 ) :
94 textRenderPrototype_(std::move(renderPrototype)),
95 textMesh_(std::move(textMesh)),
96 textPropertiesOverride_(textPropertiesOverride)
97 {
98
99 if (!textRenderPrototype_) {
100 throw std::invalid_argument("Unexpected nullptr for TextRenderPrototype");
101 }
102
103 }
104
105 /**
106 * @brief Returns the local-space axis-aligned bounding box.
107 *
108 * The AABB is computed based on the text layout and font metrics.
109 *
110 * @return Reference to the local-space AABB.
111 */
112 [[nodiscard]] const helios::math::aabbf& localAABB() const noexcept override {
113 return textMesh_->localAABB(textRenderPrototype_->fontResourceProvider());
114 }
115
116 /**
117 * @brief Updates the text string.
118 *
119 * @param text The new text to render.
120 */
121 void setText(std::string text) noexcept {
122 textMesh_->setText(std::move(text));
123 }
124
125 /**
126 * @brief Returns the current text string.
127 *
128 * @return View of the text string.
129 */
130 [[nodiscard]] std::string_view text() const noexcept {
131 return textMesh_->text();
132 }
133
134 /**
135 * @brief Returns the text render prototype.
136 *
137 * **PERF-NOTE:** This method returns a copy of the `shared_ptr`, triggering atomic
138 * reference counting. For read-only access in rendering loops, consider using
139 * `textRenderPrototype_.get()` directly or adding a `const TextRenderPrototype&`
140 * overload.
141 *
142 * @return Shared pointer to the prototype.
143 */
144 [[nodiscard]] std::shared_ptr<const helios::rendering::text::TextRenderPrototype> shareTextRenderPrototype() const noexcept {
145 return textRenderPrototype_;
146 }
147
148 /**
149 * @brief Returns a const ref to the TextRenderPrototype used by this TextRenderable.
150 *
151 * This method provides direct access to the prototype without incrementing the
152 * reference count, making it suitable for use in hot rendering paths.
153 *
154 * @return A const ref to the TextRenderPrototype.
155 */
156 [[nodiscard]] const helios::rendering::text::TextRenderPrototype& textRenderPrototype() const noexcept {
157 return *textRenderPrototype_;
158 }
159
160 /**
161 * @brief Returns the text mesh.
162 *
163 * The text mesh contains the text content, font, and cached layout data.
164 *
165 * @return Reference to the text mesh.
166 */
167 [[nodiscard]] const helios::rendering::text::TextMesh& textMesh() const noexcept {
168 return *textMesh_;
169 }
170
171 /**
172 * @brief Writes uniform values to the given map.
173 *
174 * Applies the prototype's text properties first, then any instance-specific
175 * overrides. Used by the render pipeline to configure the text shader.
176 *
177 * @param uniformValueMap The map to write uniform values to.
178 */
179 void writeUniformValues(helios::rendering::shader::UniformValueMap& uniformValueMap) const noexcept override {
180 textRenderPrototype_->textProperties().writeUniformValues(uniformValueMap);
181
182 if (textPropertiesOverride_) {
183 textPropertiesOverride_->writeUniformValues(uniformValueMap);
184 }
185 }
186
187 /**
188 * @brief Emits a text render command to the render queue.
189 *
190 * Creates a `TextRenderCommand` with the current text, prototype, and uniform
191 * values, then adds it to the render queue for processing by the `TextRenderer`.
192 *
193 * @param renderQueue The render queue to emit the command to.
194 * @param objectUniformValues Object-specific uniform values (e.g., model matrix).
195 * @param materialUniformValues Material uniform values (will be merged with text properties).
196 */
197 void emit(
198 helios::rendering::RenderQueue& renderQueue,
199 helios::rendering::shader::UniformValueMap& objectUniformValues,
200 helios::rendering::shader::UniformValueMap& materialUniformValues) const override {
201
202
203 writeUniformValues(materialUniformValues);
204
205 renderQueue.add(helios::rendering::text::TextRenderCommand(
206 textMesh_.get(),
207 textRenderPrototype_.get(),
208 objectUniformValues,
209 materialUniformValues
210 ));
211 };
212
213
214 };
215
216}
217

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.