Issue #7: improving camera class documentation

ArcballCam.hpp

@@ -1,5 +1,5 @@
 /**
- * @file ArcballC.hpp
+ * @file ArcballCam.hpp
  * @brief Abstract Camera class
  * @author Dr. Jeffrey Paone
  *
@@ -14,33 +14,31 @@
 
 #include "Camera.hpp"
 
-/// \namespace CSCI441
-/// \desc CSCI441 Helper Functions for OpenGL
 namespace CSCI441 {
-    /// \desc concrete CSCI441::Camera implementation to implement an ArcBall camera model
+    /// A camera that implements an ArcBall camera model.
     /// \note camera direction is controlled by setting theta & phi and rotating the camera
     class ArcballCam : public CSCI441::Camera {
     public:
         explicit ArcballCam(GLfloat minRadius = 2.0f, GLfloat maxRadius = 30.0f) : _minRadius(minRadius), _maxRadius(maxRadius) {}
 
-        /// \desc converts spherical theta & phi to cartesian x,y,z direction vector
+        /// converts spherical theta & phi to cartesian x,y,z direction vector
         /// \note sets the camera's position to be on a sphere centered
         /// at the camera's look at position.  internally sets the
         /// camera's view matrix
         void recomputeOrientation() final;
 
-        /// \desc updates the camera's position by decreasing the camera's radius
+        /// updates the camera's position by decreasing the camera's radius
         /// \param movementFactor distance factor to scale the movement step
         /// \note internally sets the camera's view matrix
         void moveForward(GLfloat movementFactor) final;
 
-        /// \desc updates the camera's position by increasing the camera's radius
+        /// updates the camera's position by increasing the camera's radius
         /// \param movementFactor distance factor to scale the movement step
         /// \note internally sets the camera's view matrix
         void moveBackward(GLfloat movementFactor) final;
 
     private:
-        /// \desc updates the camera position and recalculates the view matrix
+        // updates the camera position and recalculates the view matrix
         void _updateArcballCameraViewMatrix();
 
         void _clampRadius();

Camera.hpp

@@ -19,39 +19,37 @@
 #include <glm/gtc/matrix_transform.hpp>
 
 #ifndef M_PI
-#define M_PI 3.14159265
+#define M_PI 3.14159265f
 #endif
 
-/// \namespace CSCI441
-/// \desc CSCI441 Helper Functions for OpenGL
 namespace CSCI441 {
 
-    /// \desc Abstract Class to represent a synthetic camera.  The following methods
+    /// Abstract Class to represent a synthetic camera.  The following methods
     /// must be overridden:<br>
     ///  - recomputeOrientation()<br>
     ///  - moveForward()<br>
     ///  - moveBackward()<br>
     class Camera {
     public:
-        /// \desc properly destroy concrete children
+        /// properly destroy concrete children
         virtual ~Camera() = default;
 
-        /// \desc Uses theta, phi, & radius to update the
+        /// Uses theta, phi, & radius to update the
         /// camera's view matrix parameters.
         /// The camera orientation is controlled via spherical coordinates
         /// and this method would orient and/or position the camera in
         /// cartesian coordinates.
         virtual void recomputeOrientation() = 0;
 
-        /// \desc steps forward along the camera's view
+        /// steps forward along the camera's view
         /// \param movementFactor scaling factor for distance to move
         virtual void moveForward(GLfloat movementFactor) = 0;
 
-        /// \desc steps backward along the camera's view
+        /// steps backward along the camera's view
         /// \param movementFactor scaling factor for distance to move
         virtual void moveBackward(GLfloat movementFactor) = 0;
 
-        /// \desc rotates the camera's POV by adding to theta & phi
+        /// rotates the camera's POV by adding to theta & phi
         /// then ensuring phi stays within the (0, pi) range and finally
         /// calls through to recomputeOrientation() to update the view
         /// parameters after the rotation
@@ -62,65 +60,65 @@ namespace CSCI441 {
         /// and rotation can then be disabled.
         virtual void rotate(GLfloat dTheta, GLfloat dPhi);
 
-        /// \desc creates the View Matrix based on the position, lookAt point, and up vector
+        /// creates the View Matrix based on the position, lookAt point, and up vector
         void computeViewMatrix() { _viewMatrix = glm::lookAt( _position, _lookAtPoint, _upVector ); }
 
-        /// \desc returns the current view matrix
+        /// returns the current view matrix
         [[nodiscard]] glm::mat4 getViewMatrix() { return _viewMatrix; }
-        /// \desc returns the current camera position in world space
+        /// returns the current camera position in world space
         [[nodiscard]] glm::vec3 getPosition() const { return _position; }
-        /// \desc returns the current lookAt point in world space
+        /// returns the current lookAt point in world space
         [[nodiscard]] glm::vec3 getLookAtPoint() const { return _lookAtPoint; }
-        /// \desc returns the current up vector in world space
+        /// returns the current up vector in world space
         [[nodiscard]] glm::vec3 getUpVector() const { return _upVector; }
-        /// \desc returns the current theta value in radians
+        /// returns the current theta value in radians
         [[nodiscard]] GLfloat getTheta() const { return _theta; }
-        /// \desc returns the current phi value in radians
+        /// returns the current phi value in radians
         [[nodiscard]] GLfloat getPhi() const { return _phi; }
 
-        /// \desc sets the camera's position in world space
+        /// sets the camera's position in world space
         /// \param pos the new camera world space position
         void setPosition( glm::vec3 pos ) { _position = pos; }
-        /// \desc sets the camera's lookAt point in world space
+        /// sets the camera's lookAt point in world space
         /// \param lookAt the new camera world space lookAt point
         void setLookAtPoint( glm::vec3 lookAt ) { _lookAtPoint = lookAt; }
-        /// \desc sets the camera's up vector in world space
+        /// sets the camera's up vector in world space
         /// \param up the new camera world space up vector
         void setUpVector( glm::vec3 up ) { _upVector = up; }
-        /// \desc sets the camera's theta angle in radians
+        /// sets the camera's theta angle in radians
         /// \param t the new camera theta angle in radians
         void setTheta( GLfloat t ) { _theta = t; }
-        /// \desc sets the camera's phi angle in radians
+        /// sets the camera's phi angle in radians
         /// \param p the new camera phi angle in radians
         void setPhi( GLfloat p ) { _phi = p; }
-        /// \desc sets the camera's radius
+        /// sets the camera's radius
         /// \param r the new camera radius
         void setRadius( GLfloat r ) { _radius = r; }
 
     protected:
         Camera();
 
-        /// \desc stores the View Matrix corresponding to the inverse of the Camera's Matrix
+        /// stores the View Matrix corresponding to the inverse of the Camera's Matrix
         glm::mat4 _viewMatrix;
 
-        /// \desc the cartesian position in world space of the camera
+        /// the cartesian position in world space of the camera
         glm::vec3 _position;
-        /// \desc the cartesian direction the camera is facing in world space
+        /// the cartesian direction the camera is facing in world space
         glm::vec3 _direction;
-        /// \desc the world space point in front of the camera
+        /// the world space point in front of the camera
         glm::vec3 _lookAtPoint;
-        /// \desc the up vector of the camera specified in world space
+        /// the up vector of the camera specified in world space
         glm::vec3 _upVector;
 
-        /// \desc spherical angle for yaw direction in radians
+        /// spherical angle for yaw direction in radians
         GLfloat _theta;
-        /// \desc spherical angle for pitch direction in radians
+        /// spherical angle for pitch direction in radians
         GLfloat _phi;
-        /// \desc spherical magnitude for direction in world space
+        /// spherical magnitude for direction in world space
         GLfloat _radius;
 
     private:
-        /// \desc keeps phi within the range (0, pi) to prevent the camera from flipping over
+        // keeps phi within the range (0, pi) to prevent the camera from flipping over
         void _clampPhi();
     };
 }

FixedCam.hpp

@@ -15,14 +15,18 @@
 #include <CSCI441/Camera.hpp>
 
 namespace CSCI441 {
-    /// \desc A camera that can be positioned and oriented but never moved or
-    /// rotated.
+    /// A camera that can be positioned and oriented but never moved or rotated.
     /// \note Must position via setPosition()
     /// \note Must orient via setLookAtPoint()
     class FixedCam : public CSCI441::Camera {
     public:
+        /// does nothing
         void recomputeOrientation() final;
+        /// does nothing
+        /// \param unused does nothing
         void moveForward(GLfloat unused) final;
+        /// does nothing
+        /// \param unused does nothing
         void moveBackward(GLfloat unused) final;
     };
 }

FreeCam.hpp

@@ -14,34 +14,32 @@
 
 #include "Camera.hpp"
 
-/// \namespace CSCI441
-/// \desc CSCI441 Helper Functions for OpenGL
 namespace CSCI441 {
-    /// \desc concrete CSCI441::Camera implementation to implement a FreeCam camera model
+    /// A camera that implements a FreeCam camera model.
     /// \note camera direction is controlled by setting theta & phi and rotating the camera
     class FreeCam : public CSCI441::Camera {
     public:
-        /// \desc converts spherical theta & phi to cartesian x,y,z direction vector
+        /// converts spherical theta & phi to cartesian x,y,z direction vector
         /// \note sets the camera's direction vector to point outward from a sphere centered
         /// at the camera's position and updates the camera's look at point to be a point
         /// on the sphere offset from the camera's position.  internally sets the
         /// camera's view matrix
         void recomputeOrientation() final;
 
-        /// \desc updates the camera's position by the adding the camera's direction to the
+        /// updates the camera's position by the adding the camera's direction to the
         /// camera's position
         /// \param movementFactor distance factor to scale the movement step
         /// \note internally sets the camera's view matrix
         void moveForward(GLfloat movementFactor) final;
 
-        /// \desc updates the camera's position by the adding the camera's negative direction to the
+        /// updates the camera's position by the adding the camera's negative direction to the
         /// camera's position
         /// \param movementFactor distance factor to scale the movement step
         /// \note internally sets the camera's view matrix
         void moveBackward(GLfloat movementFactor) final;
 
     private:
-        /// \desc updates the look at point and recalculates the view matrix
+        // updates the look at point and recalculates the view matrix
         void _updateFreeCameraViewMatrix();
     };
 }

docs/_arcball_cam_8hpp.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen 1.9.6"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>CSCI441 OpenGL Library: ArcballCam.hpp File Reference</title>
+<link href="tabs.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="jquery.js"></script>
+<script type="text/javascript" src="dynsections.js"></script>
+<link href="search/search.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="search/searchdata.js"></script>
+<script type="text/javascript" src="search/search.js"></script>
+<link href="doxygen.css" rel="stylesheet" type="text/css" />
+</head>
+<body>
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <td id="projectalign">
+   <div id="projectname">CSCI441 OpenGL Library<span id="projectnumber">&#160;3.12.1</span>
+   </div>
+   <div id="projectbrief">CS@Mines CSCI441 Computer Graphics Course Library</div>
+  </td>
+ </tr>
+ </tbody>
+</table>
+</div>
+<!-- end header part -->
+<!-- Generated by Doxygen 1.9.6 -->
+<script type="text/javascript">
+/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
+var searchBox = new SearchBox("searchBox", "search/",'.html');
+/* @license-end */
+</script>
+<script type="text/javascript" src="menudata.js"></script>
+<script type="text/javascript" src="menu.js"></script>
+<script type="text/javascript">
+/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
+$(function() {
+  initMenu('',true,false,'search.php','Search');
+  $(document).ready(function() { init_search(); });
+});
+/* @license-end */
+</script>
+<div id="main-nav"></div>
+<!-- window showing the filter options -->
+<div id="MSearchSelectWindow"
+     onmouseover="return searchBox.OnSearchSelectShow()"
+     onmouseout="return searchBox.OnSearchSelectHide()"
+     onkeydown="return searchBox.OnSearchSelectKey(event)">
+</div>
+
+<!-- iframe showing the search results (closed by default) -->
+<div id="MSearchResultsWindow">
+<div id="MSearchResults">
+<div class="SRPage">
+<div id="SRIndex">
+<div id="SRResults"></div>
+<div class="SRStatus" id="Loading">Loading...</div>
+<div class="SRStatus" id="Searching">Searching...</div>
+<div class="SRStatus" id="NoMatches">No Matches</div>
+</div>
+</div>
+</div>
+</div>
+
+</div><!-- top -->
+<div class="header">
+  <div class="summary">
+<a href="#nested-classes">Classes</a> &#124;
+<a href="#namespaces">Namespaces</a>  </div>
+  <div class="headertitle"><div class="title">ArcballCam.hpp File Reference</div></div>
+</div><!--header-->
+<div class="contents">
+
+<p>Abstract Camera class.  
+<a href="#details">More...</a></p>
+<div class="textblock"><code>#include &quot;<a class="el" href="_camera_8hpp_source.html">Camera.hpp</a>&quot;</code><br />
+</div>
+<p><a href="_arcball_cam_8hpp_source.html">Go to the source code of this file.</a></p>
+<table class="memberdecls">
+<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
+Classes</h2></td></tr>
+<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_c_s_c_i441_1_1_arcball_cam.html">CSCI441::ArcballCam</a></td></tr>
+<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
+</table><table class="memberdecls">
+<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="namespaces" name="namespaces"></a>
+Namespaces</h2></td></tr>
+<tr class="memitem:namespace_c_s_c_i441"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespace_c_s_c_i441.html">CSCI441</a></td></tr>
+<tr class="memdesc:namespace_c_s_c_i441"><td class="mdescLeft">&#160;</td><td class="mdescRight"><a class="el" href="namespace_c_s_c_i441.html" title="CSCI441 Helper Functions for OpenGL.">CSCI441</a> Helper Functions for OpenGL. <br /></td></tr>
+<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
+</table>
+<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
+<div class="textblock"><p>Abstract Camera class. </p>
+<dl class="section author"><dt>Author</dt><dd>Dr. Jeffrey Paone</dd></dl>
+<dl class="section copyright"><dt>Copyright</dt><dd>MIT License Copyright (c) 2021 Dr. Jeffrey Paone</dd></dl>
+<p>These functions, classes, and constants help minimize common code that needs to be written. </p>
+</div></div><!-- contents -->
+<!-- start footer part -->
+<hr class="footer"/><address class="footer"><small>
+Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6
+</small></address>
+</body>
+</html>