[#42][Doc] adjust documentation, fix trackball camera radius issue

Before:
If more than one trackball camera controller is added to your application, changing the m_radius variable via scroll event would lead to adjusting the radius for all cameras attached to the trackball camera controller.

After:
Before updating the radius, the m_radius variable is changed in respect to the current distance from the camera to its center point. This enables handling all cameras with attached trackball camera controller separately.

modules/camera/include/vkcv/camera/Camera.hpp

@@ -42,10 +42,10 @@ namespace vkcv {
         
         /**
          * @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
-         * @param far Distance to far clipping plane
+         * @param[in] fov The desired field of view in radians
+         * @param[in] ratio The aspect ratio
+         * @param[in] near Distance to near clipping plane
+         * @param[in] far Distance to far clipping plane
          */
         void setPerspective(float fov, float ratio, float near, float far);
 
@@ -57,9 +57,9 @@ namespace vkcv {
 
         /**
          * @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
+         * @param[in] position The position of the camera
+         * @param[in] center The target position the camera is looking at
+         * @param[in] 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);
 
@@ -145,7 +145,7 @@ namespace vkcv {
 
         /**
          * @brief Sets @p center as the new center point.
-         * @param center The new center point.
+         * @param[in] center The new center point.
          */
         void setCenter(glm::vec3 center);
 
@@ -181,7 +181,7 @@ namespace vkcv {
 
         /**
          * @brief Sets @p up as the new up vector.
-         * @param up The new up vector.
+         * @param[in] up The new up vector.
          */
         void setUp(const glm::vec3 &up);
     };

modules/camera/include/vkcv/camera/CameraController.hpp

@@ -19,8 +19,9 @@ namespace vkcv {
         CameraController() = default;
 
         /**
-         * @brief Updates the camera object in respect to @p deltaTime.
-         * @param deltaTime The time that has passed since last update.
+         * @brief Updates @p camera in respect to @p deltaTime.
+         * @param[in] deltaTime The time that has passed since last update.
+         * @param[in] camera The camera object.
          */
         virtual void updateCamera(double deltaTime, Camera &camera);
 
@@ -30,6 +31,7 @@ namespace vkcv {
          * @param[in] scancode The platform-specific scancode.
          * @param[in] action The key action.
          * @param[in] mods The modifier bits.
+         * @param[in] camera The camera object.
          */
         virtual void keyCallback(int key, int scancode, int action, int mods, Camera &camera);
 
@@ -37,6 +39,7 @@ namespace vkcv {
          * @brief A callback function for mouse scrolling events.
          * @param[in] offsetX The offset in horizontal direction.
          * @param[in] offsetY The offset in vertical direction.
+         * @param[in] camera The camera object.
          */
         virtual void scrollCallback( double offsetX, double offsetY, Camera &camera);
 
@@ -44,6 +47,7 @@ namespace vkcv {
          * @brief A callback function for mouse movement events.
          * @param[in] x The horizontal mouse position.
          * @param[in] y The vertical mouse position.
+         * @param[in] camera The camera object.
          */
         virtual void mouseMoveCallback(double offsetX, double offsetY, Camera &camera);
 
@@ -52,6 +56,7 @@ namespace vkcv {
          * @param[in] button The mouse button.
          * @param[in] action The button action.
          * @param[in] mods The modifier bits.
+         * @param[in] camera The camera object.
          */
         virtual void mouseButtonCallback(int button, int action, int mods, Camera &camera);
     };

modules/camera/include/vkcv/camera/CameraManager.hpp

@@ -113,14 +113,14 @@ namespace vkcv {
         /**
          * @brief Adds a new camera object to the #CameraManager and binds it to a camera controller object of specified
          * @p controllerType.
-         * @param controllerType The type of the camera controller.
+         * @param[in] controllerType The type of the camera controller.
          * @return The index of the newly created camera object.
          */
         int addCamera(ControllerType controllerType);
 
         /**
          * @brief Gets the stored camera object located at @p cameraIndex.
-         * @param cameraIndex The camera index.
+         * @param[in] cameraIndex The camera index.
          * @return The camera object at @p cameraIndex.
          * @throws std::runtime_error If @p cameraIndex is not a valid camera index.
          */
@@ -134,7 +134,7 @@ namespace vkcv {
 
         /**
          * @brief Sets the stored camera object located at @p cameraIndex as the active camera.
-         * @param cameraIndex The camera index.
+         * @param[in] cameraIndex The camera index.
          * @throws std::runtime_error If @p cameraIndex is not a valid camera index.
          */
         void setActiveCamera(uint32_t cameraIndex);
@@ -148,15 +148,15 @@ namespace vkcv {
         /**
          * @brief Binds a stored camera object located at @p cameraIndex to a camera controller of specified
          * @p controllerType.
-         * @param cameraIndex The camera index.
-         * @param controllerType The type of the camera controller.
+         * @param[in] cameraIndex The camera index.
+         * @param[in] controllerType The type of the camera controller.
          * @throws std::runtime_error If @p cameraIndex is not a valid camera index.
          */
         void setControllerType(uint32_t cameraIndex, ControllerType controllerType);
 
         /**
          * @brief Gets the currently bound camera controller type of the stored camera object located at @p cameraIndex.
-         * @param cameraIndex The camera index.
+         * @param[in] cameraIndex The camera index.
          * @return The type of the camera controller of the specified camera object.
          * @throws std::runtime_error If @p cameraIndex is not a valid camera index.
          */
@@ -164,14 +164,14 @@ namespace vkcv {
 
         /**
          * @brief Gets a camera controller object of specified @p controllerType.
-         * @param controllerType The type of the camera controller.
+         * @param[in] controllerType The type of the camera controller.
          * @return The specified camera controller object.
          */
         CameraController& getControllerByType(ControllerType controllerType);
 
         /**
          * @brief Updates all stored camera controllers in respect to @p deltaTime.
-         * @param deltaTime The time that has passed since last update.
+         * @param[in] deltaTime The time that has passed since last update.
          */
         void update(double deltaTime);
 

modules/camera/include/vkcv/camera/PilotCameraController.hpp

@@ -27,15 +27,17 @@ namespace vkcv {
 
 
         /**
-         * @brief Updates the position of the camera with respect to @p deltaTime.
+         * @brief Updates the position of @p camera with respect to @p deltaTime.
          * @param[in] deltaTime The time that has passed since last update.
+         * @param[in] camera The camera object.
          * @return The updated camera position.
          */
         glm::vec3 updatePosition(double deltaTime, Camera &camera);
 
         /**
-         * @brief Updates the view matrix of the camera with respect to @p deltaTime.
-         * @param deltaTime The time that has passed since last update.
+         * @brief Updates the view matrix of @p camera with respect to @p deltaTime.
+         * @param[in] deltaTime The time that has passed since last update.
+         * @param[in] camera The camera object.
          * @return The updated view matrix of the camera.
          */
         glm::mat4 updateView(double deltaTime, Camera &camera);
@@ -89,22 +91,25 @@ namespace vkcv {
         ~PilotCameraController() = default;
 
         /**
-         * @brief Changes the field of view of the camera with an @p offset in degrees.
+         * @brief Changes the field of view of @p camera with an @p offset in degrees.
          * @param[in] offset The offset in degrees.
+         * @param[in] camera The camera object.
          */
         void changeFov(double offset, Camera &camera);
 
         /**
-         * @brief Pans the view of the camera according to the pitch and yaw values and additional offsets @p xOffset
+         * @brief Pans the view of @p camera according to the pitch and yaw values and additional offsets @p xOffset
          * and @p yOffset.
          * @param[in] xOffset The offset added to the yaw value.
          * @param[in] yOffset The offset added to the pitch value.
+         * @param[in] camera The camera object.
          */
         void panView(double xOffset, double yOffset, Camera &camera);
 
         /**
-         * @brief Updates the camera object in respect to @p deltaTime.
-         * @param deltaTime The time that has passed since last update.
+         * @brief Updates @p camera in respect to @p deltaTime.
+         * @param[in] deltaTime The time that has passed since last update.
+         * @param[in] camera The camera object.
          */
         void updateCamera(double deltaTime, Camera &camera);
 
@@ -114,14 +119,16 @@ namespace vkcv {
          * @param[in] scancode The platform-specific scancode.
          * @param[in] action The key action.
          * @param[in] mods The modifier bits.
+         * @param[in] camera The camera object.
          */
         void keyCallback(int key, int scancode, int action, int mods, Camera &camera);
 
         /**
          * @brief A callback function for mouse scrolling events. Currently, this leads to changes in the field of view
-         * of the camera object.
+         * of @p camera.
          * @param[in] offsetX The offset in horizontal direction.
          * @param[in] offsetY The offset in vertical direction.
+         * @param[in] camera The camera object.
          */
         void scrollCallback(double offsetX, double offsetY, Camera &camera);
 
@@ -130,6 +137,7 @@ namespace vkcv {
          * if #mouseButtonCallback(int button, int action, int mods) enabled panning.
          * @param[in] x The horizontal mouse position
          * @param[in] y The vertical mouse position
+         * @param[in] camera The camera object.
          */
         void mouseMoveCallback(double x, double y, Camera &camera);
 
@@ -139,6 +147,7 @@ namespace vkcv {
          * @param[in] button The mouse button
          * @param[in] action The button action
          * @param[in] mods The modifier bits
+         * @param[in] camera The camera object.
          */
         void mouseButtonCallback(int button, int action, int mods, Camera &camera);
     };

modules/camera/include/vkcv/camera/TrackballCameraController.hpp

@@ -17,22 +17,26 @@ namespace vkcv {
 
 
         /**
-         * @brief Updates the position of the camera.
+         * @brief Updates the position of @p camera.
+         * @param[in] camera The camera object.
+         * @param[in] camera The camera object.
          * @return The updated camera position.
          */
         glm::vec3 updatePosition(Camera &camera);
 
         /**
-         * @brief Updates the view matrix of the camera.
+         * @brief Updates the view matrix of @p camera.
+         * @param[in] camera The camera object.
          * @return The updated view matrix of the camera.
          */
         glm::mat4 updateView(Camera &camera);
 
         /**
-         * @brief Updates the current radius in respect to the @p offset.
-         * @param offset The offset between the old and new radius.
+         * @brief Updates the current radius of @p camera in respect to the @p offset.
+         * @param[in] offset The offset between the old and new radius.
+         * @param[in] camera The camera object.
          */
-        void updateRadius(double offset);
+        void updateRadius(double offset, Camera &camera);
 
     public:
 
@@ -48,22 +52,24 @@ namespace vkcv {
 
         /**
          * @brief Sets @p radius as the new radius for orbiting around the camera's center point.
-         * @param radius The new radius.
+         * @param[in] radius The new radius.
          */
         void setRadius(const float radius);
 
         /**
-         * @brief Pans the view of the camera according to the pitch and yaw values and additional offsets @p xOffset
+         * @brief Pans the view of @p camera according to the pitch and yaw values and additional offsets @p xOffset
          * and @p yOffset.
          * @param[in] xOffset The offset added to the yaw value.
          * @param[in] yOffset The offset added to the pitch value.
+         * @param[in] camera The camera object.
          */
         void panView(double xOffset, double yOffset, Camera &camera);
 
         /**
-        * @brief Updates the camera object in respect to @p deltaTime.
-        * @param deltaTime The time that has passed since last update.
-        */
+         * @brief Updates @p camera in respect to @p deltaTime.
+         * @param[in] deltaTime The time that has passed since last update.
+         * @param[in] camera The camera object
+         */
         void updateCamera(double deltaTime, Camera &camera);
 
         /**
@@ -73,6 +79,7 @@ namespace vkcv {
          * @param[in] scancode The platform-specific scancode.
          * @param[in] action The key action.
          * @param[in] mods The modifier bits.
+         * @param[in] camera The camera object.
          */
         void keyCallback(int key, int scancode, int action, int mods, Camera &camera);
 
@@ -81,14 +88,16 @@ namespace vkcv {
          * of the camera object.
          * @param[in] offsetX The offset in horizontal direction.
          * @param[in] offsetY The offset in vertical direction.
+         * @param[in] camera The camera object.
          */
         void scrollCallback(double offsetX, double offsetY, Camera &camera);
 
         /**
          * @brief A callback function for mouse movement events. Currently, this leads to panning the view of the
          * camera, if #mouseButtonCallback(int button, int action, int mods) enabled panning.
-         * @param[in] x The horizontal mouse position.
-         * @param[in] y The vertical mouse position.
+         * @param[in] xoffset The horizontal mouse position.
+         * @param[in] yoffset The vertical mouse position.
+         * @param[in] camera The camera object.
          */
         void mouseMoveCallback(double xoffset, double yoffset, Camera &camera);
 
@@ -98,6 +107,7 @@ namespace vkcv {
          * @param[in] button The mouse button.
          * @param[in] action The button action.
          * @param[in] mods The modifier bits.
+         * @param[in] camera The camera object.
          */
         void mouseButtonCallback(int button, int action, int mods, Camera &camera);
 

modules/camera/src/vkcv/camera/TrackballCameraController.cpp

@@ -6,7 +6,7 @@ namespace vkcv {
 
     TrackballCameraController::TrackballCameraController() {
         m_rotationActive = false;
-        m_radius = 3.0f; // TODO: Needs to be removed. Radius should only depend on camera
+        m_radius = 3.0f;
         m_cameraSpeed = 2.5f;
         m_scrollSensitivity = 0.2f;
     }
@@ -53,7 +53,7 @@ namespace vkcv {
         glm::vec3 translate = glm::vec3(0.0f, 0.0f, m_radius);
         translate = glm::vec3(rotationX * glm::vec4(translate, 0.0f));
         glm::vec3 center = camera.getCenter();
-        glm::vec3 position = center +translate;
+        glm::vec3 position = center + translate;
         camera.setPosition(position);
         glm::vec3 up = glm::vec3(rotationX * glm::vec4(glm::vec3(0.0f, 1.0f, 0.0f), 0.0f));
         camera.setUp(up);
@@ -69,8 +69,11 @@ namespace vkcv {
         return camera.getView();
     }
 
-    void TrackballCameraController::updateRadius(double offset) {
-        setRadius(m_radius - offset * m_scrollSensitivity);
+    void TrackballCameraController::updateRadius(double offset, Camera &camera) {
+        glm::vec3 cameraPosition = camera.getPosition();
+        glm::vec3 cameraCenter = camera.getCenter();
+        float radius = glm::length(cameraCenter - cameraPosition);  // get current camera radius
+        setRadius(radius - offset * m_scrollSensitivity);
     }
 
     void TrackballCameraController::updateCamera(double deltaTime, Camera &camera) {
@@ -80,7 +83,7 @@ namespace vkcv {
     void TrackballCameraController::keyCallback(int key, int scancode, int action, int mods, Camera &camera) {}
 
     void TrackballCameraController::scrollCallback(double offsetX, double offsetY, Camera &camera) {
-        updateRadius(offsetY);
+        updateRadius(offsetY, camera);
     }
 
     void TrackballCameraController::mouseMoveCallback(double xoffset, double yoffset, Camera &camera) {