Cogl.MatrixEntry¶

Fields¶

None

Methods¶

	`calculate_translation` (entry1)
	`equal` (entry1)
	`get` ()
	`is_identity` ()
	`ref` ()
	`unref` ()

Details¶

class Cogl.MatrixEntry¶

Represents a single immutable transformation that was retrieved from a Cogl.MatrixStack using Cogl.MatrixStack.get_entry().

Internally a Cogl.MatrixEntry represents a single matrix operation (such as “rotate”, “scale”, “translate”) which is applied to the transform of a single parent entry.

Using the Cogl.MatrixStack api effectively builds up a graph of these immutable Cogl.MatrixEntry structures whereby operations that can be shared between multiple transformations will result in shared Cogl.MatrixEntry nodes in the graph.

When a Cogl.MatrixStack is first created it references one Cogl.MatrixEntry that represents a single “load identity” operation. This serves as the root entry and all operations that are then applied to the stack will extend the graph starting from this root “load identity” entry.

Given the typical usage model for a Cogl.MatrixStack and the way the entries are built up while traversing a scenegraph then in most cases where an application is interested in comparing two transformations for equality then it is enough to simply compare two Cogl.MatrixEntry pointers directly. Technically this can lead to false negatives that could be identified with a deeper comparison but often these false negatives are unlikely and don’t matter anyway so this enables extremely cheap comparisons.

Cogl.MatrixEntry s are reference counted using Cogl.MatrixEntry.ref() and Cogl.MatrixEntry.unref() not with cogl_object_ref() and cogl_object_unref().

calculate_translation(entry1)¶

Parameters:

entry1 (Cogl.MatrixEntry) – A second reference transform

Returns:

True if the only difference between the transform of self and the transform of entry1 is a translation, otherwise False.

x:: The destination for the x-component of the translation
y:: The destination for the y-component of the translation
z:: The destination for the z-component of the translation

Return type:

(int, x: float, y: float, z: float)

Determines if the only difference between two transforms is a translation and if so returns what the x, y, and z components of the translation are.

If the difference between the two translations involves anything other than a translation then the function returns False.

equal(entry1)¶

Parameters:: entry1 (Cogl.MatrixEntry) – A second Cogl.MatrixEntry to compare
Returns:: True if self represents the same transform as entry1, otherwise False.
Return type:: int

Compares two arbitrary Cogl.MatrixEntry transforms for equality returning True if they are equal or False otherwise.

In many cases it is unnecessary to use this api and instead direct pointer comparisons of entries are good enough and much cheaper too.

get()¶

Returns:

A direct pointer to a Cogl.Matrix transform or None and in that case matrix will be initialized with the effective transform represented by self.

matrix:: The potential destination for the transform as a matrix

Return type:

(Cogl.Matrix, matrix: Cogl.Matrix)

Resolves the current self transform into a Cogl.Matrix by combining the sequence of 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 it’s possible 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 transform of self.

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

is_identity()¶

Returns:: True if self is definitely an identity transform, otherwise False.
Return type:: int

Determines whether self is known to represent an identity transform.

If this returns True then the entry is definitely the identity matrix. If it returns False it may or may not be the identity matrix but no expensive comparison is performed to verify it.

ref()¶

Return type:: Cogl.MatrixEntry

Takes a reference on the given self to ensure the self stays alive and remains valid. When you are finished with the self then you should call Cogl.MatrixEntry.unref().

It is an error to pass an self pointer to cogl_object_ref() and cogl_object_unref()

unref()¶: Releases a reference on self either taken by calling Cogl.MatrixEntry.unref() or to release the reference given when calling Cogl.MatrixStack.get_entry().