Skip to main content

Camera.ixx File

Defines the Camera class providing view and projection matrices. More...

Included Headers​

#include <cassert> #include <helios.scene.SceneNode> #include <helios.math.types> #include <helios.math.transform> #include <helios.math.utils>

Namespaces Index​

namespacehelios
namespacescene

Scene graph and camera management. More...

Classes Index​

classCamera

Represents a camera for perspective or orthographic projection. More...

Description​

Defines the Camera class providing view and projection matrices.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file Camera.ixx
3 * @brief Defines the Camera class providing view and projection matrices.
4 */
5module;
6
7#include <cassert>
8
9export module helios.scene.Camera;
10
11import helios.math.utils;
12import helios.math.transform;
13import helios.math.types;
14import helios.scene.SceneNode;
15
16export namespace helios::scene {
17
18 /**
19 * @brief Represents a camera for perspective or orthographic projection.
20 *
21 * The camera provides the view and projection matrices, whereas the view matrix
22 * is computed as the inverse of the camera's world transform.
23 *
24 * The camera supports two projection modes:
25 * - **Perspective projection:** Simulates how the human eye perceives depth, where
26 * distant objects appear smaller. Use `setPerspective()` to configure.
27 * - **Orthographic projection:** Maintains parallel lines and uniform scaling regardless
28 * of distance, useful for 2D rendering, UI elements, or CAD-style views. Use `setOrtho()`
29 * to configure.
30 *
31 * By default, the camera uses perspective projection.
32 *
33 * Example usage:
34 * ```cpp
35 * helios::scene::Camera camera;
36 *
37 * // Perspective projection
38 * camera.setPerspective(helios::math::radians(60.0f), 16.0f / 9.0f, 0.1f, 1000.0f);
39 *
40 * // Orthographic projection
41 * camera.setOrtho(0.0f, 800.0f, 0.0f, 600.0f, -1.0f, 100.0f);
42 * ```
43 */
44 class Camera {
45
46 protected:
47 /**
48 * @brief The projection matrix of this camera.
49 */
50 mutable helios::math::mat4f perspectiveMatrix_;
51
52 /**
53 * @brief The orthographic projection matrix of this camera.
54 *
55 * Used when the camera is in orthographic mode (`usePerspective_ == false`).
56 */
57 mutable helios::math::mat4f orthographicMatrix_;
58
59 /**
60 * @brief The view matrix of this camera.
61 */
62 helios::math::mat4f viewMatrix_;
63
64 /**
65 * @brief The aspect ratio of the camera (width/height).
66 *
67 * Defaults to 1.0.
68 */
69 float aspectRatio_ = 1.0f;
70
71 /**
72 * @brief The near clipping plane distance.
73 *
74 * Defaults to 0.1.
75 */
76 float zNear_ = 0.1f;
77
78 /**
79 * @brief The far clipping plane distance.
80 *
81 * Defaults to 1000.0.
82 */
83 float zFar_ = 1000.0f;
84
85 /**
86 * @brief The vertical field of view in radians.
87 *
88 * Defaults to 90 degrees (converted to radians).
89 */
90 float fovY_ = helios::math::radians(90);
91
92 /**
93 * @brief Flag indicating whether the matrices need to be updated.
94 */
95 mutable bool needsUpdate_ = true;
96
97 /**
98 * @brief Left boundary of the orthographic frustum.
99 */
100 float left_;
101
102 /**
103 * @brief Right boundary of the orthographic frustum.
104 */
105 float right_;
106
107 /**
108 * @brief Bottom boundary of the orthographic frustum.
109 */
110 float bottom_;
111
112 /**
113 * @brief Top boundary of the orthographic frustum.
114 */
115 float top_;
116
117 /**
118 * @brief Flag indicating the projection mode.
119 *
120 * When `true`, perspective projection is used. When `false`, orthographic
121 * projection is used. Defaults to `true`.
122 */
123 bool usePerspective_ = true;
124
125 /**
126 * @brief Updates the view and projection matrices if needed.
127 *
128 * This function recalculates the view and projection matrices
129 * based on the current camera parameters.
130 */
131 void update() const {
132
133 if (!needsUpdate_) {
134 return;
135 }
136
137 if (usePerspective_) {
138 perspectiveMatrix_ = helios::math::perspective(fovY_, aspectRatio_, zNear_, zFar_);
139 } else {
140 orthographicMatrix_ = helios::math::ortho(left_, right_, bottom_, top_, zNear_, zFar_);
141 }
142
143 needsUpdate_ = false;
144 }
145
146 public:
147 /**
148 * @brief Constructs a camera with identity projection and view matrices.
149 */
150 Camera() noexcept :
151 perspectiveMatrix_(helios::math::mat4f::identity()),
152 orthographicMatrix_(helios::math::mat4f::identity()),
153 viewMatrix_(helios::math::mat4f::identity())
154 {}
155
156 /**
157 * @brief Gets the current projection matrix.
158 *
159 * Typically set to a perspective or orthographic projection.
160 *
161 * @return A const reference to this camera's projection matrix.
162 */
163 [[nodiscard]] const helios::math::mat4f& projectionMatrix() const noexcept {
164 update();
165
166 if (usePerspective_) {
167 return perspectiveMatrix_;
168 }
169 return orthographicMatrix_;
170 }
171
172
173 /**
174 * @brief Gets the current view matrix.
175 *
176 * The view matrix represents the inverse of the camera's world transform.
177 *
178 * @return A const reference to this camera's view matrix.
179 */
180 [[nodiscard]] const helios::math::mat4f& viewMatrix() const noexcept {
181 return viewMatrix_;
182 }
183
184 /**
185 * @brief Sets the view matrix for this camera.
186 *
187 * This method is typically called by `CameraSceneNode::worldTransform()` to update
188 * the view matrix based on the camera node's position and orientation in the scene graph.
189 *
190 * @param viewMatrix The new view matrix to assign.
191 *
192 * @return A const reference to this camera instance.
193 *
194 * @see helios::scene::CameraSceneNode::worldTransform()
195 */
196 Camera& setViewMatrix(const helios::math::mat4f& viewMatrix) noexcept {
197 viewMatrix_ = viewMatrix;
198 return *this;
199 }
200
201 /**
202 * @brief Sets the aspect ratio used by the camera.
203 *
204 * @param aspectRatio The new aspect ratio (width/height).
205 *
206 * @return A reference to this camera instance.
207 */
208 Camera& setAspectRatio(float aspectRatio) noexcept {
209 needsUpdate_ = true;
210 aspectRatio_ = aspectRatio;
211 return *this;
212 }
213
214 /**
215 * @brief Handles viewport resize events.
216 *
217 * Adjusts the camera projection parameters when the viewport dimensions change.
218 * - For perspective projection: Updates the aspect ratio.
219 * - For orthographic projection: Adjusts the right and top boundaries to maintain
220 * the correct projection volume.
221 *
222 * @param width The new viewport width in pixels.
223 * @param height The new viewport height in pixels.
224 */
225 void onResize(const float width, const float height) noexcept {
226
227 if (usePerspective_) {
228 setAspectRatio(width / height);
229 return;
230 }
231
232 if (left_ == 0.0f && bottom_ == 0.0f) {
233 right_ = width;
234 top_ = height;
235 } else {
236
237 left_ = -width/2.0f;
238 right_ = width/2.0f;
239 bottom_ = -height/2.0f;
240 top_ = height/2.0f;
241 }
242
243 needsUpdate_ = true;
244 }
245
246 /**
247 * @brief Sets the perspective projection parameters.
248 *
249 * @param fovY The vertical field of view in radians.
250 * @param aspectRatio The aspect ratio (width/height).
251 * @param zNear The near clipping plane distance.
252 * @param zFar The far clipping plane distance.
253 *
254 * @return A reference to this camera instance.
255 */
256 Camera& setPerspective(float fovY, float aspectRatio, float zNear, float zFar) noexcept {
257 assert(zNear > 0 && "zNear must be positive");
258 assert(zFar > 0 && zFar > zNear && "zFar must be positive and greater than zNear");
259 fovY_ = fovY;
260 aspectRatio_ = aspectRatio;
261 zNear_ = zNear;
262 zFar_ = zFar;
263 needsUpdate_ = true;
264 usePerspective_ = true;
265 return *this;
266 }
267
268 /**
269 * @brief Sets the orthographic projection parameters.
270 *
271 * Configures the camera for orthographic projection, which is useful for 2D rendering,
272 * UI overlays, or scenes where parallel lines should remain parallel (no perspective
273 * distortion).
274 *
275 * @param left The left boundary of the view volume.
276 * @param right The right boundary of the view volume.
277 * @param bottom The bottom boundary of the view volume.
278 * @param top The top boundary of the view volume.
279 * @param zNear The near clipping plane distance. Defaults to -1.0.
280 * @param zFar The far clipping plane distance. Defaults to 100.0.
281 *
282 * @return A reference to this camera instance.
283 *
284 * @note Calling this method switches the camera to orthographic projection mode.
285 */
286 Camera& setOrtho(
287 const float left , const float right,
288 const float bottom, const float top,
289 const float zNear = -1.0f, const float zFar = 100.0f) noexcept {
290
291 assert(zFar > zNear && "zFar must be greater than zNear");
292
293 zNear_ = zNear;
294 zFar_ = zFar;
295
296 left_ = left;
297 right_ = right;
298 bottom_ = bottom;
299 top_ = top;
300
301 aspectRatio_ = (right - left) / (top - bottom); // w/h
302
303 usePerspective_ = false;
304
305 needsUpdate_ = true;
306 return *this;
307 }
308
309 /**
310 * @brief Sets the near clipping plane distance.
311 *
312 * @param zNear The new near clipping plane distance.
313 *
314 * @return A reference to this camera instance.
315 */
316 Camera& setZNear(float zNear) noexcept {
317 zNear_ = zNear;
318 needsUpdate_ = true;
319 return *this;
320 }
321
322 /**
323 * @brief Sets the far clipping plane distance.
324 *
325 * @param zFar The new far clipping plane distance.
326 *
327 * @return A reference to this camera instance.
328 */
329 Camera& setZFar(float zFar) noexcept {
330 zFar_ = zFar;
331 needsUpdate_ = true;
332 return *this;
333 }
334
335 /**
336 * @brief Sets the vertical field of view.
337 *
338 * @param fovY The new vertical field of view in radians.
339 *
340 * @return A reference to this camera instance.
341 */
342 Camera& setFovY(float fovY) noexcept {
343 fovY_ = fovY;
344 needsUpdate_ = true;
345 return *this;
346 }
347
348 /**
349 * @brief Gets the current vertical field of view.
350 *
351 * @return The vertical field of view in radians.
352 */
353 [[nodiscard]] float fovY() const noexcept {
354 return fovY_;
355 }
356
357 /**
358 * @brief Gets the current aspect ratio.
359 *
360 * @return The aspect ratio (width/height).
361 */
362 [[nodiscard]] float aspectRatio() const noexcept {
363 return aspectRatio_;
364 }
365
366 /**
367 * @brief Gets the current near clipping plane distance.
368 *
369 * @return The near clipping plane distance.
370 */
371 [[nodiscard]] float zNear() const noexcept {
372 return zNear_;
373 }
374
375 /**
376 * @brief Gets the current far clipping plane distance.
377 *
378 * @return The far clipping plane distance.
379 */
380 [[nodiscard]] float zFar() const noexcept {
381 return zFar_;
382 }
383
384 };
385
386}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.