Skip to main content

RotationStateComponent.ixx File

Component for managing composite rotation state from heading and spin. More...

Included Headers​

#include <cmath> #include <helios.math>

Namespaces Index​

namespacehelios
namespaceengine

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

namespacemodules

Domain-specific components and systems. More...

namespacespatial
namespacetransform

Transform components and systems for spatial state management. More...

namespacecomponents

Transform state components for spatial management. More...

Classes Index​

classRotationStateComponent

Component that manages composite rotation from heading and spin rotations. More...

Description​

Component for managing composite rotation state from heading and spin.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file RotationStateComponent.ixx
3 * @brief Component for managing composite rotation state from heading and spin.
4 */
5module;
6
7#include <cmath>
8
9export module helios.engine.modules.spatial.transform.components.RotationStateComponent;
10
11
12
13import helios.math;
14
15/**
16 * @todo move to spatial transform
17 */
18export namespace helios::engine::modules::spatial::transform::components {
19
20 /**
21 * @brief Component that manages composite rotation from heading and spin rotations.
22 *
23 * @details
24 * This component combines two independent rotation sources:
25 * - **Heading Rotation:** The direction the entity is facing (controlled by input).
26 * - **Spin Rotation:** Additional rotation for visual effects (e.g., rolling, tumbling).
27 *
28 * The component caches the computed rotation matrices and only recalculates them
29 * when the underlying angles or axes change (dirty flag pattern).
30 */
31 class RotationStateComponent {
32
33 /**
34 * @brief Current heading rotation angle in degrees.
35 */
36 float headingRotationAngle_ = 0.0f;
37
38 /**
39 * @brief Axis around which heading rotation occurs.
40 */
41 helios::math::vec3f headingRotationAxis_{};
42
43 /**
44 * @brief Current spin rotation angle in degrees.
45 */
46 float spinRotationAngle_ = 0.0f;
47
48 /**
49 * @brief Axis around which spin rotation occurs.
50 */
51 helios::math::vec3f spinRotationAxis_{};
52
53 /**
54 * @brief Dirty flag indicating matrices need recalculation.
55 */
56 bool needsUpdate_ = true;
57
58 /**
59 * @brief Cached spin rotation matrix.
60 */
61 helios::math::mat4f spinRotationMatrix_;
62
63 /**
64 * @brief Cached heading rotation matrix.
65 */
66 helios::math::mat4f headingRotationMatrix_;
67
68 /**
69 * @brief Cached composed rotation matrix (heading * spin).
70 */
71 helios::math::mat4f composedRotationMatrix_;
72
73 /**
74 * @brief Whether this component is enabled.
75 */
76 bool isEnabled_ = true;
77
78 public:
79
80 /**
81 * @brief Checks whether this component is enabled.
82 *
83 * @return True if enabled, false otherwise.
84 */
85 [[nodiscard]] bool isEnabled() const noexcept {
86 return isEnabled_;
87 }
88
89 /**
90 * @brief Enables this component.
91 */
92 void enable() noexcept {
93 isEnabled_ = true;
94 }
95
96 /**
97 * @brief Disables this component.
98 */
99 void disable() noexcept {
100 isEnabled_ = false;
101 }
102
103 private:
104
105 /**
106 * @brief Recalculates rotation matrices if dirty.
107 *
108 * @details Updates spinRotationMatrix_, headingRotationMatrix_, and
109 * composedRotationMatrix_ based on current angles and axes.
110 */
111 void update() {
112
113 if (!needsUpdate_) {
114 return;
115 }
116 needsUpdate_ = false;
117
118 spinRotationMatrix_ = helios::math::rotate(
119 helios::math::mat4f::identity(),
120 helios::math::radians(spinRotationAngle_),
121 spinRotationAxis_
122 );
123
124 headingRotationMatrix_ = helios::math::rotate(
125 helios::math::mat4f::identity(),
126 helios::math::radians(headingRotationAngle_),
127 headingRotationAxis_
128
129 );
130
131 composedRotationMatrix_ = headingRotationMatrix_ * spinRotationMatrix_;
132 }
133
134 public:
135
136 /**
137 * @brief Default constructor.
138 */
139 RotationStateComponent() = default;
140
141 /**
142 * @brief Copy constructor.
143 *
144 * @param other The component to copy from.
145 *
146 * @details Copies rotation axes but resets angles and matrices.
147 */
148 RotationStateComponent(const RotationStateComponent& other) :
149 headingRotationAxis_(other.headingRotationAxis_),
150 spinRotationAxis_(other.spinRotationAxis_)
151 {}
152
153 RotationStateComponent& operator=(const RotationStateComponent&) = default;
154 RotationStateComponent(RotationStateComponent&&) noexcept = default;
155 RotationStateComponent& operator=(RotationStateComponent&&) noexcept = default;
156
157 /**
158 * @brief Sets the heading rotation angle.
159 *
160 * @param angle The new heading rotation angle in degrees (wrapped to 0-360).
161 */
162 void setHeadingRotationAngle(float angle) {
163 headingRotationAngle_ = std::fmod(angle, 360.0f);
164 needsUpdate_ = true;
165 }
166
167 /**
168 * @brief Returns the current heading rotation angle.
169 *
170 * @return The heading rotation angle in degrees.
171 */
172 [[nodiscard]] float headingRotationAngle() const noexcept {
173 return headingRotationAngle_;
174 }
175
176 /**
177 * @brief Sets the heading rotation axis.
178 *
179 * @param axis The new rotation axis (should be normalized).
180 */
181 void setHeadingRotationAxis(helios::math::vec3f axis) {
182 headingRotationAxis_ = axis;
183 needsUpdate_ = true;
184 }
185
186 /**
187 * @brief Returns the heading rotation axis.
188 *
189 * @return The current heading rotation axis.
190 */
191 [[nodiscard]] helios::math::vec3f headingRotationAxis() const noexcept {
192 return headingRotationAxis_;
193 }
194
195 /**
196 * @brief Sets the spin rotation angle.
197 *
198 * @param angle The new spin rotation angle in degrees (wrapped to 0-360).
199 */
200 void setSpinRotationAngle(float angle) {
201 spinRotationAngle_ = std::fmod(angle, 360.0f);
202 needsUpdate_ = true;
203 }
204
205 /**
206 * @brief Returns the current spin rotation angle.
207 *
208 * @return The spin rotation angle in degrees.
209 */
210 [[nodiscard]] float spinRotationAngle() const noexcept {
211 return spinRotationAngle_;
212 }
213
214 /**
215 * @brief Sets the spin rotation axis.
216 *
217 * @param axis The new spin rotation axis (should be normalized).
218 */
219 void setSpinRotationAxis(helios::math::vec3f axis) {
220 spinRotationAxis_ = axis;
221 needsUpdate_ = true;
222 }
223
224 /**
225 * @brief Returns the spin rotation axis.
226 *
227 * @return The current spin rotation axis.
228 */
229 [[nodiscard]] helios::math::vec3f spinRotationAxis() const noexcept {
230 return spinRotationAxis_;
231 }
232
233 /**
234 * @brief Returns the spin rotation matrix.
235 *
236 * @details Triggers matrix update if dirty.
237 *
238 * @return Const reference to the spin rotation matrix.
239 */
240 const helios::math::mat4f& spinRotation() noexcept {
241 update();
242 return spinRotationMatrix_;
243 }
244
245 /**
246 * @brief Returns the heading rotation matrix.
247 *
248 * @details Triggers matrix update if dirty.
249 *
250 * @return Const reference to the heading rotation matrix.
251 */
252 const helios::math::mat4f& headingRotation() noexcept {
253 update();
254 return headingRotationMatrix_;
255 }
256
257 /**
258 * @brief Returns the composed rotation matrix (heading * spin).
259 *
260 * @details Triggers matrix update if dirty.
261 *
262 * @return Const reference to the composed rotation matrix.
263 */
264 const helios::math::mat4f& rotation() noexcept {
265 update();
266 return composedRotationMatrix_;
267 }
268
269 };
270
271};
272

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.