Skip to main content

TextRenderableConfig.ixx File

Fluent configuration for text renderable GameObjects. More...

Included Headers​

#include <memory> #include <string> #include <cassert> #include <helios.engine.builder.gameObject.builders.configs.SceneNodeConfig> #include <helios.engine.modules.ui> #include <helios.scene.SceneNode> #include <helios.math.types> #include <helios.engine.modules.rendering> #include <helios.ext.opengl> #include <helios.core.types> #include <helios.engine.modules.ui.widgets.types.FontId> #include <helios.rendering> #include <helios.engine.ecs.GameObject>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespacebuilder

Fluent builder pattern for constructing GameObjects. More...

namespacegameObject

Factory and prototype classes for GameObject construction. More...

namespacebuilders

Domain-specific builders for configuring different aspects of GameObjects. More...

namespaceconfigs

Fine-grained configuration classes for component setup. More...

Classes Index​

classTextRenderableConfig

Fluent configuration for text renderable GameObjects. More...

Description​

Fluent configuration for text renderable GameObjects.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file TextRenderableConfig.ixx
3 * @brief Fluent configuration for text renderable GameObjects.
4 */
5module;
6
7#include <memory>
8#include <string>
9#include <cassert>
10
11export module helios.engine.builder.gameObject.builders.configs.TextRenderableConfig;
12
13import helios.engine.ecs.GameObject;
14import helios.rendering;
15import helios.engine.modules.ui.widgets.types.FontId;
16import helios.core.types;
17import helios.ext.opengl;
18import helios.engine.modules.rendering;
19import helios.math.types;
20import helios.scene.SceneNode;
21import helios.engine.modules.ui;
22
23
24
25import helios.engine.builder.gameObject.builders.configs.SceneNodeConfig;
26
27
28export namespace helios::engine::builder::gameObject::builders::configs {
29
30 /**
31 * @brief Fluent configuration for text renderable GameObjects.
32 *
33 * Provides a builder-style interface for configuring text rendering
34 * properties including font, color, shader, and optional UI text binding.
35 */
36 class TextRenderableConfig {
37
38 /**
39 * @brief The GameObject being configured.
40 */
41 helios::engine::ecs::GameObject gameObject_;
42
43 /**
44 * @brief Pointer to the font resource provider.
45 */
46 helios::rendering::text::FontResourceProvider* fontResourceProvider_;
47
48 /**
49 * @brief The shader used for text rendering.
50 */
51 std::shared_ptr<helios::ext::opengl::rendering::shader::LegacyOpenGLShader> shader_;
52
53 /**
54 * @brief The text color.
55 */
56 helios::math::vec4f color_;
57
58 /**
59 * @brief The text content to display.
60 */
61 std::string text_;
62
63 /**
64 * @brief The font scale factor.
65 */
66 float fontScale_;
67
68 /**
69 * @brief Format string for number display (std::vformat syntax).
70 */
71 std::string numberFormat_ = "{:0.f}";
72
73 /**
74 * @brief Whether this text should be configured as UI text.
75 */
76 bool isUiText_ = false;
77
78 /**
79 * @brief The font identifier.
80 */
81 helios::engine::modules::ui::widgets::types::FontId fontId_{helios::core::types::no_init};
82
83 /**
84 * @brief Format string for timestamp display (std::vformat syntax).
85 */
86 std::string timestampFormat_;
87
88 /**
89 * @brief Whether a TimeFormatterComponent should be attached.
90 */
91 bool usesTimeFormatter_;
92
93 /**
94 * @brief Whether a NumberFormatterComponent should be attached.
95 */
96 bool usesNumberFormatter_;
97
98 /**
99 * @brief Whether the timer should display remaining instead of elapsed time.
100 */
101 bool displayRemaining_;
102
103 /**
104 * @brief Label displayed instead of "00:00" when remaining time reaches zero.
105 */
106 std::string elapsedLabel_;
107
108 /**
109 * @brief True if an elapsed label has been configured.
110 */
111 bool showElapsedLabel_ = false;
112
113 /**
114 * @brief True if the output should be empty when remaining time reaches zero.
115 */
116 bool hideWhenZero_ = false;
117
118
119
120 public:
121
122 /**
123 * @brief Constructs a TextRenderableConfig for the given GameObject.
124 *
125 * @param gameObject The GameObject to configure.
126 */
127 explicit TextRenderableConfig(
128 helios::engine::ecs::GameObject gameObject
129 ) : gameObject_(gameObject) {}
130
131 /**
132 * @brief Sets the shader for text rendering.
133 *
134 * @param shader The shader to use.
135 *
136 * @return Reference to this config for method chaining.
137 */
138 TextRenderableConfig& shader(const std::shared_ptr<helios::ext::opengl::rendering::shader::LegacyOpenGLShader>& shader) {
139 shader_ = std::move(shader);
140
141 return *this;
142 }
143
144 /**
145 * @brief Sets the text color.
146 *
147 * @param color The RGBA color.
148 *
149 * @return Reference to this config for method chaining.
150 */
151 TextRenderableConfig& color(const helios::math::vec4f color) {
152 color_ = color;
153
154 return *this;
155 }
156
157 /**
158 * @brief Builds the text renderable and attaches to a parent GameObject.
159 *
160 * @param parent The parent GameObject to attach to.
161 *
162 * @return A SceneNodeConfig for further configuration.
163 */
164 SceneNodeConfig attachTo(helios::engine::ecs::GameObject parent) {
165
166 build();
167
168 SceneNodeConfig scn{gameObject_};
169
170 scn.parent(parent);
171
172 return scn;
173 }
174
175 /**
176 * @brief Builds the text renderable and attaches to a parent SceneNode.
177 *
178 * @param parent The parent SceneNode to attach to.
179 *
180 * @return A SceneNodeConfig for further configuration.
181 */
182 SceneNodeConfig attachTo(helios::scene::SceneNode* parent) {
183
184 build();
185
186 SceneNodeConfig scn{gameObject_};
187
188 scn.parent(parent);
189
190 return scn;
191 }
192
193 /**
194 * @brief Sets the font resource provider.
195 *
196 * @param provider The font resource provider.
197 *
198 * @return Reference to this config for method chaining.
199 */
200 TextRenderableConfig& fontResourceProvider(helios::rendering::text::FontResourceProvider& provider) {
201 fontResourceProvider_ = &provider;
202 return *this;
203 }
204
205 /**
206 * @brief Configures this text as a UI text component.
207 *
208 * @return Reference to this config for method chaining.
209 */
210 TextRenderableConfig& asUiText() {
211 isUiText_ = true;
212 return *this;
213 }
214
215 /**
216 * @brief Attaches a NumberFormatterComponent with the given format.
217 *
218 * Implicitly enables UI text mode.
219 *
220 * @param numberFormat A std::vformat-compatible string. Defaults to "{:.0f}".
221 *
222 * @return Reference to this config for method chaining.
223 */
224 TextRenderableConfig& formattedAsNumber(std::string numberFormat = "{:.0f}") {
225 numberFormat_ = std::move(numberFormat);
226 usesNumberFormatter_ = true;
227 return *this;
228 }
229
230 /**
231 * @brief Attaches a TimeFormatterComponent with the given format.
232 *
233 * Implicitly enables UI text mode.
234 *
235 * @param timestampFormat A std::vformat-compatible string expecting minutes and seconds.
236 *
237 * @return Reference to this config for method chaining.
238 */
239 TextRenderableConfig& formattedAsTimestamp(std::string timestampFormat) {
240 timestampFormat_ = std::move(timestampFormat);
241 usesTimeFormatter_ = true;
242 return *this;
243 }
244
245 /**
246 * @brief Sets the label shown instead of "00:00" when remaining time reaches zero.
247 *
248 * Only effective in Remaining mode. Once the remaining time drops to
249 * one second or below, format() returns this label instead of the
250 * numeric output.
251 *
252 * @param label The label string to display (e.g. "TIME UP").
253 *
254 * @return Reference to this config for method chaining.
255 */
256 TextRenderableConfig& useElapsedLabel(std::string label) {
257 elapsedLabel_ = std::move(label);
258 showElapsedLabel_ = true;
259 return *this;
260 }
261
262 /**
263 * @brief Hides the time output when remaining time reaches zero.
264 *
265 * Only effective in Remaining mode. When enabled, format() returns
266 * an empty string once the remaining time is exhausted.
267 *
268 * @return Reference to this config for method chaining.
269 */
270 TextRenderableConfig& hideWhenZero() {
271 hideWhenZero_ = true;
272 return *this;
273 }
274
275 /**
276 * @brief Switches the time formatter to display remaining time.
277 *
278 * Only effective when formattedAsTimestamp() has been called.
279 *
280 * @return Reference to this config for method chaining.
281 */
282 TextRenderableConfig& displayRemaining() {
283 displayRemaining_ = true;
284 return *this;
285 }
286
287
288 /**
289 * @brief Sets the text content.
290 *
291 * @param text The text to display.
292 *
293 * @return Reference to this config for method chaining.
294 */
295 TextRenderableConfig& text(std::string text) {
296 text_ = std::move(text);
297 return *this;
298 }
299
300 /**
301 * @brief Sets the font identifier.
302 *
303 * @param fontId The font ID to use.
304 *
305 * @return Reference to this config for method chaining.
306 */
307 TextRenderableConfig& fontId(helios::engine::modules::ui::widgets::types::FontId fontId) {
308 fontId_ = fontId;
309 return *this;
310 }
311
312 /**
313 * @brief Sets the font scale factor.
314 *
315 * @param fontScale The scale factor.
316 *
317 * @return Reference to this config for method chaining.
318 */
319 TextRenderableConfig& fontScale(const float fontScale) {
320 fontScale_ = fontScale;
321 return *this;
322 }
323
324 /**
325 * @brief Builds the text renderable and adds components to the GameObject.
326 *
327 * Creates a TextRenderable with the configured properties and adds
328 * RenderableComponent and ModelAabbComponent. If configured as UI text,
329 * also adds UiTextComponent.
330 *
331 * @return Reference to this config for method chaining.
332 */
333 TextRenderableConfig& build() {
334
335 assert(shader_ && "Unexpected missing shape and/or shader");
336
337 auto shaderProperties = std::make_shared<helios::rendering::text::TextShaderProperties>(color_);
338
339 const auto textPrototype = std::make_shared<helios::rendering::text::TextRenderPrototype>(
340 shader_, shaderProperties, fontResourceProvider_
341 );
342
343 auto renderable = std::make_shared<helios::rendering::text::TextRenderable>(
344 std::make_unique<helios::rendering::text::TextMesh>(std::move(text_), fontScale_, fontId_),
345 textPrototype
346 );
347
348 gameObject_.add<helios::engine::modules::rendering::renderable::components::RenderableComponent>(renderable);
349
350 auto& msc = gameObject_.getOrAdd<helios::engine::modules::rendering::model::components::ModelAabbComponent>();
351 msc.setAabb(renderable->localAABB());
352
353 if (isUiText_ || usesNumberFormatter_ || usesTimeFormatter_) {
354 gameObject_.add<helios::engine::modules::ui::widgets::components::UiTextComponent>(renderable.get());
355 isUiText_ = false;
356 }
357
358 if (usesTimeFormatter_) {
359 auto& tfc = gameObject_.add<helios::engine::modules::ui::layout::components::TimeFormatterComponent>();
360 tfc.setFormat(
361 timestampFormat_,
362 displayRemaining_ ? modules::ui::layout::types::TimeDisplayMode::Remaining
363 : modules::ui::layout::types::TimeDisplayMode::Elapsed
364 );
365 if (showElapsedLabel_) {
366 tfc.setElapsedLabel(elapsedLabel_);
367 }
368 tfc.setHideWhenZero(hideWhenZero_);
369 usesTimeFormatter_ = false;
370 }
371
372 if (usesNumberFormatter_) {
373 gameObject_.add<helios::engine::modules::ui::layout::components::NumberFormatterComponent>()
374 .setFormat(numberFormat_);
375 usesNumberFormatter_ = false;
376 }
377
378
379 return *this;
380 }
381
382 };
383
384}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.