From 637e6a7be6e239d9aa6b798f343bf2b39a8281e4 Mon Sep 17 00:00:00 2001
From: Vanessa Karolek <vaka1997@uni-koblenz.de>
Date: Tue, 1 Jun 2021 17:20:39 +0200
Subject: [PATCH] [#42][Doc] add documentation of camera class
---
modules/camera/include/vkcv/camera/Camera.hpp | 143 ++++++++++++++----
modules/camera/src/vkcv/camera/Camera.cpp | 10 +-
2 files changed, 121 insertions(+), 32 deletions(-)
diff --git a/modules/camera/include/vkcv/camera/Camera.hpp b/modules/camera/include/vkcv/camera/Camera.hpp
index 7fd8ed6c..44689c70 100644
--- a/modules/camera/include/vkcv/camera/Camera.hpp
+++ b/modules/camera/include/vkcv/camera/Camera.hpp
@@ -8,7 +8,6 @@ namespace vkcv {
/**
* @brief Used to create a camera whose position can be changed.
- *
*/
class Camera {
protected:
@@ -39,13 +38,19 @@ namespace vkcv {
bool m_right;
public:
+
+ /**
+ * @brief The default constructor of the camera
+ */
Camera();
+ /**
+ * @brief The destructor of the camera (default behavior)
+ */
virtual ~Camera();
/**
- * @brief Set the Perspective object
- *
+ * @brief Sets the perspective object according to @p fov, @p ratio, @p near and @p far. This leads to changes in the projection matrix of the camera
* @param fov The desired field of view in radians
* @param ratio The aspect ratio
* @param near Distance to near clipping plane
@@ -53,91 +58,175 @@ namespace vkcv {
*/
void setPerspective(float fov, float ratio, float near, float far);
+ /**
+ * @brief Gets the view matrix of the camera
+ * @return The view matrix of the camera
+ */
const glm::mat4 getView() const;
/**
- * @brief Get the View object
- *
- * @param x
- * @param y
- * @param z
- * @param pos
+ * @brief Gets the view object containing the @p x, @p y, @p z axis in camera space, and the camera position @p pos in world space
+ * @param x The horizontal axis in camera space
+ * @param y The vertical axis in camera space
+ * @param z The depth axis in camera space
+ * @param pos The position of the camera in world space
*/
void getView(glm::vec3 &x, glm::vec3 &y, glm::vec3 &z, glm::vec3 &pos);
+ /**
+ * @brief Updates the view matrix of the camera with respect to @p deltatime
+ * @param deltatime The time past between frames
+ * @return
+ */
glm::mat4 updateView(double deltatime);
+ /**
+ * @brief Sets the view matrix of the camera according to @p position, @p center and @p up
+ * @param[out] position The position of the camera
+ * @param[out] center The target position the camera is looking at
+ * @param[out] up The vector that defines which direction is 'up' depending on the camera's orientation
+ */
void lookAt(glm::vec3 position, glm::vec3 center, glm::vec3 up);
+ /**
+ * @brief Gets the current projection of the camera
+ * @return The current projection matrix
+ */
const glm::mat4& getProjection() const;
/**
- * @brief Set the Projection matrix
- *
- * @param projection The projection matrix (4x4)
+ * @brief Sets the projection matrix of the camera to @p projection
+ * @param[in] projection The projection matrix
*/
void setProjection(const glm::mat4 projection);
+ /**
+ * @brief Gets the near and far bounds of the view frustum of the camera.
+ * @param[out] near The near bound of the view frustum
+ * @param[out] far The far bound of the view frustum
+ */
void getNearFar(float &near, float &far) const;
- void setUp(const glm::vec3 &Up);
+ /**
+ * @brief Sets the up vector of the camera to @p up
+ * @param[in] up The new up vector of the camera
+ */
+ void setUp(const glm::vec3 &up);
/**
- * @brief Get the Field of view in radians
- *
- * @return Field of view in radians
+ * @brief Gets the current field of view of the camera in radians
+ * @return[in] The current field of view in radians
*/
float getFov() const;
/**
- * @brief Set the Field of view in radians
- *
- * @param fov Field of view in radians
+ * @brief Sets the field of view of the camera to @p fov in radians
+ * @param[in] fov The new field of view in radians
*/
void setFov(float fov);
/**
- * @brief Changes the Field of view with offset in degrees
- *
- * @param offset in degrees
+ * @brief Changes the field of view of the camera with an @p offset in degrees
+ * @param[in] offset in degrees
*/
void changeFov(double offset);
-
+
+ /**
+ * @brief Updates the aspect ratio of the camera with @p ratio and, thus, changes the projection matrix
+ * @param[in] ratio The new aspect ratio of the camera
+ */
void updateRatio(float ratio);
/**
- * @brief Get the Ratio
- *
- * @return float aspect ratio
+ * @brief Gets the current aspect ratio of the camera
+ * @return The current aspect ratio of the camera
*/
float getRatio() const;
+ /**
+ * @brief Sets @p near and @p far as new values for the view frustum of the camera. This leads to changes in the projection matrix according to these two values.
+ * @param[in] near The new near bound of the view frustum
+ * @param[in] far The new far bound of the view frustum
+ */
void setNearFar(float near, float far);
+ /**
+ * @brief Gets the current front vector of the camera in world space
+ * @return The current front vector of the camera
+ */
glm::vec3 getFront() const;
+ /**
+ * @brief Gets the current position of the camera in world space
+ * @return The current position of the camera in world space
+ */
glm::vec3 getPosition() const;
+ /**
+ * @brief Sets the position of the camera to @p position
+ * @param[in] position The new position of the camera
+ */
void setPosition( glm::vec3 position );
+ /**
+ * @brief Gets the pitch value of the camera in degrees
+ * @return The pitch value in degrees
+ */
float getPitch() const;
+ /**
+ * @brief Sets the pitch value of the camera to @p pitch in degrees
+ * @param[in] pitch The new pitch value in degrees
+ */
void setPitch(float pitch);
+ /**
+ * @brief Gets the yaw value of the camera in degrees
+ * @return The yaw value in degrees
+ */
float getYaw() const;
+ /**
+ * @brief Sets the yaw value of the camera to @p yaw
+ * @param[in] yaw The new yaw value in degrees
+ */
void setYaw(float yaw);
+ /**
+ * @brief Pans the view of the camera according to the pitch and yaw values and additional offsets @p xOffset and @p yOffset (e.g. taken from mouse movement)
+ * @param[in] xOffset The offset added to the yaw value
+ * @param[in] yOffset The offset added to the pitch value
+ */
void panView( double xOffset, double yOffset );
- void updatePosition(double deltatime);
+ /**
+ * @brief Updates the position of the camera with respect to @p deltaTime
+ * @param[in] deltaTime The time that has passed since last update
+ */
+ void updatePosition(double deltaTime);
+ /**
+ * @brief Indicates forward movement of the camera depending on the performed @p action
+ * @param[in] action The performed action
+ */
void moveForward(int action);
+ /**
+ * @brief Indicates backward movement of the camera depending on the performed @p action
+ * @param[in] action The performed action
+ */
void moveBackward(int action);
+ /**
+ * @brief Indicates left movement of the camera depending on the performed @p action
+ * @param[in] action The performed action
+ */
void moveLeft(int action);
+ /**
+ * @brief Indicates right movement of the camera depending on the performed @p action
+ * @param[in] action The performed action
+ */
void moveRight(int action);
};
diff --git a/modules/camera/src/vkcv/camera/Camera.cpp b/modules/camera/src/vkcv/camera/Camera.cpp
index 921ba5e4..e45e9c59 100644
--- a/modules/camera/src/vkcv/camera/Camera.cpp
+++ b/modules/camera/src/vkcv/camera/Camera.cpp
@@ -158,11 +158,11 @@ namespace vkcv {
setPitch(m_pitch + yOffset);
}
- void Camera::updatePosition(double deltatime ){
- m_position += (m_cameraSpeed * getFront() * static_cast<float> (m_forward) * static_cast<float>(deltatime));
- m_position -= (m_cameraSpeed * getFront() * static_cast<float> (m_backward) * static_cast<float>(deltatime));
- m_position -= (glm::normalize(glm::cross(getFront(), m_up)) * m_cameraSpeed * static_cast<float> (m_left) * static_cast<float>(deltatime));
- m_position += (glm::normalize(glm::cross(getFront(), m_up)) * m_cameraSpeed * static_cast<float> (m_right) * static_cast<float>(deltatime));
+ void Camera::updatePosition(double deltaTime ){
+ m_position += (m_cameraSpeed * getFront() * static_cast<float> (m_forward) * static_cast<float>(deltaTime));
+ m_position -= (m_cameraSpeed * getFront() * static_cast<float> (m_backward) * static_cast<float>(deltaTime));
+ m_position -= (glm::normalize(glm::cross(getFront(), m_up)) * m_cameraSpeed * static_cast<float> (m_left) * static_cast<float>(deltaTime));
+ m_position += (glm::normalize(glm::cross(getFront(), m_up)) * m_cameraSpeed * static_cast<float> (m_right) * static_cast<float>(deltaTime));
}
void Camera::moveForward(int action){
--
GitLab