GskTransform

GskTransform — A description for transform operations

Types and Values

Description

GskTransform is an object to describe transform matrices. Unlike graphene_matrix_t, GskTransform retains the steps in how a transform was constructed, and allows inspecting them. It is modeled after the way CSS describes transforms.

GskTransform objects are immutable and cannot be changed after creation. This means code can safely expose them as properties of objects without having to worry about others changing them.

Functions

gsk_transform_ref ()

GskTransform *
gsk_transform_ref (GskTransform *self);

Acquires a reference on the given GskTransform.

Parameters

self

a GskTransform.

[allow-none]

Returns

the GskTransform with an additional reference.

[transfer none]


gsk_transform_unref ()

void
gsk_transform_unref (GskTransform *self);

Releases a reference on the given GskTransform.

If the reference was the last, the resources associated to the self are freed.

Parameters

self

a GskTransform.

[allow-none]

gsk_transform_get_category ()

GskTransformCategory
gsk_transform_get_category (GskTransform *self);

Returns the category this transform belongs to.

Parameters

self

A GskTransform.

[allow-none]

Returns

The category of the transform


gsk_transform_print ()

void
gsk_transform_print (GskTransform *self,
                     GString *string);

Converts self into a human-readable string representation suitable for printing that can later be parsed with gsk_transform_parse().

Parameters

self

a GskTransform.

[allow-none]

string

The string to print into

 

gsk_transform_to_string ()

char *
gsk_transform_to_string (GskTransform *self);

Converts a matrix into a string that is suitable for printing and can later be parsed with gsk_transform_parse().

This is a wrapper around gsk_transform_print(), see that function for details.

Parameters

self

a GskTransform.

[allow-none]

Returns

A new string for self


gsk_transform_parse ()

gboolean
gsk_transform_parse (const char *string,
                     GskTransform **out_transform);

Parses the given string into a transform and puts it in out_transform . Strings printed via gsk_transform_to_string() can be read in again successfully using this function.

If string does not describe a valid transform, FALSE is returned and NULL is put in out_transform .

Parameters

string

the string to parse

 

out_transform

The location to put the transform in.

[out]

Returns

TRUE if string described a valid transform.


gsk_transform_to_matrix ()

void
gsk_transform_to_matrix (GskTransform *self,
                         graphene_matrix_t *out_matrix);

Computes the actual value of self and stores it in out_matrix . The previous value of out_matrix will be ignored.

Parameters

self

a GskTransform.

[allow-none]

out_matrix

The matrix to set.

[out caller-allocates]

gsk_transform_to_2d ()

void
gsk_transform_to_2d (GskTransform *self,
                     float *out_xx,
                     float *out_yx,
                     float *out_xy,
                     float *out_yy,
                     float *out_dx,
                     float *out_dy);

Converts a GskTransform to a 2D transformation matrix. self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D to check.

The returned values have the following layout:

1
2
3
| xx yx |   |  a  b  0 |
| xy yy | = |  c  d  0 |
| dx dy |   | tx ty  1 |

This function can be used to convert between a GskTransform and a matrix type from other 2D drawing libraries, in particular Cairo.

Parameters

self

a 2D GskTransform

 

out_xx

return location for the xx member.

[out]

out_yx

return location for the yx member.

[out]

out_xy

return location for the xy member.

[out]

out_yy

return location for the yy member.

[out]

out_dx

return location for the x0 member.

[out]

out_dy

return location for the y0 member.

[out]

gsk_transform_to_affine ()

void
gsk_transform_to_affine (GskTransform *self,
                         float *out_scale_x,
                         float *out_scale_y,
                         float *out_dx,
                         float *out_dy);

Converts a GskTransform to 2D affine transformation factors. self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE to check.

Parameters

self

a GskTransform

 

out_scale_x

return location for the scale factor in the x direction.

[out]

out_scale_y

return location for the scale factor in the y direction.

[out]

out_dx

return location for the translation in the x direction.

[out]

out_dy

return location for the translation in the y direction.

[out]

gsk_transform_to_translate ()

void
gsk_transform_to_translate (GskTransform *self,
                            float *out_dx,
                            float *out_dy);

Converts a GskTransform to a translation operation. self must be a 2D transformation. If you are not sure, use gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE to check.

Parameters

self

a GskTransform

 

out_dx

return location for the translation in the x direction.

[out]

out_dy

return location for the translation in the y direction.

[out]

gsk_transform_transform ()

GskTransform *
gsk_transform_transform (GskTransform *next,
                         GskTransform *other);

Applies all the operations from other to next .

Parameters

next

Transform to apply other to.

[allow-none][transfer full]

other

Transform to apply.

[allow-none]

Returns

The new transform


gsk_transform_invert ()

GskTransform *
gsk_transform_invert (GskTransform *self);

Inverts the given transform.

If self is not invertible, NULL is returned. Note that inverting NULL also returns NULL, which is the correct inverse of NULL. If you need to differentiate between those cases, you should check self is not NULL before calling this function.

Parameters

self

Transform to invert.

[allow-none][transfer full]

Returns

The inverted transform or NULL if the transform cannot be inverted.

[nullable]


gsk_transform_matrix ()

GskTransform *
gsk_transform_matrix (GskTransform *next,
                      const graphene_matrix_t *matrix);

Multiplies next with the given matrix .

Parameters

next

the next transform.

[allow-none][transfer full]

matrix

the matrix to multiply next with

 

Returns

The new transform


gsk_transform_translate ()

GskTransform *
gsk_transform_translate (GskTransform *next,
                         const graphene_point_t *point);

Translates next in 2dimensional space by point .

Parameters

next

the next transform.

[allow-none][transfer full]

point

the point to translate the transform by

 

Returns

The new transform


gsk_transform_translate_3d ()

GskTransform *
gsk_transform_translate_3d (GskTransform *next,
                            const graphene_point3d_t *point);

Translates next by point .

Parameters

next

the next transform.

[allow-none][transfer full]

point

the point to translate the transform by

 

Returns

The new transform


gsk_transform_rotate ()

GskTransform *
gsk_transform_rotate (GskTransform *next,
                      float angle);

Rotates next angle degrees in 2D - or in 3Dspeak, around the z axis.

Parameters

next

the next transform.

[allow-none][transfer full]

angle

the rotation angle, in degrees (clockwise)

 

Returns

The new transform


gsk_transform_rotate_3d ()

GskTransform *
gsk_transform_rotate_3d (GskTransform *next,
                         float angle,
                         const graphene_vec3_t *axis);

Rotates next angle degrees around axis .

For a rotation in 2D space, use gsk_transform_rotate().

Parameters

next

the next transform.

[allow-none][transfer full]

angle

the rotation angle, in degrees (clockwise)

 

axis

The rotation axis

 

Returns

The new transform


gsk_transform_scale ()

GskTransform *
gsk_transform_scale (GskTransform *next,
                     float factor_x,
                     float factor_y);

Scales next in 2-dimensional space by the given factors. Use gsk_transform_scale_3d() to scale in all 3 dimensions.

Parameters

next

the next transform.

[allow-none][transfer full]

factor_x

scaling factor on the X axis

 

factor_y

scaling factor on the Y axis

 

Returns

The new transform


gsk_transform_scale_3d ()

GskTransform *
gsk_transform_scale_3d (GskTransform *next,
                        float factor_x,
                        float factor_y,
                        float factor_z);

Scales next by the given factors.

Parameters

next

the next transform.

[allow-none][transfer full]

factor_x

scaling factor on the X axis

 

factor_y

scaling factor on the Y axis

 

factor_z

scaling factor on the Z axis

 

Returns

The new transform


gsk_transform_perspective ()

GskTransform *
gsk_transform_perspective (GskTransform *next,
                           float depth);

Applies a perspective projection transform. This transform scales points in X and Y based on their Z value, scaling points with positive Z values away from the origin, and those with negative Z values towards the origin. Points on the z=0 plane are unchanged.

Parameters

next

the next transform.

[allow-none][transfer full]

depth

distance of the z=0 plane. Lower values give a more flattened pyramid and therefore a more pronounced perspective effect.

 

Returns

The new transform


gsk_transform_equal ()

gboolean
gsk_transform_equal (GskTransform *first,
                     GskTransform *second);

Checks two transforms for equality.

Parameters

first

the first transform

 

second

the second transform

 

Returns

TRUE if the two transforms perform the same operation.


gsk_transform_transform_bounds ()

void
gsk_transform_transform_bounds (GskTransform *self,
                                const graphene_rect_t *rect,
                                graphene_rect_t *out_rect);

Transforms a graphene_rect_t using the given transform self . The result is the bounding box containing the coplanar quad.

Parameters

self

a GskTransform

 

rect

a graphene_rect_t

 

out_rect

return location for the bounds of the transformed rectangle.

[out caller-allocates]

gsk_transform_transform_point ()

void
gsk_transform_transform_point (GskTransform *self,
                               const graphene_point_t *point,
                               graphene_point_t *out_point);

Transforms a graphene_point_t using the given transform self .

Parameters

self

a GskTransform

 

point

a graphene_point_t

 

out_point

return location for the transformed point.

[out caller-allocates]

Types and Values

GskTransform

typedef struct _GskTransform GskTransform;

The GskTransform structure contains only private data.


enum GskTransformCategory

The categories of matrices relevant for GSK and GTK. Note that any category includes matrices of all later categories. So if you want to for example check if a matrix is a 2D matrix, category >= GSK_TRANSFORM_CATEGORY_2D is the way to do this.

Also keep in mind that rounding errors may cause matrices to not conform to their categories. Otherwise, matrix operations done via mutliplication will not worsen categories. So for the matrix multiplication C = A * B, category(C) = MIN (category(A), category(B)).

Members

GSK_TRANSFORM_CATEGORY_UNKNOWN

The category of the matrix has not been determined.

 

GSK_TRANSFORM_CATEGORY_ANY

Analyzing the matrix concluded that it does not fit in any other category.

 

GSK_TRANSFORM_CATEGORY_3D

The matrix is a 3D matrix. This means that the w column (the last column) has the values (0, 0, 0, 1).

 

GSK_TRANSFORM_CATEGORY_2D

The matrix is a 2D matrix. This is equivalent to graphene_matrix_is_2d() returning TRUE. In particular, this means that Cairo can deal with the matrix.

 

GSK_TRANSFORM_CATEGORY_2D_AFFINE

The matrix is a combination of 2D scale and 2D translation operations. In particular, this means that any rectangle can be transformed exactly using this matrix.

 

GSK_TRANSFORM_CATEGORY_2D_TRANSLATE

The matrix is a 2D translation.

 

GSK_TRANSFORM_CATEGORY_IDENTITY

The matrix is the identity matrix.