Transform#

class Transform(**kwargs)#

Describes a 3D transform.

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

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

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

matrix_2d(xx: float, yx: float, xy: float, yy: float, dx: float, dy: float) → Transform | None#

Multiplies next with the matrix [ xx yx x0; xy yy y0; 0 0 1 ].

The result of calling to_2d on the returned Transform should match the input passed to this function.

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

Added in version 4.20.

Parameters:

  • xx – the xx member

  • yx – the yx member

  • xy – the xy member

  • yy – the yy member

  • dx – the x0 member

  • dy – the y0 member

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

Parses a given into a 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 NULL 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 by an angle 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 transform to a 2D transformation matrix.

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

get_category() >= GSK_TRANSFORM_CATEGORY_2D

to check.

The returned values are a subset of the full 4x4 matrix that is computed by to_matrix and 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 transform 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_INIT (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() >= GSK_TRANSFORM_CATEGORY_2D

to check.

Added in version 4.6.

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

Converts a transform 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() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE

to check.

to_matrix() → Matrix#

Computes the 4x4 matrix for the transform.

The previous value of out_matrix will be ignored.

to_string() → str#

Converts the transform into a human-readable string.

The resulting string can be parsed with parse.

This is a wrapper around print.

to_translate() → tuple[float, float]#

Converts a transform to a translation operation.

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

get_category() >= GSK_TRANSFORM_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 rectangle using the given transform.

The result is the bounding box containing the coplanar quad.

The input and output rect may point to the same rectangle.

Parameters:

rect – the rectangle to transform

transform_point(point: Point) → Point#

Transforms a point using the given transform.

Parameters:

point – the point to transform

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