Top |
Functions
void | cogl_matrix_init_identity () |
CoglMatrix * | cogl_matrix_copy () |
CoglBool | cogl_matrix_equal () |
void | cogl_matrix_free () |
void | cogl_matrix_frustum () |
void | cogl_matrix_ortho () |
void | cogl_matrix_perspective () |
void | cogl_matrix_multiply () |
void | cogl_matrix_rotate () |
void | cogl_matrix_translate () |
void | cogl_matrix_scale () |
void | cogl_matrix_transpose () |
void | cogl_matrix_init_from_array () |
const float * | cogl_matrix_get_array () |
CoglBool | cogl_matrix_get_inverse () |
void | cogl_matrix_transform_point () |
void | cogl_matrix_project_points () |
void | cogl_matrix_transform_points () |
CoglBool | cogl_matrix_is_identity () |
Description
Matrices are used in Cogl to describe affine model-view transforms, texture transforms, and projective transforms. This exposes a utility API that can be used for direct manipulation of these matrices.
Functions
cogl_matrix_init_identity ()
void
cogl_matrix_init_identity (CoglMatrix *matrix
);
Resets matrix to the identity matrix:
1 2 3 4 |
.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; |
cogl_matrix_copy ()
CoglMatrix *
cogl_matrix_copy (const CoglMatrix *matrix
);
Allocates a new CoglMatrix on the heap and initializes it with
the same values as matrix
.
Returns
A newly allocated CoglMatrix which
should be freed using cogl_matrix_free()
.
[transfer full]
Since: 1.6
cogl_matrix_equal ()
CoglBool cogl_matrix_equal (const void *v1
,const void *v2
);
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.
Since: 1.4
cogl_matrix_free ()
void
cogl_matrix_free (CoglMatrix *matrix
);
Frees a CoglMatrix that was previously allocated via a call to
cogl_matrix_copy()
.
Since: 1.6
cogl_matrix_frustum ()
void cogl_matrix_frustum (CoglMatrix *matrix
,float left
,float right
,float bottom
,float top
,float z_near
,float z_far
);
Multiplies matrix
by the given frustum perspective matrix.
Parameters
matrix |
A 4x4 transformation matrix |
|
left |
X position of the left clipping plane where it intersects the near clipping plane |
|
right |
X position of the right clipping plane where it intersects the near clipping plane |
|
bottom |
Y position of the bottom clipping plane where it intersects the near clipping plane |
|
top |
Y position of the top clipping plane where it intersects the near clipping plane |
|
z_near |
The distance to the near clipping plane (Must be positive) |
|
z_far |
The distance to the far clipping plane (Must be positive) |
cogl_matrix_ortho ()
void cogl_matrix_ortho (CoglMatrix *matrix
,float left
,float right
,float bottom
,float top
,float near
,float far
);
cogl_matrix_ortho
has been deprecated since version 1.10 and should not be used in newly-written code.
Use cogl_matrix_orthographic()
Multiplies matrix
by a parallel projection matrix.
Parameters
matrix |
A 4x4 transformation matrix |
|
left |
The coordinate for the left clipping plane |
|
right |
The coordinate for the right clipping plane |
|
bottom |
The coordinate for the bottom clipping plane |
|
top |
The coordinate for the top clipping plane |
|
near |
The distance to the near clipping plane (will be negative if the plane is behind the viewer) |
|
far |
The distance to the far clipping plane (will be negative if the plane is behind the viewer) |
cogl_matrix_perspective ()
void cogl_matrix_perspective (CoglMatrix *matrix
,float fov_y
,float aspect
,float z_near
,float z_far
);
Multiplies matrix
by the described perspective matrix
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.cogl_matrix_multiply ()
void cogl_matrix_multiply (CoglMatrix *result
,const CoglMatrix *a
,const CoglMatrix *b
);
Multiplies the two supplied matrices together and stores
the resulting matrix inside result
.
a
matrix in-place, so
result
can be equal to a
but can't be equal to b
.cogl_matrix_rotate ()
void cogl_matrix_rotate (CoglMatrix *matrix
,float angle
,float x
,float y
,float z
);
Multiplies matrix
with a rotation matrix that applies a rotation
of angle
degrees around the specified 3D vector.
cogl_matrix_translate ()
void cogl_matrix_translate (CoglMatrix *matrix
,float x
,float y
,float z
);
Multiplies matrix
with a transform matrix that translates along
the X, Y and Z axis.
cogl_matrix_scale ()
void cogl_matrix_scale (CoglMatrix *matrix
,float sx
,float sy
,float sz
);
Multiplies matrix
with a transform matrix that scales along the X,
Y and Z axis.
cogl_matrix_transpose ()
void
cogl_matrix_transpose (CoglMatrix *matrix
);
Replaces matrix
with its transpose. Ie, every element (i,j) in the
new matrix is taken from element (j,i) in the old matrix.
Since: 1.10
cogl_matrix_init_from_array ()
void cogl_matrix_init_from_array (CoglMatrix *matrix
,const float *array
);
Initializes matrix
with the contents of array
cogl_matrix_get_array ()
const float *
cogl_matrix_get_array (const CoglMatrix *matrix
);
Casts matrix
to a float array which can be directly passed to OpenGL.
cogl_matrix_get_inverse ()
CoglBool cogl_matrix_get_inverse (const CoglMatrix *matrix
,CoglMatrix *inverse
);
Gets the inverse transform of a given matrix and uses it to initialize a new CoglMatrix.
Parameters
matrix |
A 4x4 transformation matrix |
|
inverse |
The destination for a 4x4 inverse transformation matrix. |
[out] |
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)
Since: 1.2
cogl_matrix_transform_point ()
void cogl_matrix_transform_point (const CoglMatrix *matrix
,float *x
,float *y
,float *z
,float *w
);
Transforms a point whos position is given and returned as four float components.
cogl_matrix_project_points ()
void cogl_matrix_project_points (const CoglMatrix *matrix
,int n_components
,size_t stride_in
,const void *points_in
,size_t stride_out
,void *points_out
,int n_points
);
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
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); |
Parameters
matrix |
A projection matrix |
|
n_components |
The number of position components for each input point. (either 2, 3 or 4) |
|
stride_in |
The stride in bytes between input points. |
|
points_in |
A pointer to the first component of the first input point. |
|
stride_out |
The stride in bytes between output points. |
|
points_out |
A pointer to the first component of the first output point. |
|
n_points |
The number of points to transform. |
Stability Level: Unstable
cogl_matrix_transform_points ()
void cogl_matrix_transform_points (const CoglMatrix *matrix
,int n_components
,size_t stride_in
,const void *points_in
,size_t stride_out
,void *points_out
,int n_points
);
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
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); |
Parameters
matrix |
A transformation matrix |
|
n_components |
The number of position components for each input point. (either 2 or 3) |
|
stride_in |
The stride in bytes between input points. |
|
points_in |
A pointer to the first component of the first input point. |
|
stride_out |
The stride in bytes between output points. |
|
points_out |
A pointer to the first component of the first output point. |
|
n_points |
The number of points to transform. |
Stability Level: Unstable
cogl_matrix_is_identity ()
CoglBool
cogl_matrix_is_identity (const CoglMatrix *matrix
);
Determines if the given matrix is an identity matrix.
Since: 1.8
Types and Values
CoglMatrix
typedef struct { /* column 0 */ float xx; float yx; float zx; float wx; /* column 1 */ float xy; float yy; float zy; float wy; /* column 2 */ float xz; float yz; float zz; float wz; /* column 3 */ float xw; float yw; float zw; float ww; } CoglMatrix;
A CoglMatrix holds a 4x4 transform matrix. This is a single precision, column-major matrix which means it is compatible with what OpenGL expects.
A CoglMatrix 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 CoglMatrix is given by:
1 2 3 4 |
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
cogl_matrix_init_from_array()
.