Transform#

class Transform(**kwargs)#

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.

Constructors#

class Transform
classmethod new() → Transform#

Creates a new identity transform.

This function is meant to be used by language bindings. For C code, this is equivalent to using None.

Methods#

class Transform
equal(second: Transform | None = None) → bool#

Checks two transforms for equality.

Parameters:

second – the second transform

get_category() → TransformCategory#

Returns the category this transform belongs to.

invert() → Transform | None#

Inverts the given transform.

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

This function consumes self. Use ref first if you want to keep it around.

matrix(matrix: Matrix) → Transform#

Multiplies next with the given matrix.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

matrix – the matrix to multiply next with

classmethod parse() → tuple[bool, Transform]#

Parses the given string into a transform and puts it in out_transform.

Strings printed via to_string can be read in again successfully using this function.

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

perspective(depth: float) → Transform#

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.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

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

print_(string: String) → None#
Parameters:

string

rotate(angle: float) → Transform | None#

Rotates next angle degrees in 2D - or in 3D-speak, around the Z axis. The rotation happens around the origin point of (0, 0).

This function consumes next. Use ref first if you want to keep it around.

Parameters:

angle – the rotation angle, in degrees (clockwise)

rotate_3d(angle: float, axis: Vec3) → Transform | None#

Rotates next angle degrees around axis.

For a rotation in 2D space, use rotate

This function consumes next. Use ref first if you want to keep it around.

Parameters:

  • angle – the rotation angle, in degrees (clockwise)

  • axis – The rotation axis

scale(factor_x: float, factor_y: float) → Transform | None#

Scales next in 2-dimensional space by the given factors.

Use scale_3d to scale in all 3 dimensions.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

  • factor_x – scaling factor on the X axis

  • factor_y – scaling factor on the Y axis

scale_3d(factor_x: float, factor_y: float, factor_z: float) → Transform | None#

Scales next by the given factors.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

  • factor_x – scaling factor on the X axis

  • factor_y – scaling factor on the Y axis

  • factor_z – scaling factor on the Z axis

skew(skew_x: float, skew_y: float) → Transform | None#

Applies a skew transform.

This function consumes next. Use ref first if you want to keep it around.

Added in version 4.6.

Parameters:

  • skew_x – skew factor, in degrees, on the X axis

  • skew_y – skew factor, in degrees, on the Y axis

to_2d() → tuple[float, float, float, float, float, float]#

Converts a GskTransform to a 2D transformation matrix.

self must be a 2D transformation. If you are not sure, use get_category() >= 2D to check.

The returned values have the following layout:

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

to_2d_components() → tuple[float, float, float, float, float, float, float]#

Converts a GskTransform to 2D transformation factors.

To recreate an equivalent transform from the factors returned by this function, use

gsk_transform_skew (
gsk_transform_scale (
gsk_transform_rotate (

gsk_transform_translate (NULL, &GRAPHENE_POINT_T (dx, dy)), angle),

scale_x, scale_y),

skew_x, skew_y)

self must be a 2D transformation. If you are not sure, use

get_category() >= 2D

to check.

Added in version 4.6.

to_affine() → tuple[float, float, float, float]#

Converts a GskTransform to 2D affine transformation factors.

To recreate an equivalent transform from the factors returned by this function, use

gsk_transform_scale (gsk_transform_translate (NULL,

&GRAPHENE_POINT_T (dx, dy)),

sx, sy)

self must be a 2D affine transformation. If you are not sure, use

get_category() >= 2D_AFFINE

to check.

to_matrix() → Matrix#

Computes the actual value of self and stores it in out_matrix.

The previous value of out_matrix will be ignored.

to_string() → str#

Converts a matrix into a string that is suitable for printing.

The resulting string can be parsed with parse.

This is a wrapper around print.

to_translate() → tuple[float, float]#

Converts a GskTransform to a translation operation.

self must be a 2D transformation. If you are not sure, use

get_category() >= 2D_TRANSLATE

to check.

transform(other: Transform | None = None) → Transform | None#

Applies all the operations from other to next.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

other – Transform to apply

transform_bounds(rect: Rect) → Rect#

Transforms a graphene_rect_t using the given transform self.

The result is the bounding box containing the coplanar quad.

Parameters:

rect – a graphene_rect_t

transform_point(point: Point) → Point#

Transforms a graphene_point_t using the given transform self.

Parameters:

point – a graphene_point_t

translate(point: Point) → Transform | None#

Translates next in 2-dimensional space by point.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

point – the point to translate the transform by

translate_3d(point: Point3D) → Transform | None#

Translates next by point.

This function consumes next. Use ref first if you want to keep it around.

Parameters:

point – the point to translate the transform by