easy3d::transform Namespace Reference

Functions
mat4	ortho (float left, float right, float bottom, float top, float zNear, float zFar)
mat4	ortho (float left, float right, float bottom, float top)
	Creates a matrix for projecting two-dimensional coordinates onto the screen.
mat4	frustum (float left, float right, float bottom, float top, float nearVal, float farVal)
mat4	perspective (float fov_y, float aspect, float zNear, float zFar)
mat4	perspective (float fov, float width, float height, float zNear, float zFar)
mat4	infinite_perspective (float fov_y, float aspect, float zNear)
mat4	viewport (float width, float height)
	Creates a viewport matrix. Simulating glViewport().
vec3	project (const vec3 &obj, const mat4 &mv, const mat4 &proj, const int viewport[4], bool lowerleft)
vec3	project (const vec3 &obj, const mat4 &mvp, const int viewport[4], bool lowerleft)
vec3	unproject (const vec3 &win, const mat4 &mv, const mat4 &proj, const int viewport[4], bool lowerleft)
vec3	unproject (const vec3 &win, const mat4 &mvp, const int viewport[4], bool lowerleft)
mat4	look_at (const vec3 &eye, const vec3 &center, const vec3 &up)
mat4	pick_matrix (const vec2 &center, const vec2 &delta, const vec4 &viewport)
	Defines a picking region.
mat3	normal_matrix (const mat4 &mat)
mat43	normal_matrix_padded (const mat4 &mat)
void	decompose (const mat4 &M, vec3 &scaling, mat3 &rotation, vec3 &translation)
	Decomposes a transformation matrix (M = translation * rotation * scaling) into its original components. More...
void	decompose (const mat4 &M, vec3 &scaling, quat &rotation, vec3 &translation)
void	decompose_no_scaling (const mat4 &M, mat3 &rotation, vec3 &translation)
	Decomposes a transformation matrix without scaling (M = translation * rotation) into its original components. More...
void	decompose_no_scaling (const mat4 &M, quat &rotation, vec3 &translation)
bool	decompose (const mat4 &M, vec3 &scaling, quat &rotation, vec3 &translation, vec3 &skew, vec4 &persp)
	Decomposes a transformation matrix into to its original components (i.e., scaling, rotation, translation, skew and perspective). More...

Detailed Description

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 specifications defines the particular layout of this eye space.

Function Documentation

decompose() [1/2]

void decompose	(	const mat4 &	M,
		vec3 &	scaling,
		mat3 &	rotation,
		vec3 &	translation
	)

Decomposes a transformation matrix (M = translation * rotation * scaling) into its original components.

Parameters

M	is the input transformation matrix
scaling	receives the output scaling for the x, y, z axes
rotation	receives the output rotation
translation	receives the output translation for the x, y, z axes

Note

This function cannot handle skew and perspective transformation. See the overloaded function below.

Todo:

Add functions that extract single components, i.e.,

• Quat extract_rotation(const mat4& M);
• vec3 extract_scale(const mat4& M);
• vec3 extract_translation(const mat4& M);

decompose() [2/2]

bool decompose	(	const mat4 &	M,
		vec3 &	scaling,
		quat &	rotation,
		vec3 &	translation,
		vec3 &	skew,
		vec4 &	persp
	)

Decomposes a transformation matrix into to its original components (i.e., scaling, rotation, translation, skew and perspective).

Todo:

Not tested yet.

decompose_no_scaling()

void decompose_no_scaling	(	const mat4 &	M,
		mat3 &	rotation,
		vec3 &	translation
	)

Decomposes a transformation matrix without scaling (M = translation * rotation) into its original components.

Parameters

rotation	receives the output rotation
translation	receives the output translation for the x, y, z axes

Note

This function cannot handle rotation, skew, and perspective transformation. See the overloaded function below.

Todo:

Add functions that extract single components, i.e.,

• Quat extract_rotation(const mat4& M);
• vec3 extract_translation(const mat4& M);

frustum()

mat4 frustum	(	float	left,
		float	right,
		float	bottom,
		float	top,
		float	near,
		float	far
	)

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/

infinite_perspective()

mat4 infinite_perspective	(	float	fov_y,
		float	aspect,
		float	near
	)

Creates a matrix for a symmetric perspective-view frustum with far plane at infinite.

Parameters

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 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).

look_at()

mat4 look_at	(	const vec3 &	eye,
		const vec3 &	center,
		const vec3 &	up
	)

Builds a look at view matrix simulating gluLookAt().

Parameters

eye	Position of the camera.
center	Position where the camera is looking at.
up	Normalized up vector determining how the camera is oriented. Typically (0, 0, 1).

normal_matrix()

mat3 normal_matrix

(

const mat4 &

mat

)

Computes the normal matrix based on mat.

Note

The returned matrix is NOT padded. Use the padded version for uniform blocks.

normal_matrix_padded()

mat43 normal_matrix_padded

(

const mat4 &

mat

)

Computes the normal matrix based on mat.

Note

This is the padded version suitable for uniform blocks.

ortho()

mat4 ortho	(	float	left,
		float	right,
		float	bottom,
		float	top,
		float	near,
		float	far
	)

Creates a matrix for an orthographic parallel viewing volume. Simulating glFrustum().

Parameters

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 https://ksimek.github.io/2013/06/03/calibrated_cameras_in_opengl/

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

perspective()

mat4 perspective	(	float	fov_y,
		float	aspect,
		float	near,
		float	far
	)

Creates a matrix for a right-handed symmetric perspective-view frustum. Simulating gluPerspective().

Parameters

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

project()

vec3 project	(	const vec3 &	obj,
		const mat4 &	model,
		const mat4 &	proj,
		const int	viewport[4],
		bool	lowerleft = true
	)

Maps the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates. Simulating gluProject().

Parameters

obj	Specifies the object coordinates.
model	Specifies the current model-view matrix.
proj	Specifies the current projection matrix.
viewport	Specifies the current viewport. viewport[0] = 0; viewport[1] = 0; viewport[2] = screenWidth(); viewport[3] = screenHeight();

Note

OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner.

Returns

The computed window coordinates.

unproject()

vec3 unproject	(	const vec3 &	win,
		const mat4 &	model,
		const mat4 &	proj,
		const int	viewport[4],
		bool	lowerleft = true
	)

Maps the specified window coordinates (win.x, win.y, win.z) into object coordinates. Simulating gluUnProject().

Parameters

win	Specifies the window coordinates to be mapped.
model	Specifies the model-view matrix.
proj	Specifies the projection matrix.
viewport	Specifies the viewport. viewport[0] = 0; viewport[1] = 0; viewport[2] = screenWidth(); viewport[3] = screenHeight();

Note

OpenGL uses the lower corner for its origin while other software (e.g., Qt) may use upper corner.

Returns

The computed object coordinates.