## GskTransform GskTransform — A description for transform operations |

## Functions

GskTransform * | gsk_transform_ref ()
void | gsk_transform_unref ()
GskTransformCategory | gsk_transform_get_category ()
void | gsk_transform_print ()
char * | gsk_transform_to_string ()
gboolean | gsk_transform_parse ()
void | gsk_transform_to_matrix ()
void | gsk_transform_to_2d ()
void | gsk_transform_to_affine ()
void | gsk_transform_to_translate ()
GskTransform * | gsk_transform_transform ()
GskTransform * | gsk_transform_invert ()
GskTransform * | gsk_transform_matrix ()
GskTransform * | gsk_transform_translate ()
GskTransform * | gsk_transform_translate_3d ()
GskTransform * | gsk_transform_rotate ()
GskTransform * | gsk_transform_rotate_3d ()
GskTransform * | gsk_transform_scale ()
GskTransform * | gsk_transform_scale_3d ()
GskTransform * | gsk_transform_perspective ()
gboolean | gsk_transform_equal ()
void | gsk_transform_transform_bounds ()
void | gsk_transform_transform_point ()

## Types and Values

| GskTransform
enum | GskTransformCategory

## 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.

### 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 peform 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 &gt;= 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. |