easy3d::transform Namespace Reference

Functions that generate common transformation matrices (all using the right-handed coordinate system). More...

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)
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 w, float h)
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)
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.
void	decompose (const mat4 &M, mat3 &rotation, vec3 &translation)
	Decomposes a transformation matrix without scaling (M = translation * rotation) into its original components.
bool	decompose (const mat4 &M, vec3 &scaling, quat &rotation, vec3 &translation, vec3 &skew, vec4 &perspective)
	Decomposes a transformation matrix into to its original components (i.e., scaling, rotation, translation, skew and perspective).

Detailed Description

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

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

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

Parameters

M	The input transformation matrix.
rotation	The output rotation.
translation	The output translation for the x, y, z axes

Note

This function cannot handle scaling, skew, and perspective transformation. See the overloaded function with scaling, skew, and perspective.

Todo

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

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

decompose() [2/3]

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	The input transformation matrix.
scaling	The output scaling for the x, y, z axes
rotation	The output rotation.
translation	The output translation for the x, y, z axes

Note

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

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() [3/3]

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

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

Parameters

M	The input transformation matrix.
scaling	The output scaling for the x, y, z axes.
rotation	The output rotation.
translation	The output translation for the x, y, z axes.
skew	The output skew.
perspective	The output perspective.

Returns

true if the decomposition is successful.

Todo

Not tested yet.

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/

Parameters

left	Specifies the coordinates for the left vertical clipping plane.
right	Specifies the coordinates for the right vertical clipping plane.
bottom	Specifies the coordinates for the bottom horizontal clipping plane.
top	Specifies the coordinates for the top horizontal clipping plane.
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).

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

Note

In this function, angles are expressed in radians.

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 for a given transformation matrix.

Parameters

mat	The transformation matrix.

Note

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

normal_matrix_padded()

mat43 normal_matrix_padded

(

const mat4 &

mat

)

Computes the normal matrix for a given transformation matrix.

Parameters

mat	The transformation matrix.

Note

This is the padded version suitable for uniform blocks.

See also

normal_matrix.

ortho() [1/2]

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

Creates a matrix for projecting two-dimensional coordinates onto the screen.

Parameters

left	Specify the coordinates for the left vertical clipping plane.
right	Specify the coordinates for the right vertical clipping plane.
bottom	Specify the coordinates for the bottom horizontal clipping plane.
top	Specify the coordinates for the top horizontal clipping plane.

ortho() [2/2]

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

left	Specifies the coordinates for the left vertical clipping plane.
right	Specifies the coordinates for the right vertical clipping plane.
bottom	Specifies the coordinates for the bottom horizontal clipping plane.
top	Specifies the coordinates for the top horizontal clipping plane.
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/main.cpp, and Tutorial_204_Viewer_Qt/main.cpp.

perspective() [1/2]

mat4 perspective	(	float	fov_y,
		float	width,
		float	height,
		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.
width	Specifies the width of the view.
height	Specifies the height of the view. The ratio of width to height gives the aspect ratio that defines the field of view in the x direction.
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

In this function, angles are expressed in radians.

perspective() [2/2]

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

In this function, angles are expressed in radians. See https://ksimek.github.io/2013/06/18/calibrated-cameras-and-gluperspective/

pick_matrix()

mat4 pick_matrix	(	const vec2 &	center,
		const vec2 &	delta,
		const vec4 &	viewport )

Defines a picking region.

Parameters

center	The center of the picking region.
delta	The width and height of the picking region.
viewport	The viewport.

project() [1/2]

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.
lowerleft	Specifies whether the origin is in the lower corner (true) or upper corner (false).

Note

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

Returns

The computed window coordinates.

project() [2/2]

vec3 project	(	const vec3 &	obj,
		const mat4 &	mvp,
		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.
mvp	Specifies the current model-view-projection matrix, i.e., mvp = projection * model_view.
viewport	Specifies the current viewport.
lowerleft	Specifies whether the origin is in the lower corner (true) or upper corner (false).

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() [1/2]

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.
lowerleft	Specifies whether the origin is in the lower corner (true) or upper corner (false).

Note

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

Returns

The computed object coordinates.

unproject() [2/2]

vec3 unproject	(	const vec3 &	win,
		const mat4 &	mvp,
		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.
mvp	Specifies the model-view-projection matrix, i.e., mvp = projection * model_view.
viewport	Specifies the viewport.
lowerleft	Specifies whether the origin is in the lower corner (true) or upper corner (false).

Note

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

Returns

The computed object coordinates.

viewport()

mat4 viewport	(	float	width,
		float	height )

Creates a viewport matrix. Simulating glViewport(), with the origin located at (0, 0).

Parameters

width	Specifies the width of the viewport.
height	Specifies the height of the viewport.