Cogl.Matrix

Fields

Name

Type

Access

Description

private_member__padding3

int

r

private_member_flags

int

r

private_member_inv

[float]

r

private_member_type

int

r

ww

float

r/w

wx

float

r/w

wy

float

r/w

wz

float

r/w

xw

float

r/w

xx

float

r/w

xy

float

r/w

xz

float

r/w

yw

float

r/w

yx

float

r/w

yy

float

r/w

yz

float

r/w

zw

float

r/w

zx

float

r/w

zy

float

r/w

zz

float

r/w

Methods

class

equal (v1, v2)

copy ()

free ()

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

get_array ()

get_inverse ()

init_from_array (array)

init_from_euler (euler)

init_from_quaternion (quaternion)

init_identity ()

init_translation (tx, ty, tz)

is_identity ()

look_at (eye_position_x, eye_position_y, eye_position_z, object_x, object_y, object_z, world_up_x, world_up_y, world_up_z)

multiply (a, b)

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

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

perspective (fov_y, aspect, z_near, z_far)

project_points (n_components, stride_in, points_in, stride_out, points_out, n_points)

rotate (angle, x, y, z)

rotate_euler (euler)

rotate_quaternion (quaternion)

scale (sx, sy, sz)

transform_point (x, y, z, w)

transform_points (n_components, stride_in, points_in, stride_out, points_out, n_points)

translate (x, y, z)

transpose ()

view_2d_in_frustum (left, right, bottom, top, z_near, z_2d, width_2d, height_2d)

view_2d_in_perspective (fov_y, aspect, z_near, z_2d, width_2d, height_2d)

Details

class Cogl.Matrix

A Cogl.Matrix holds a 4x4 transform matrix. This is a single precision, column-major matrix which means it is compatible with what OpenGL expects.

A Cogl.Matrix can represent transforms such as, rotations, scaling, translation, sheering, and linear projections. You can combine these transforms by multiplying multiple matrices in the order you want them applied.

The transformation of a vertex (x, y, z, w) by a Cogl.Matrix is given by:

x_new = xx * x + xy * y + xz * z + xw * w
y_new = yx * x + yy * y + yz * z + yw * w
z_new = zx * x + zy * y + zz * z + zw * w
w_new = wx * x + wy * y + wz * z + ww * w

Where w is normally 1

You must consider the members of the Cogl.Matrix structure read only, and all matrix modifications must be done via the cogl_matrix API. This allows Cogl to annotate the matrices internally. Violation of this will give undefined results. If you need to initialize a matrix with a constant other than the identity matrix you can use Cogl.Matrix.init_from_array().

classmethod equal(v1, v2)
Parameters:

  • v1 (object or None) – A 4x4 transformation matrix

  • v2 (object or None) – A 4x4 transformation matrix

Return type:

int

Compares two matrices to see if they represent the same transformation. Although internally the matrices may have different annotations associated with them and may potentially have a cached inverse matrix these are not considered in the comparison.

New in version 1.4.

copy()
Returns:

A newly allocated Cogl.Matrix which should be freed using Cogl.Matrix.free()

Return type:

Cogl.Matrix

Allocates a new Cogl.Matrix on the heap and initializes it with the same values as self.

New in version 1.6.

free()

Frees a Cogl.Matrix that was previously allocated via a call to Cogl.Matrix.copy().

New in version 1.6.

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)

Multiplies self by the given frustum perspective matrix.

get_array()
Returns:

a pointer to the float array

Return type:

float

Casts self to a float array which can be directly passed to OpenGL.

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 a given matrix and uses it to initialize a new Cogl.Matrix.

Although the first parameter is annotated as const to indicate that the transform it represents isn’t modified this function may technically save a copy of the inverse transform within the given Cogl.Matrix so that subsequent requests for the inverse transform may avoid costly inversion calculations.

New in version 1.2.

init_from_array(array)
Parameters:

array (float) – A linear array of 16 floats (column-major order)

Initializes self with the contents of array

init_from_euler(euler)
Parameters:

euler (Cogl.Euler) – A Cogl.Euler

Initializes self from a Cogl.Euler rotation.

init_from_quaternion(quaternion)
Parameters:

quaternion (Cogl.Quaternion) – A Cogl.Quaternion

Initializes self from a Cogl.Quaternion rotation.

init_identity()

Resets matrix to the identity matrix:

.xx=1; .xy=0; .xz=0; .xw=0;
.yx=0; .yy=1; .yz=0; .yw=0;
.zx=0; .zy=0; .zz=1; .zw=0;
.wx=0; .wy=0; .wz=0; .ww=1;
init_translation(tx, ty, tz)
Parameters:

  • tx (float) – x coordinate of the translation vector

  • ty (float) – y coordinate of the translation vector

  • tz (float) – z coordinate of the translation vector

Resets matrix to the (tx, ty, tz) translation matrix:

.xx=1; .xy=0; .xz=0; .xw=tx;
.yx=0; .yy=1; .yz=0; .yw=ty;
.zx=0; .zy=0; .zz=1; .zw=tz;
.wx=0; .wy=0; .wz=0; .ww=1;

New in version 2.0.

is_identity()
Returns:

True if self is an identity matrix else False

Return type:

int

Determines if the given matrix is an identity matrix.

New in version 1.8.

look_at(eye_position_x, eye_position_y, eye_position_z, object_x, object_y, object_z, world_up_x, world_up_y, world_up_z)
Parameters:

  • eye_position_x (float) – The X coordinate to look from

  • eye_position_y (float) – The Y coordinate to look from

  • eye_position_z (float) – The Z coordinate to look from

  • object_x (float) – The X coordinate of the object to look at

  • object_y (float) – The Y coordinate of the object to look at

  • object_z (float) – The Z coordinate of the object to look at

  • world_up_x (float) – The X component of the world’s up direction vector

  • world_up_y (float) – The Y component of the world’s up direction vector

  • world_up_z (float) – The Z component of the world’s up direction vector

Applies a view transform self that positions the camera at the coordinate (eye_position_x, eye_position_y, eye_position_z) looking towards an object at the coordinate (object_x, object_y, object_z). The top of the camera is aligned to the given world up vector, which is normally simply (0, 1, 0) to map up to the positive direction of the y axis.

Because there is a lot of missleading documentation online for gluLookAt regarding the up vector we want to try and be a bit clearer here.

The up vector should simply be relative to your world coordinates and does not need to change as you move the eye and object positions. Many online sources may claim that the up vector needs to be perpendicular to the vector between the eye and object position (partly because the man page is somewhat missleading) but that is not necessary for this function.

You should never look directly along the world-up vector. It is assumed you are using a typical projection matrix where your origin maps to the center of your viewport. Almost always when you use this function it should be the first transform applied to a new modelview transform

New in version 1.8.

multiply(a, b)
Parameters:

Multiplies the two supplied matrices together and stores the resulting matrix inside self.

It is possible to multiply the a matrix in-place, so self can be equal to a but can’t be equal to b.

ortho(left, right, bottom, top, near, far)
Parameters:

  • left (float) – The coordinate for the left clipping plane

  • right (float) – The coordinate for the right clipping plane

  • bottom (float) – The coordinate for the bottom clipping plane

  • top (float) – The coordinate for the top 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)

Multiplies self by a parallel projection matrix.

Deprecated since version 1.10: Use Cogl.Matrix.orthographic()

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)

Multiplies self by a parallel projection matrix.

New in version 1.10.

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)

Multiplies self by the described perspective matrix

You should be careful not to have to 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.

project_points(n_components, stride_in, points_in, stride_out, points_out, n_points)
Parameters:

  • n_components (int) – The number of position components for each input point. (either 2, 3 or 4)

  • stride_in (int) – The stride in bytes between input points.

  • points_in (object or None) – A pointer to the first component of the first input point.

  • stride_out (int) – The stride in bytes between output points.

  • points_out (object or None) – A pointer to the first component of the first output point.

  • n_points (int) – The number of points to transform.

Projects an array of input points and writes the result to another array of output points. The input points can either have 2, 3 or 4 components each. The output points always have 4 components (known as homogenous coordinates). The output array can simply point to the input array to do the transform in-place.

Here’s an example with differing input/output strides:

typedef struct {
  float x,y;
  uint8_t r,g,b,a;
  float s,t,p;
} MyInVertex;
typedef struct {
  uint8_t r,g,b,a;
  float x,y,z;
} MyOutVertex;
MyInVertex vertices[N_VERTICES];
MyOutVertex results[N_VERTICES];
CoglMatrix matrix;

my_load_vertices (vertices);
my_get_matrix (&matrix);

cogl_matrix_project_points (&matrix,
                            2,
                            sizeof (MyInVertex),
                            &vertices[0].x,
                            sizeof (MyOutVertex),
                            &results[0].x,
                            N_VERTICES);
rotate(angle, x, y, z)
Parameters:

  • angle (float) – The angle you want to rotate in degrees

  • x (float) – X component of your rotation vector

  • y (float) – Y component of your rotation vector

  • z (float) – Z component of your rotation vector

Multiplies self with a rotation matrix that applies a rotation of angle degrees around the specified 3D vector.

rotate_euler(euler)
Parameters:

euler (Cogl.Euler) – A euler describing a rotation

Multiplies self with a rotation transformation described by the given Cogl.Euler.

New in version 2.0.

rotate_quaternion(quaternion)
Parameters:

quaternion (Cogl.Quaternion) – A quaternion describing a rotation

Multiplies self with a rotation transformation described by the given Cogl.Quaternion.

New in version 2.0.

scale(sx, sy, sz)
Parameters:

  • sx (float) – The X scale factor

  • sy (float) – The Y scale factor

  • sz (float) – The Z scale factor

Multiplies self with a transform matrix that scales along the X, Y and Z axis.

transform_point(x, y, z, w)
Parameters:

  • x (float) – The X component of your points position

  • y (float) – The Y component of your points position

  • z (float) – The Z component of your points position

  • w (float) – The W component of your points position

Returns:

x:

The X component of your points position

y:

The Y component of your points position

z:

The Z component of your points position

w:

The W component of your points position

Return type:

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

Transforms a point whos position is given and returned as four float components.

transform_points(n_components, stride_in, points_in, stride_out, points_out, n_points)
Parameters:

  • n_components (int) – The number of position components for each input point. (either 2 or 3)

  • stride_in (int) – The stride in bytes between input points.

  • points_in (object or None) – A pointer to the first component of the first input point.

  • stride_out (int) – The stride in bytes between output points.

  • points_out (object or None) – A pointer to the first component of the first output point.

  • n_points (int) – The number of points to transform.

Transforms an array of input points and writes the result to another array of output points. The input points can either have 2 or 3 components each. The output points always have 3 components. The output array can simply point to the input array to do the transform in-place.

If you need to transform 4 component points see Cogl.Matrix.project_points().

Here’s an example with differing input/output strides:

typedef struct {
  float x,y;
  uint8_t r,g,b,a;
  float s,t,p;
} MyInVertex;
typedef struct {
  uint8_t r,g,b,a;
  float x,y,z;
} MyOutVertex;
MyInVertex vertices[N_VERTICES];
MyOutVertex results[N_VERTICES];
CoglMatrix matrix;

my_load_vertices (vertices);
my_get_matrix (&matrix);

cogl_matrix_transform_points (&matrix,
                              2,
                              sizeof (MyInVertex),
                              &vertices[0].x,
                              sizeof (MyOutVertex),
                              &results[0].x,
                              N_VERTICES);
translate(x, y, z)
Parameters:

  • x (float) – The X translation you want to apply

  • y (float) – The Y translation you want to apply

  • z (float) – The Z translation you want to apply

Multiplies self with a transform matrix that translates along the X, Y and Z axis.

transpose()

Replaces self with its transpose. Ie, every element (i,j) in the new matrix is taken from element (j,i) in the old matrix.

New in version 1.10.

view_2d_in_frustum(left, right, bottom, top, z_near, z_2d, width_2d, height_2d)
Parameters:

  • left (float) – coord of left vertical clipping plane

  • right (float) – coord of right vertical clipping plane

  • bottom (float) – coord of bottom horizontal clipping plane

  • top (float) – coord of top horizontal clipping plane

  • z_near (float) – The distance to the near clip plane. Never pass 0 and always pass a positive number.

  • z_2d (float) – The distance to the 2D plane. (Should always be positive and be between z_near and the z_far value that was passed to Cogl.Matrix.frustum())

  • width_2d (float) – The width of the 2D coordinate system

  • height_2d (float) – The height of the 2D coordinate system

Multiplies self by a view transform that maps the 2D coordinates (0,0) top left and (width_2d,`height_2d`) bottom right the full viewport size. Geometry at a depth of 0 will now lie on this 2D plane.

Note: this doesn’t multiply the matrix by any projection matrix, but it assumes you have a perspective projection as defined by passing the corresponding arguments to Cogl.Matrix.frustum().

Toolkits such as Clutter that mix 2D and 3D drawing can use this to create a 2D coordinate system within a 3D perspective projected view frustum.

New in version 1.8.

view_2d_in_perspective(fov_y, aspect, z_near, z_2d, width_2d, height_2d)
Parameters:

  • fov_y (float) – A field of view angle for the Y axis

  • aspect (float) – The ratio of width to height determining the field of view angle for the x axis.

  • z_near (float) – The distance to the near clip plane. Never pass 0 and always pass a positive number.

  • z_2d (float) – The distance to the 2D plane. (Should always be positive and be between z_near and the z_far value that was passed to Cogl.Matrix.frustum())

  • width_2d (float) – The width of the 2D coordinate system

  • height_2d (float) – The height of the 2D coordinate system

Multiplies self by a view transform that maps the 2D coordinates (0,0) top left and (width_2d,`height_2d`) bottom right the full viewport size. Geometry at a depth of 0 will now lie on this 2D plane.

Note: this doesn’t multiply the matrix by any projection matrix, but it assumes you have a perspective projection as defined by passing the corresponding arguments to Cogl.Matrix.perspective().

Toolkits such as Clutter that mix 2D and 3D drawing can use this to create a 2D coordinate system within a 3D perspective projected view frustum.

New in version 1.8.