:right-sidebar: True Transform =================================================================== .. currentmodule:: gi.repository.Gsk .. class:: Transform(**kwargs) :no-contents-entry: ``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 ------------ .. rst-class:: interim-class .. class:: Transform :no-index: .. classmethod:: new() -> ~gi.repository.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 :const:`None`. Methods ------- .. rst-class:: interim-class .. class:: Transform :no-index: .. method:: equal(second: ~gi.repository.Gsk.Transform | None = None) -> bool Checks two transforms for equality. :param second: the second transform .. method:: get_category() -> ~gi.repository.Gsk.TransformCategory Returns the category this transform belongs to. .. method:: invert() -> ~gi.repository.Gsk.Transform | None Inverts the given transform. If ``self`` is not invertible, :const:`None` is returned. Note that inverting :const:`None` also returns :const:`None`, which is the correct inverse of :const:`None`. If you need to differentiate between those cases, you should check ``self`` is not :const:`None` before calling this function. This function consumes ``self``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. .. method:: matrix(matrix: ~gi.repository.Graphene.Matrix) -> ~gi.repository.Gsk.Transform Multiplies ``next`` with the given ``matrix``\. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param matrix: the matrix to multiply ``next`` with .. classmethod:: parse() -> ~typing.Tuple[bool, ~gi.repository.Gsk.Transform] Parses the given ``string`` into a transform and puts it in ``out_transform``\. Strings printed via :obj:`~gi.repository.Gsk.Transform.to_string` can be read in again successfully using this function. If ``string`` does not describe a valid transform, :const:`False` is returned and :const:`None` is put in ``out_transform``\. .. method:: perspective(depth: float) -> ~gi.repository.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 ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param depth: distance of the z=0 plane. Lower values give a more flattened pyramid and therefore a more pronounced perspective effect. .. method:: print_(string: ~gi.repository.GLib.String) -> None :param string: .. method:: rotate(angle: float) -> ~gi.repository.Gsk.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 :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param angle: the rotation angle, in degrees (clockwise) .. method:: rotate_3d(angle: float, axis: ~gi.repository.Graphene.Vec3) -> ~gi.repository.Gsk.Transform | None Rotates ``next`` ``angle`` degrees around ``axis``\. For a rotation in 2D space, use :obj:`~gi.repository.Gsk.Transform.rotate` This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param angle: the rotation angle, in degrees (clockwise) :param axis: The rotation axis .. method:: scale(factor_x: float, factor_y: float) -> ~gi.repository.Gsk.Transform | None Scales ``next`` in 2-dimensional space by the given factors. Use :obj:`~gi.repository.Gsk.Transform.scale_3d` to scale in all 3 dimensions. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param factor_x: scaling factor on the X axis :param factor_y: scaling factor on the Y axis .. method:: scale_3d(factor_x: float, factor_y: float, factor_z: float) -> ~gi.repository.Gsk.Transform | None Scales ``next`` by the given factors. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param factor_x: scaling factor on the X axis :param factor_y: scaling factor on the Y axis :param factor_z: scaling factor on the Z axis .. method:: skew(skew_x: float, skew_y: float) -> ~gi.repository.Gsk.Transform | None Applies a skew transform. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. .. versionadded:: 4.6 :param skew_x: skew factor, in degrees, on the X axis :param skew_y: skew factor, in degrees, on the Y axis .. method:: to_2d() -> ~typing.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 :func:`~gi.repository.Gsk.Transform.get_category` >= :const:`~gi.repository.Gsk.TransformCategory.2D` to check. The returned values have the following layout: .. code-block:: :dedent: | 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. .. method:: to_2d_components() -> ~typing.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 :func:`~gi.repository.Gsk.Transform.get_category` >= :const:`~gi.repository.Gsk.TransformCategory.2D` to check. .. versionadded:: 4.6 .. method:: to_affine() -> ~typing.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 :func:`~gi.repository.Gsk.Transform.get_category` >= :const:`~gi.repository.Gsk.TransformCategory.2D_AFFINE` to check. .. method:: to_matrix() -> ~gi.repository.Graphene.Matrix Computes the actual value of ``self`` and stores it in ``out_matrix``\. The previous value of ``out_matrix`` will be ignored. .. method:: to_string() -> str Converts a matrix into a string that is suitable for printing. The resulting string can be parsed with :obj:`~gi.repository.Gsk.Transform.parse`\. This is a wrapper around :obj:`~gi.repository.Gsk.Transform.print`\. .. method:: to_translate() -> ~typing.Tuple[float, float] Converts a ``GskTransform`` to a translation operation. ``self`` must be a 2D transformation. If you are not sure, use :func:`~gi.repository.Gsk.Transform.get_category` >= :const:`~gi.repository.Gsk.TransformCategory.2D_TRANSLATE` to check. .. method:: transform(other: ~gi.repository.Gsk.Transform | None = None) -> ~gi.repository.Gsk.Transform | None Applies all the operations from ``other`` to ``next``\. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param other: Transform to apply .. method:: transform_bounds(rect: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect Transforms a ``graphene_rect_t`` using the given transform ``self``\. The result is the bounding box containing the coplanar quad. :param rect: a ``graphene_rect_t`` .. method:: transform_point(point: ~gi.repository.Graphene.Point) -> ~gi.repository.Graphene.Point Transforms a ``graphene_point_t`` using the given transform ``self``\. :param point: a ``graphene_point_t`` .. method:: translate(point: ~gi.repository.Graphene.Point) -> ~gi.repository.Gsk.Transform | None Translates ``next`` in 2-dimensional space by ``point``\. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param point: the point to translate the transform by .. method:: translate_3d(point: ~gi.repository.Graphene.Point3D) -> ~gi.repository.Gsk.Transform | None Translates ``next`` by ``point``\. This function consumes ``next``\. Use :obj:`~gi.repository.Gsk.Transform.ref` first if you want to keep it around. :param point: the point to translate the transform by