From d0e544af35b0cddaea9c6572f00b5b42dfca4c99 Mon Sep 17 00:00:00 2001 From: Liangliang Nan Date: Thu, 2 Nov 2023 09:37:12 +0100 Subject: [PATCH] documentation --- easy3d/core/line.h | 2 +- easy3d/renderer/transform.cpp | 7 +-- easy3d/renderer/transform.h | 82 +++++++++++++++++------------------ 3 files changed, 45 insertions(+), 46 deletions(-) diff --git a/easy3d/core/line.h b/easy3d/core/line.h index 505403f9..e259e115 100644 --- a/easy3d/core/line.h +++ b/easy3d/core/line.h @@ -76,7 +76,7 @@ namespace easy3d { /// \param p2 The perpendicular foot on the other line. /// \return true if the perpendicular foots exist, and false if the two lines are parallel. /// \note This function is for 3D only. - bool foots(const thisclass& another, Point& p1, Point& p2) const; + bool foots(const thisclass& other, Point& p1, Point& p2) const; private: // Ambiguities exist for this one. GenericLine(const Point & p, const Vector & dir); diff --git a/easy3d/renderer/transform.cpp b/easy3d/renderer/transform.cpp index 022eceb2..9b1d4abc 100644 --- a/easy3d/renderer/transform.cpp +++ b/easy3d/renderer/transform.cpp @@ -221,7 +221,8 @@ namespace easy3d { } mat3 normal_matrix(const mat4& mat) { - mat3 submv(mat); + // use the 3x3 sub-matrix to extract the rotation matrix (note: the translation has to be excluded) + mat3 submv(mat); return transpose(inverse(submv)); } @@ -231,9 +232,9 @@ namespace easy3d { result(0, 0) = N(0, 0); result(0, 1) = N(0, 1); result(0, 2) = N(0, 2); result(1, 0) = N(1, 0); result(1, 1) = N(1, 1); result(1, 2) = N(1, 2); result(2, 0) = N(2, 0); result(2, 1) = N(2, 1); result(2, 2) = N(2, 2); - // Set the last row to be zeros because of the column major storage. Otherwise + // Set the last row to zeros because of the column major storage. Otherwise // you need to set the last column to be zeros). - result(3, 0) = 0; result(3, 1) = 0; result(3, 2) = 0; + result(3, 0) = 0; result(3, 1) = 0; result(3, 2) = 0; return result; } diff --git a/easy3d/renderer/transform.h b/easy3d/renderer/transform.h index 73160666..c4e8142c 100644 --- a/easy3d/renderer/transform.h +++ b/easy3d/renderer/transform.h @@ -31,99 +31,97 @@ #include -// Defines functions that generate common transformation matrices. -// NOTE: using right-handed coordinate system. +// Defines functions that generate common transformation matrices (all using the right-handed coordinate system). // -// The matrices generated by this extension use standard OpenGL fixed-function -// conventions. For example, the lookAt function generates a transform from world -// space into the specific eye space that the projective matrix functions -// (perspective, ortho, etc.) are designed to expect. The OpenGL compatibility +// The matrices generated by this extension use standard OpenGL fixed-function conventions. +// For example, the lookAt function generates a transform from world space into the specific eye space that +// the projective matrix functions (perspective, ortho, etc.) are designed to expect. The OpenGL compatibility // specifications defines the particular layout of this eye space. namespace easy3d { namespace transform { - // Creates a matrix for an orthographic parallel viewing volume. Simulating glFrustum() - // near: Specifies the distance from the viewer to the near clipping plane (always positive). - // far: Specifies the distance from the viewer to the far clipping plane (always positive). - // see http://www.songho.ca/opengl/gl_projectionmatrix.html + // Creates a matrix for an orthographic parallel viewing volume. Simulating glFrustum(). + // \param near Specifies the distance from the viewer to the near clipping plane (always positive). + // \param far Specifies the distance from the viewer to the far clipping plane (always positive). + // See http://www.songho.ca/opengl/gl_projectionmatrix.html // https://ksimek.github.io/2013/06/03/calibrated_cameras_in_opengl/ mat4 ortho(float left, float right, float bottom, float top, float near, float far); // Creates a matrix for projecting two-dimensional coordinates onto the screen. mat4 ortho(float left, float right, float bottom, float top); - // Creates a frustum perspective matrix. Simulating glFrustum() - // see. http://www.songho.ca/opengl/gl_projectionmatrix.html + // Creates a frustum perspective matrix. Simulating glFrustum(). + // See. http://www.songho.ca/opengl/gl_projectionmatrix.html // https://ksimek.github.io/2013/06/03/calibrated_cameras_in_opengl/ mat4 frustum(float left, float right, float bottom, float top, float near, float far); // Creates a matrix for a right-handed symmetric perspective-view frustum. Simulating gluPerspective(). - // fov_y: Specifies the field of view angle, in the y direction. Expressed in radians. - // aspect: Specifies the aspect ratio that determines the field of view in the x direction. The + // \param fov_y Specifies the field of view angle, in the y direction. Expressed in radians. + // \param aspect Specifies the aspect ratio that determines the field of view in the x direction. The // aspect ratio is the ratio of x (width) to y (height). - // near: Specifies the distance from the viewer to the near clipping plane (always positive). - // far: Specifies the distance from the viewer to the far clipping plane (always positive). - // NOTE: Degrees are an unhandy unit to work with. Thus, I use radians for everything! - // see https://ksimek.github.io/2013/06/18/calibrated-cameras-and-gluperspective/ + // \param near Specifies the distance from the viewer to the near clipping plane (always positive). + // \param far Specifies the distance from the viewer to the far clipping plane (always positive). + // \note Degrees are an unhandy unit to work with. Thus, I use radians for everything! + // See https://ksimek.github.io/2013/06/18/calibrated-cameras-and-gluperspective/ mat4 perspective(float fov_y, float aspect, float near, float far); mat4 perspective(float fov_y, float width, float height, float near, float far); // Creates a matrix for a symmetric perspective-view frustum with far plane at infinite. - // fov_y: Specifies the field of view angle, in the y direction. Expressed in radians. - // aspect: Specifies the aspect ratio that determines the field of view in the x direction. The + // \param fov_y Specifies the field of view angle, in the y direction. Expressed in radians. + // \param aspect Specifies the aspect ratio that determines the field of view in the x direction. The // aspect ratio is the ratio of x (width) to y (height). - // near: Specifies the distance from the viewer to the near clipping plane (always positive). + // \param near Specifies the distance from the viewer to the near clipping plane (always positive). mat4 infinite_perspective(float fov_y, float aspect, float near); // Creates a viewport matrix. Simulating glViewport(). mat4 viewport(float width, float height); - // Build a look at view matrix. Simulating gluLookAt() - // eye: Position of the camera - // center: Position where the camera is looking at - // up: Normalized up vector, how the camera is oriented. Typically (0, 0, 1) + // Builds a look at view matrix simulating gluLookAt(). + // \param eye Position of the camera. + // \param center Position where the camera is looking at. + // \param up Normalized up vector determining how the camera is oriented. Typically (0, 0, 1). mat4 look_at(const vec3& eye, const vec3& center, const vec3& up); - // Define a picking region + // Defines a picking region mat4 pick_matrix(const vec2& center, const vec2& delta, const vec4& viewport); - // Map the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates. Simulating gluProject() - // obj: Specify the object coordinates. - // model: Specifies the current model-view matrix - // proj: Specifies the current projection matrix - // viewport: Specifies the current viewport + // Maps the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates. Simulating gluProject(). + // \param obj Specifies the object coordinates. + // \param model Specifies the current model-view matrix. + // \param proj Specifies the current projection matrix. + // \param viewport Specifies the current viewport. // viewport[0] = 0; // viewport[1] = 0; // viewport[2] = screenWidth(); // viewport[3] = screenHeight(); - // OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner - // Return the computed window coordinates. + // \note OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner. + // \return The computed window coordinates. vec3 project(const vec3& obj, const mat4& model, const mat4& proj, const int viewport[4], bool lowerleft = true); vec3 project(const vec3& obj, const mat4& mvp, const int viewport[4], bool lowerleft = true); // mvp = proj * model; - // Map the specified window coordinates (win.x, win.y, win.z) into object coordinates. Simulating gluUnProject() - // win: Specify the window coordinates to be mapped. - // model: Specifies the model-view matrix - // proj: Specifies the projection matrix - // viewport: Specifies the viewport + // Maps the specified window coordinates (win.x, win.y, win.z) into object coordinates. Simulating gluUnProject(). + // \param win Specifies the window coordinates to be mapped. + // \param model Specifies the model-view matrix. + // \param proj Specifies the projection matrix. + // \param viewport Specifies the viewport. // viewport[0] = 0; // viewport[1] = 0; // viewport[2] = screenWidth(); // viewport[3] = screenHeight(); - // OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner - // Returns the computed object coordinates. + // \note OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner. + // \return The computed object coordinates. vec3 unproject(const vec3& win, const mat4& model, const mat4& proj, const int viewport[4], bool lowerleft = true); vec3 unproject(const vec3& win, const mat4& mvp, const int viewport[4], bool lowerleft = true); // mvp = proj * model; // -------------------------------------------------------------------------------------------------- // Computes the normal matrix based on mat. - // NOTE: this is NOT padded. Use the padded version in uniform blocks. + // \note The returned matrix is NOT padded. Use the padded version for uniform blocks. mat3 normal_matrix(const mat4& mat); // Computes the normal matrix based on mat. - // NOTE: this is the padded version suitable in uniform blocks. + // \note This is the padded version suitable for uniform blocks. mat43 normal_matrix_padded(const mat4& mat); } // namespace transform