Skip to main content

MeshRenderable.ixx File

Representative of a configurable MeshRenderable rendered by the underlying GL API. More...

Included Headers​

#include <memory> #include <optional> #include <stdexcept> #include <helios.util.log.LogManager> #include <helios.util.log.Logger> #include <helios.rendering.RenderPrototype> #include <helios.rendering.material.MaterialShaderPropertiesOverride> #include <helios.rendering.RenderQueue> #include <helios.rendering.Renderable> #include <helios.rendering.shader.UniformValueMap> #include <helios.rendering.mesh.MeshRenderCommand>

Namespaces Index​

namespacehelios
namespacerendering

Graphics rendering infrastructure. More...

namespacemesh

Mesh rendering abstractions and command types. More...

Classes Index​

classMeshRenderable

Represents a renderable object that combines a shared prototype with instance-specific overrides. More...

Macro Definitions Index​

#defineHELIOS_LOG_SCOPE   "helios::rendering::MeshRenderable"

Description​

Representative of a configurable MeshRenderable rendered by the underlying GL API.

Macro Definitions​

HELIOS_LOG_SCOPE​

#define HELIOS_LOG_SCOPE   "helios::rendering::MeshRenderable"

Definition at line 24 of file MeshRenderable.ixx.

24#define HELIOS_LOG_SCOPE "helios::rendering::MeshRenderable"

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file MeshRenderable.ixx
3 * @brief Representative of a configurable MeshRenderable rendered by the underlying GL API.
4 */
5module;
6
7#include <memory>
8#include <optional>
9#include <stdexcept>
10
11export module helios.rendering.mesh.MeshRenderable;
12
13import helios.rendering.mesh.MeshRenderCommand;
14
15import helios.rendering.Renderable;
16import helios.rendering.RenderQueue;
17import helios.rendering.RenderPrototype;
18import helios.rendering.material.MaterialShaderPropertiesOverride;
19import helios.rendering.shader.UniformValueMap;
20
21import helios.util.log.Logger;
22import helios.util.log.LogManager;
23
24#define HELIOS_LOG_SCOPE "helios::rendering::MeshRenderable"
25export namespace helios::rendering::mesh {
26
27
28 /**
29 * @brief Represents a renderable object that combines a shared prototype with instance-specific overrides.
30 *
31 * A `MeshRenderable` aggregates an immutable `RenderPrototype` (shared asset definition)
32 * with optional instance-specific `MaterialShaderPropertiesOverride`. This separation enables
33 * efficient batching of shared prototypes while allowing per-instance visual adjustments.
34 *
35 * ## Design
36 *
37 * - **Shared Prototype:** Multiple `MeshRenderable` instances can reference the same `RenderPrototype`.
38 * - **Per-Instance Overrides:** Each instance can customize material properties.
39 * - **Move-Only:** Prevents accidental duplication during render queue processing.
40 *
41 * ## Data Flow
42 *
43 * ```
44 * RenderPrototype (shared)
45 * │
46 * ├── MeshRenderable A (override: red color)
47 * ├── MeshRenderable B (override: blue color)
48 * └── MeshRenderable C (no override)
49 * ```
50 *
51 * ## Performance Considerations
52 *
53 * **PERF-NOTE: shared_ptr overhead**
54 *
55 * The `renderPrototype_` member uses `std::shared_ptr`, which incurs atomic
56 * reference counting overhead on every copy. In the hot rendering path, consider:
57 *
58 * - Returning `const RenderPrototype&` instead of `std::shared_ptr` from getters
59 * when ownership transfer is not required.
60 * - Using `std::shared_ptr<T>::get()` for temporary access instead of copying
61 * the shared_ptr.
62 * - Evaluating whether `std::unique_ptr` with raw pointer access would suffice
63 * if the prototype lifetime is well-defined (e.g., asset manager ownership).
64 *
65 * @see renderPrototype()
66 *
67 * @note For text rendering, use `TextRenderable` instead.
68 *
69 * @see RenderPrototype
70 * @see RenderCommand
71 * @see MaterialShaderPropertiesOverride
72 */
73 class MeshRenderable final : public helios::rendering::Renderable {
74
75 protected:
76
77 /**
78 * @brief Shared pointer to the immutable RenderPrototype definition.
79 */
80 std::shared_ptr<const helios::rendering::RenderPrototype> renderPrototype_ = nullptr;
81
82 /**
83 * @brief The MaterialShaderPropertiesOverride owned by this class. This will be std::nullopt if not
84 * available.
85 */
86 std::optional<helios::rendering::material::MaterialShaderPropertiesOverride> materialOverride_;
87
88 /**
89 * @brief Shared logger instance for all MeshRenderable objects.
90 */
91 inline static const helios::util::log::Logger& logger_ = helios::util::log::LogManager::loggerForScope(HELIOS_LOG_SCOPE);
92
93 public:
94 /**
95 * @brief Deleted default constructor.
96 */
97 MeshRenderable() = delete;
98
99 /**
100 * @brief Deleted copy constructor.
101 */
102 MeshRenderable(const MeshRenderable&) = delete;
103
104 /**
105 * @brief Deleted copy assignment operator.
106 */
107 MeshRenderable& operator=(const MeshRenderable&)= delete;
108
109 /**
110 * @brief Defaulted move constructor.
111 */
112 MeshRenderable(MeshRenderable&&) noexcept = default;
113
114 /**
115 * @brief Defaulted move assignment operator.
116 */
117 MeshRenderable& operator=(MeshRenderable&&) noexcept = default;
118
119 /**
120 * @brief Creates a new MeshRenderable instance.
121 *
122 * @param renderPrototype A shared pointer to the immutable RenderPrototype definition. Must not be nullptr.
123 * @param materialOverride An optional set of instance-specific material property overrides.
124 * If std::nullopt, the MeshRenderable uses only the default properties from the RenderPrototype's Material.
125 *
126 * @throws std::invalid_argument if `renderPrototype` is a nullptr.
127 */
128 explicit MeshRenderable(
129 std::shared_ptr<const helios::rendering::RenderPrototype> renderPrototype,
130 const std::optional<helios::rendering::material::MaterialShaderPropertiesOverride>& materialOverride = std::nullopt
131 ) :
132 renderPrototype_(std::move(renderPrototype)),
133 materialOverride_(materialOverride)
134 {
135
136 if (!renderPrototype_) {
137 const std::string msg = "MeshRenderable constructor received a null shared pointer.";
138 logger_.error(msg);
139 throw std::invalid_argument(msg);
140 }
141
142 }
143
144
145 /**
146 * @brief Returns a shared pointer to the RenderPrototype used by this MeshRenderable.
147 *
148 * @return A shared pointer to the RenderPrototype.
149 */
150 [[nodiscard]] std::shared_ptr<const helios::rendering::RenderPrototype> shareRenderPrototype() const noexcept {
151 return renderPrototype_;
152 }
153
154 /**
155 * @brief Returns a raw pointer to the RenderPrototype used by this MeshRenderable.
156 *
157 * This method provides direct access to the prototype without incrementing the
158 * reference count, making it suitable for use in hot rendering paths.
159 *
160 * @return A raw pointer to the RenderPrototype (never null after construction).
161 */
162 [[nodiscard]] const helios::rendering::RenderPrototype* renderPrototype() const noexcept {
163 return renderPrototype_.get();
164 }
165
166 /**
167 * @brief Returns a const reference to the optional instance-specific MaterialShaderPropertiesOverride.
168 *
169 * This allows read-only access to the overrides. Use `.has_value()` to check for existence
170 * and `.value()` or `->` to safely access the override data.
171 *
172 * @return A const reference to the std::optional<MaterialShaderPropertiesOverride>.
173 */
174
175 [[nodiscard]] const std::optional<helios::rendering::material::MaterialShaderPropertiesOverride>& materialOverride() const noexcept {
176 return materialOverride_;
177 }
178
179 /**
180 * @brief Returns a non-const reference to the optional instance-specific MaterialShaderPropertiesOverride.
181 *
182 * This allows modification of the overrides. If the optional currently has no value,
183 * it can be assigned to or `.emplace()` can be used to create a new MaterialShaderPropertiesOverride.
184 *
185 * @return A non-const reference to the std::optional<MaterialShaderPropertiesOverride>.
186 */
187 [[nodiscard]] std::optional<helios::rendering::material::MaterialShaderPropertiesOverride>& materialOverride() noexcept {
188 return materialOverride_;
189 }
190
191 /**
192 * @brief Returns true if this MeshRenderable was configured with a MaterialShaderPropertiesOverride.
193 *
194 * @return True if this MeshRenderable was configured with a MaterialShaderPropertiesOverride instance, otherwise false.
195 */
196 [[nodiscard]] bool hasMaterialOverride() const noexcept {
197 return materialOverride_.has_value();
198 }
199
200 /**
201 * @brief Returns the local-space axis-aligned bounding box.
202 *
203 * Delegates to the underlying mesh's AABB from the render prototype.
204 *
205 * @return A const reference to the local-space AABB.
206 */
207 [[nodiscard]] const helios::math::aabbf& localAABB() const noexcept override {
208 return renderPrototype_->mesh().aabb();
209 }
210
211 /**
212 * @brief Writes uniform values into the given map.
213 *
214 * This method first applies the default uniform values from the base Material definition and
215 * then overlays any specific overrides provided by this instance's MaterialShaderPropertiesOverride.
216 *
217 * @param uniformValueMap Target map receiving the uniform values.
218 */
219 void writeUniformValues(helios::rendering::shader::UniformValueMap& uniformValueMap) const noexcept override {
220 renderPrototype_->material().writeUniformValues(uniformValueMap);
221
222 if (materialOverride_) {
223 materialOverride_->writeUniformValues(uniformValueMap);
224 }
225 }
226
227 /**
228 * @brief Emits a mesh render command to the render queue.
229 *
230 * Creates a `MeshRenderCommand` with the render prototype and uniform values,
231 * then adds it to the render queue for processing by the rendering device.
232 *
233 * @param renderQueue The render queue to emit the command to.
234 * @param objectUniformValues Object-specific uniform values (e.g., model matrix).
235 * @param materialUniformValues Material uniform values (will be merged with material properties).
236 */
237 void emit(
238 helios::rendering::RenderQueue& renderQueue,
239 helios::rendering::shader::UniformValueMap& objectUniformValues,
240 helios::rendering::shader::UniformValueMap& materialUniformValues) const override {
241
242 writeUniformValues(materialUniformValues);
243
244 renderQueue.add(helios::rendering::mesh::MeshRenderCommand(
245 renderPrototype_.get(),
246 objectUniformValues,
247 materialUniformValues
248 ));
249 };
250
251
252 };
253
254}
255

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.