Gsk.Transform¶

Fields¶

None

Methods¶

class	`new` ()
class	`parse` (string)
	`equal` (second)
	`get_category` ()
	`invert` ()
	`matrix` (matrix)
	`perspective` (depth)
	`print_` (string)
	`ref` ()
	`rotate` (angle)
	`rotate_3d` (angle, axis)
	`scale` (factor_x, factor_y)
	`scale_3d` (factor_x, factor_y, factor_z)
	`skew` (skew_x, skew_y)
	`to_2d` ()
	`to_2d_components` ()
	`to_affine` ()
	`to_matrix` ()
	`to_string` ()
	`to_translate` ()
	`transform` (other)
	`transform_bounds` (rect)
	`transform_point` (point)
	`translate` (point)
	`translate_3d` (point)
	`unref` ()

Details¶

class Gsk.Transform¶

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.

classmethod new()¶

Returns:: A new identity transform
Return type:: Gsk.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.

classmethod parse(string)¶

Parameters:

string (str) – the string to parse

Returns:

true if string described a valid transform

out_transform:: return location for the transform

Return type:

(bool, out_transform: Gsk.Transform)

Parses a given into a transform.

Strings printed via [method`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.

equal(second)¶

Parameters:: second (Gsk.Transform or None) – the second transform
Returns:: true if the two transforms perform the same operation
Return type:: bool

Checks two transforms for equality.

get_category()¶

Returns:: The category of the transform
Return type:: Gsk.TransformCategory

Returns the category this transform belongs to.

invert()¶

Returns:: The inverted transform
Return type:: Gsk.Transform or 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 [method`Gsk`.Transform.ref] first if you want to keep it around.

matrix(matrix)¶

Parameters:: matrix (Graphene.Matrix) – the matrix to multiply self with
Returns:: The new transform
Return type:: Gsk.Transform

Multiplies self with the given matrix.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

perspective(depth)¶

Parameters:: depth (float) – distance of the z=0 plane. Lower values give a more flattened pyramid and therefore a more pronounced perspective effect.
Returns:: The new transform
Return type:: Gsk.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 self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

print_(string)¶

Parameters:: string (GLib.String) – The string to print into

Converts the transform into a human-readable representation.

The result of this function can later be parsed with [func`Gsk`.Transform.parse].

ref()¶

Returns:: the transform with an additional reference
Return type:: Gsk.Transform or None

Acquires a reference on the given transform.

rotate(angle)¶

Parameters:: angle (float) – the rotation angle, in degrees (clockwise)
Returns:: The new transform
Return type:: Gsk.Transform or None

Rotates self by an angle around the Z axis.

The rotation happens around the origin point of (0, 0).

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

rotate_3d(angle, axis)¶

Parameters:

angle (float) – the rotation angle, in degrees (clockwise)
axis (Graphene.Vec3) – The rotation axis

Returns:

The new transform

Return type:

Gsk.Transform or None

Rotates self angle degrees around axis.

For a rotation in 2D space, use [method`Gsk`.Transform.rotate]

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

scale(factor_x, factor_y)¶

Parameters:

factor_x (float) – scaling factor on the X axis
factor_y (float) – scaling factor on the Y axis

Returns:

The new transform

Return type:

Gsk.Transform or None

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

Use [method`Gsk`.Transform.scale_3d] to scale in all 3 dimensions.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

scale_3d(factor_x, factor_y, factor_z)¶

Parameters:

factor_x (float) – scaling factor on the X axis
factor_y (float) – scaling factor on the Y axis
factor_z (float) – scaling factor on the Z axis

Returns:

The new transform

Return type:

Gsk.Transform or None

Scales self by the given factors.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

skew(skew_x, skew_y)¶

Parameters:

skew_x (float) – skew factor, in degrees, on the X axis
skew_y (float) – skew factor, in degrees, on the Y axis

Returns:

The new transform

Return type:

Gsk.Transform or None

Applies a skew transform.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

New in version 4.6.

to_2d()¶

Returns:

out_xx:: return location for the xx member
out_yx:: return location for the yx member
out_xy:: return location for the xy member
out_yy:: return location for the yy member
out_dx:: return location for the x0 member
out_dy:: return location for the y0 member

Return type:

(out_xx: float, out_yx: float, out_xy: float, out_yy: float, out_dx: float, out_dy: float)

Converts a transform to a 2D transformation matrix.

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

Gsk.Transform.get_category() >= Gsk.TransformCategory._2D

to check.

The returned values are a subset of the full 4x4 matrix that is computed by [method`Gsk`.Transform.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()¶

Returns:

out_skew_x:: return location for the skew factor in the x direction
out_skew_y:: return location for the skew factor in the y direction
out_scale_x:: return location for the scale factor in the x direction
out_scale_y:: return location for the scale factor in the y direction
out_angle:: return location for the rotation angle
out_dx:: return location for the translation in the x direction
out_dy:: return location for the translation in the y direction

Return type:

(out_skew_x: float, out_skew_y: float, out_scale_x: float, out_scale_y: float, out_angle: float, out_dx: float, out_dy: 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 (None, &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

Gsk.Transform.get_category() >= Gsk.TransformCategory._2D

to check.

New in version 4.6.

to_affine()¶

Returns:

out_scale_x:: return location for the scale factor in the x direction
out_scale_y:: return location for the scale factor in the y direction
out_dx:: return location for the translation in the x direction
out_dy:: return location for the translation in the y direction

Return type:

(out_scale_x: float, out_scale_y: float, out_dx: float, out_dy: 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 ( None, &GRAPHENE_POINT_T (dx, dy)), sx, sy)

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

Gsk.Transform.get_category() >= Gsk.TransformCategory._2D_AFFINE

to check.

to_matrix()¶

Returns:: return location for the matrix
Return type:: out_matrix: Graphene.Matrix

Computes the 4x4 matrix for the transform.

The previous value of out_matrix will be ignored.

to_string()¶

Returns:: A new string for self
Return type:: str

Converts the transform into a human-readable string.

The resulting string can be parsed with [func`Gsk`.Transform.parse].

This is a wrapper around [method`Gsk`.Transform.print].

to_translate()¶

Returns:

out_dx:: return location for the translation in the x direction
out_dy:: return location for the translation in the y direction

Return type:

(out_dx: float, out_dy: float)

Converts a transform to a translation operation.

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

Gsk.Transform.get_category() >= Gsk.TransformCategory._2D_TRANSLATE

to check.

transform(other)¶

Parameters:: other (Gsk.Transform or None) – transform to apply
Returns:: The new transform
Return type:: Gsk.Transform or None

Applies all the operations from other to self.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

transform_bounds(rect)¶

Parameters:: rect (Graphene.Rect) – the rectangle to transform
Returns:: return location for the bounds of the transformed rectangle
Return type:: out_rect: Graphene.Rect

Transforms a rectangle using the given transform.

The result is the bounding box containing the coplanar quad.

transform_point(point)¶

Parameters:: point (Graphene.Point) – the point to transform
Returns:: return location for the transformed point
Return type:: out_point: Graphene.Point

Transforms a point using the given transform.

translate(point)¶

Parameters:: point (Graphene.Point) – the point to translate the transform by
Returns:: The new transform
Return type:: Gsk.Transform or None

Translates self in 2-dimensional space by point.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

translate_3d(point)¶

Parameters:: point (Graphene.Point3D) – the point to translate the transform by
Returns:: The new transform
Return type:: Gsk.Transform or None

Translates self by point.

This function consumes self. Use [method`Gsk`.Transform.ref] first if you want to keep it around.

unref()¶

Releases a reference on the given transform.

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