Cogl.MatrixStack¶

Subclasses:: None

Methods¶

Inherited:: Cogl.Object (2)

class	`new` (ctx)
	`frustum` (left, right, bottom, top, z_near, z_far)
	`get` ()
	`get_entry` ()
	`get_inverse` ()
	`load_identity` ()
	`multiply` (matrix)
	`orthographic` (x_1, y_1, x_2, y_2, near, far)
	`perspective` (fov_y, aspect, z_near, z_far)
	`pop` ()
	`push` ()
	`rotate` (angle, x, y, z)
	`rotate_euler` (euler)
	`rotate_quaternion` (quaternion)
	`scale` (x, y, z)
	`set` (matrix)
	`translate` (x, y, z)

Virtual Methods¶

None

Fields¶

None

Class Details¶

class Cogl.MatrixStack¶

Bases:: Cogl.Object
Abstract:: No

Tracks your current position within a hierarchy and lets you build up a graph of transformations as you traverse through a hierarchy such as a scenegraph.

A Cogl.MatrixStack always maintains a reference to a single transformation at any point in time, representing the transformation at the current position in the hierarchy. You can get a reference to the current transformation by calling Cogl.MatrixStack.get_entry().

When a Cogl.MatrixStack is first created with Cogl.MatrixStack.new() then it is conceptually positioned at the root of your hierarchy and the current transformation simply represents an identity transformation.

As you traverse your object hierarchy (your scenegraph) then you should call Cogl.MatrixStack.push() whenever you move down one level and call Cogl.MatrixStack.pop() whenever you move back up one level towards the root.

At any time you can apply a set of operations, such as “rotate”, “scale”, “translate” on top of the current transformation of a Cogl.MatrixStack using functions such as Cogl.MatrixStack.rotate(), Cogl.MatrixStack.scale() and Cogl.MatrixStack.translate(). These operations will derive a new current transformation and will never affect a transformation that you have referenced using Cogl.MatrixStack.get_entry().

Internally applying operations to a Cogl.MatrixStack builds up a graph of Cogl.MatrixEntry structures which each represent a single immutable transform.

classmethod new(ctx)¶

Parameters:: ctx (Cogl.Context) – A Cogl.Context
Returns:: A newly allocated Cogl.MatrixStack
Return type:: Cogl.MatrixStack

Allocates a new Cogl.MatrixStack that can be used to build up transformations relating to objects in a scenegraph like hierarchy. (See the description of Cogl.MatrixStack and Cogl.MatrixEntry for more details of what a matrix stack is best suited for)

When a Cogl.MatrixStack is first allocated it is conceptually positioned at the root of your scenegraph hierarchy. As you traverse your scenegraph then you should call Cogl.MatrixStack.push() whenever you move down a level and Cogl.MatrixStack.pop() whenever you move back up a level towards the root.

Once you have allocated a Cogl.MatrixStack you can get a reference to the current transformation for the current position in the hierarchy by calling Cogl.MatrixStack.get_entry().

Once you have allocated a Cogl.MatrixStack you can apply operations such as rotate, scale and translate to modify the current transform for the current position in the hierarchy by calling Cogl.MatrixStack.rotate(), Cogl.MatrixStack.scale() and Cogl.MatrixStack.translate().

frustum(left, right, bottom, top, z_near, z_far)¶

Parameters:

left (float) – X position of the left clipping plane where it intersects the near clipping plane
right (float) – X position of the right clipping plane where it intersects the near clipping plane
bottom (float) – Y position of the bottom clipping plane where it intersects the near clipping plane
top (float) – Y position of the top clipping plane where it intersects the near clipping plane
z_near (float) – The distance to the near clipping plane (Must be positive)
z_far (float) – The distance to the far clipping plane (Must be positive)

Replaces the current matrix with a perspective matrix for a given viewing frustum defined by 4 side clip planes that all cross through the origin and 2 near and far clip planes.

get()¶

Returns:

A direct pointer to the current transform or None and in that case matrix will be initialized with the value of the current transform.

matrix:: The potential destination for the current matrix

Return type:

(Cogl.Matrix, matrix: Cogl.Matrix)

Resolves the current self transform into a Cogl.Matrix by combining the operations that have been applied to build up the current transform.

There are two possible ways that this function may return its result depending on whether the stack is able to directly point to an internal Cogl.Matrix or whether the result needs to be composed of multiple operations.

If an internal matrix contains the required result then this function will directly return a pointer to that matrix, otherwise if the function returns None then matrix will be initialized to match the current transform of self.

matrix will be left untouched if a direct pointer is returned.

get_entry()¶

Returns:: A pointer to the Cogl.MatrixEntry representing the current matrix stack transform.
Return type:: Cogl.MatrixEntry

Gets a reference to the current transform represented by a Cogl.MatrixEntry pointer.

The transform represented by a Cogl.MatrixEntry is immutable. Cogl.MatrixEntry s are reference counted using Cogl.MatrixEntry.ref() and Cogl.MatrixEntry.unref() and you should call Cogl.MatrixEntry.unref() when you are finished with and entry you get via Cogl.MatrixStack.get_entry().

get_inverse()¶

Returns:

True if the inverse was successfully calculated or False for degenerate transformations that can’t be inverted (in this case the inverse matrix will simply be initialized with the identity matrix)

inverse:: The destination for a 4x4 inverse transformation matrix

Return type:

(int, inverse: Cogl.Matrix)

Gets the inverse transform of the current matrix and uses it to initialize a new Cogl.Matrix.

load_identity()¶: Resets the current matrix to the identity matrix.

multiply(matrix)¶

Parameters:: matrix (Cogl.Matrix) – the matrix to multiply with the current model-view

Multiplies the current matrix by the given matrix.

orthographic(x_1, y_1, x_2, y_2, near, far)¶

Parameters:

x_1 (float) – The x coordinate for the first vertical clipping plane
y_1 (float) – The y coordinate for the first horizontal clipping plane
x_2 (float) – The x coordinate for the second vertical clipping plane
y_2 (float) – The y coordinate for the second horizontal clipping plane
near (float) – The distance to the near clipping plane (will be negative if the plane is behind the viewer)
far (float) – The distance to the far clipping plane (will be negative if the plane is behind the viewer)

Replaces the current matrix with an orthographic projection matrix.

perspective(fov_y, aspect, z_near, z_far)¶

Parameters:

fov_y (float) – Vertical field of view angle in degrees.
aspect (float) – The (width over height) aspect ratio for display
z_near (float) – The distance to the near clipping plane (Must be positive, and must not be 0)
z_far (float) – The distance to the far clipping plane (Must be positive)

Replaces the current matrix with a perspective matrix based on the provided values.

You should be careful not to have too great a z_far / z_near ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

pop()¶

Restores the previous transform that was last saved by calling Cogl.MatrixStack.push().

This is usually called while traversing a scenegraph whenever you return up one level in the graph towards the root node.

push()¶

Saves the current transform and starts a new transform that derives from the current transform.

This is usually called while traversing a scenegraph whenever you traverse one level deeper. Cogl.MatrixStack.pop() can then be called when going back up one layer to restore the previous transform of an ancestor.

rotate(angle, x, y, z)¶

Parameters:

angle (float) – Angle in degrees to rotate.
x (float) – X-component of vertex to rotate around.
y (float) – Y-component of vertex to rotate around.
z (float) – Z-component of vertex to rotate around.

Multiplies the current matrix by one that rotates the around the axis-vector specified by x, y and z. The rotation follows the right-hand thumb rule so for example rotating by 10 degrees about the axis-vector (0, 0, 1) causes a small counter-clockwise rotation.

rotate_euler(euler)¶

Parameters:: euler (Cogl.Euler) – A Cogl.Euler

Multiplies the current matrix by one that rotates according to the rotation described by euler.

rotate_quaternion(quaternion)¶

Parameters:: quaternion (Cogl.Quaternion) – A Cogl.Quaternion

Multiplies the current matrix by one that rotates according to the rotation described by quaternion.

scale(x, y, z)¶

Parameters:

x (float) – Amount to scale along the x-axis
y (float) – Amount to scale along the y-axis
z (float) – Amount to scale along the z-axis

Multiplies the current matrix by one that scales the x, y and z axes by the given values.

set(matrix)¶

Parameters:: matrix (Cogl.Matrix) – A Cogl.Matrix replace the current matrix value with

Replaces the current self matrix value with the value of matrix. This effectively discards any other operations that were applied since the last time Cogl.MatrixStack.push() was called or since the stack was initialized.

translate(x, y, z)¶

Parameters:

x (float) – Distance to translate along the x-axis
y (float) – Distance to translate along the y-axis
z (float) – Distance to translate along the z-axis

Multiplies the current matrix by one that translates along all three axes according to the given values.