Skip to content

Commit

Permalink
documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@LiangliangNan
LiangliangNan committed Nov 2, 2023
1 parent 9ef628b commit d0e544a
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 46 deletions.
2 changes: 1 addition & 1 deletion easy3d/core/line.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
7 changes: 4 additions & 3 deletions easy3d/renderer/transform.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));
}

Expand All @@ -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;
}

Expand Down
82 changes: 40 additions & 42 deletions easy3d/renderer/transform.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,99 +31,97 @@
#include <easy3d/core/types.h>


// 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
Expand Down

0 comments on commit d0e544a

Please sign in to comment.