Cogl.Matrix¶
Fields¶
Name |
Type |
Access |
Description |
---|---|---|---|
private_member__padding3 |
r |
||
private_member_flags |
r |
||
private_member_inv |
[ |
r |
|
private_member_type |
r |
||
ww |
r/w |
||
wx |
r/w |
||
wy |
r/w |
||
wz |
r/w |
||
xw |
r/w |
||
xx |
r/w |
||
xy |
r/w |
||
xz |
r/w |
||
yw |
r/w |
||
yx |
r/w |
||
yy |
r/w |
||
yz |
r/w |
||
zw |
r/w |
||
zx |
r/w |
||
zy |
r/w |
||
zz |
r/w |
Methods¶
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 useCogl.Matrix.init_from_array
().- classmethod equal(v1, v2)¶
- Parameters:
- Return type:
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 usingCogl.Matrix.free
()- Return type:
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 toCogl.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 planeright (
float
) – X position of the right clipping plane where it intersects the near clipping planebottom (
float
) – Y position of the bottom clipping plane where it intersects the near clipping planetop (
float
) – Y position of the top clipping plane where it intersects the near clipping planez_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:
Casts self to a float array which can be directly passed to OpenGL.
- get_inverse()¶
- Returns:
True
if the inverse was successfully calculated orFalse
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_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:
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()¶
-
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 fromeye_position_y (
float
) – The Y coordinate to look fromeye_position_z (
float
) – The Z coordinate to look fromobject_x (
float
) – The X coordinate of the object to look atobject_y (
float
) – The Y coordinate of the object to look atobject_z (
float
) – The Z coordinate of the object to look atworld_up_x (
float
) – The X component of the world’s up direction vectorworld_up_y (
float
) – The Y component of the world’s up direction vectorworld_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:
a (
Cogl.Matrix
) – A 4x4 transformation matrixb (
Cogl.Matrix
) – A 4x4 transformation matrix
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 planeright (
float
) – The coordinate for the right clipping planebottom (
float
) – The coordinate for the bottom clipping planetop (
float
) – The coordinate for the top clipping planenear (
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()
- perspective(fov_y, aspect, z_near, z_far)¶
- Parameters:
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.
- rotate(angle, x, y, z)¶
- Parameters:
Multiplies self with a rotation matrix that applies a rotation of angle degrees around the specified 3D vector.
- scale(sx, sy, sz)¶
- Parameters:
Multiplies self with a transform matrix that scales along the X, Y and Z axis.
- transform_point(x, y, z, w)¶
- Parameters:
- 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:
Transforms a point whos position is given and returned as four float components.
- translate(x, y, z)¶
- Parameters:
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.