gtkmm: Gsk::Transform Class Reference

gtkmm 4.22.0

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Symbols | List of all members
Gsk::Transform Class Referencefinal

Describes a 3D transform. More...

`#include <gskmm/transform.h>`

## Public Types
enum class | Category { Category::UNKNOWN , Category::ANY , Category::CAT_3D , Category::CAT_2D , Category::CAT_2D_AFFINE , Category::CAT_2D_TRANSLATE , Category::IDENTITY }
| The categories of matrices relevant for GSK and GTK. More...

## Public Member Functions
void | reference () const
| Increment the reference count for this object.
void | unreference () const
| Decrement the reference count for this object.
GskTransform * | gobj ()
| Provides access to the underlying C instance.
const GskTransform * | gobj () const
| Provides access to the underlying C instance.
GskTransform * | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
| Transform ()=delete
| Transform (const Transform &)=delete
Transform & | operator= (const Transform &)=delete
Glib::ustring | to_string () const
| Converts the transform into a human-readable string.
void | to_2d (float & out_xx, float & out_yx, float & out_xy, float & out_yy, float & out_dx, float & out_dy) const
| Converts a transform to a 2D transformation matrix.
void | to_2d_components (float & out_skew_x, float & out_skew_y, float & out_scale_x, float & out_scale_y, float & out_angle, float & out_dx, float & out_dy) const
| Converts a transform to 2D transformation factors.
void | to_affine (float & out_scale_x, float & out_scale_y, float & out_dx, float & out_dy) const
| Converts a transform to 2D affine transformation factors.
void | to_translate (float & out_dx, float & out_dy) const
| Converts a transform to a translation operation.
Category | get_category () const
| Returns the category this transform belongs to.
bool | equal (const Glib::RefPtr< const Transform > & second) const
| Checks two transforms for equality.
Glib::RefPtr< Transform > | transform (const Glib::RefPtr< const Transform > & other) const
| Applies all the operations from other to this transform.
Glib::RefPtr< Transform > | invert () const
| Inverts the given transform.
Glib::RefPtr< Transform > | matrix_2d (float xx, float yx, float xy, float yy, float dx, float dy) const
| Multiplies this transform with the matrix [ xx yx x0; xy yy y0; 0 0 1 ].
Glib::RefPtr< Transform > | translate (const Gdk::Graphene::Point & point) const
| Translates this transform in 2-dimensional space by point.
Glib::RefPtr< Transform > | skew (float skew_x, float skew_y) const
| Applies a skew transform.
Glib::RefPtr< Transform > | rotate (float angle) const
| Rotates this transform by an angle around the Z axis.
Glib::RefPtr< Transform > | scale (float factor_x, float factor_y) const
| Scales this transform in 2-dimensional space by the given factors.
Glib::RefPtr< Transform > | scale_3d (float factor_x, float factor_y, float factor_z) const
| Scales this transform by the given factors.
Glib::RefPtr< Transform > | perspective (float depth) const
| Applies a perspective projection transform.
Gdk::Graphene::Rect | transform_bounds (const Gdk::Graphene::Rect & rect) const
| Transforms a rectangle using the given transform.
Gdk::Graphene::Point | transform_point (const Gdk::Graphene::Point & point) const
| Transforms a point using the given transform.

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system.
static Glib::RefPtr< Transform > | create ()
static Glib::RefPtr< Transform > | create (const Glib::ustring & string)
| Parses a given string into a transform.

## Protected Member Functions
void | operator delete (void *, std::size_t)

## Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gsk::Transform > | wrap (GskTransform * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Describes a 3D transform.

Unlike graphene_matrix_t, Gsk::Transform retains the steps in how a transform was constructed, and allows inspecting them. It is modeled after the way CSS describes transforms.

Gsk::Transform 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.

Since gtkmm 4.20

## Constructor & Destructor Documentation

## ◆ Transform() [1/2]

Gsk::Transform::Transform | ( |  | ) |
| delete

## ◆ Transform() [2/2]

Gsk::Transform::Transform | ( | const Transform & |  | ) |
| delete

## Member Function Documentation

## ◆ create() [1/2]

Glib::RefPtr< Transform > Gsk::Transform::create | ( |  | ) |
| static

## ◆ create() [2/2]

Glib::RefPtr< Transform > Gsk::Transform::create | ( | const Glib::ustring & | string | ) |
| static

Parses a given string 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, an empty RefPtr is returned.

Parameters

  string | The string to parse.

Returns
  A new transform, or an empty RefPtr.

## ◆ equal()

bool Gsk::Transform::equal | ( | const Glib::RefPtr< const Transform > & | second | ) | const

Checks two transforms for equality.

Parameters

  second | The second transform.

Returns
  True if the two transforms perform the same operation.

## ◆ get_category()

Category Gsk::Transform::get_category | ( |  | ) | const

Returns the category this transform belongs to.

Returns
  The category of the transform.

## ◆ get_type()

GType Gsk::Transform::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GskTransform * Gsk::Transform::gobj | ( |  | ) |

Provides access to the underlying C instance.

## ◆ gobj() [2/2]

const GskTransform * Gsk::Transform::gobj | ( |  | ) | const

Provides access to the underlying C instance.

## ◆ gobj_copy()

GskTransform * Gsk::Transform::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ invert()

Glib::RefPtr< Transform > Gsk::Transform::invert | ( |  | ) | const

Inverts the given transform.

If this transform is not invertible, an empty RefPtr is returned.

Returns
  The inverted transform.

## ◆ matrix_2d()

Glib::RefPtr< Transform > Gsk::Transform::matrix_2d | ( | float | xx,
|  | float | yx,
|  | float | xy,
|  | float | yy,
|  | float | dx,
|  | float | dy ) const

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

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

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

Returns
  The new transform.

## ◆ operator delete()

void Gsk::Transform::operator delete | ( | void * | ,
|  | std::size_t | )
| protected

## ◆ operator=()

Transform & Gsk::Transform::operator= | ( | const Transform & |  | ) |
| delete

## ◆ perspective()

Glib::RefPtr< Transform > Gsk::Transform::perspective | ( | float | depth | ) | const

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

  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.

## ◆ reference()

void Gsk::Transform::reference | ( |  | ) | const

Increment the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## ◆ rotate()

Glib::RefPtr< Transform > Gsk::Transform::rotate | ( | float | angle | ) | const

Rotates this transform by an angle around the Z axis.

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

Parameters

  angle | The rotation angle, in degrees (clockwise).

Returns
  The new transform.

## ◆ scale()

Glib::RefPtr< Transform > Gsk::Transform::scale | ( | float | factor_x,
|  | float | factor_y ) const

Scales this transform in 2-dimensional space by the given factors.

Use scale_3d() to scale in all 3 dimensions.

Parameters

  factor_x | Scaling factor on the X axis.
  factor_y | Scaling factor on the Y axis.

Returns
  The new transform.

## ◆ scale_3d()

Glib::RefPtr< Transform > Gsk::Transform::scale_3d | ( | float | factor_x,
|  | float | factor_y,
|  | float | factor_z ) const

Scales this transform by the given factors.

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.

Returns
  The new transform.

## ◆ skew()

Glib::RefPtr< Transform > Gsk::Transform::skew | ( | float | skew_x,
|  | float | skew_y ) const

Applies a skew transform.

Parameters

  skew_x | Skew factor, in degrees, on the X axis.
  skew_y | Skew factor, in degrees, on the Y axis.

Returns
  The new transform.

## ◆ to_2d()

void Gsk::Transform::to_2d | ( | float & | out_xx,
|  | float & | out_yx,
|  | float & | out_xy,
|  | float & | out_yy,
|  | float & | out_dx,
|  | float & | out_dy ) const

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 Gsk::Transform and a matrix type from other 2D drawing libraries, in particular Cairo.

Parameters

  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.

## ◆ to_2d_components()

void Gsk::Transform::to_2d_components | ( | float & | out_skew_x,
|  | float & | out_skew_y,
|  | float & | out_scale_x,
|  | float & | out_scale_y,
|  | float & | out_angle,
|  | float & | out_dx,
|  | float & | out_dy ) const

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 (nullptr, &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.

Since gtkmm 4.20

Parameters

  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.

## ◆ to_affine()

void Gsk::Transform::to_affine | ( | float & | out_scale_x,
|  | float & | out_scale_y,
|  | float & | out_dx,
|  | float & | out_dy ) const

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 ( nullptr, &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.

Parameters

  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.

## ◆ to_string()

Glib::ustring Gsk::Transform::to_string | ( |  | ) | const

Converts the transform into a human-readable string.

The resulting string can be parsed with parse().

This is a wrapper around print().

Returns
  A new string for self.

## ◆ to_translate()

void Gsk::Transform::to_translate | ( | float & | out_dx,
|  | float & | out_dy ) const

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.

Parameters

  out_dx | Return location for the translation in the x direction.
  out_dy | Return location for the translation in the y direction.

## ◆ transform()

Glib::RefPtr< Transform > Gsk::Transform::transform | ( | const Glib::RefPtr< const Transform > & | other | ) | const

Applies all the operations from other to this transform.

Parameters

  other | Transform to apply.

Returns
  The new transform.

## ◆ transform_bounds()

Gdk::Graphene::Rect Gsk::Transform::transform_bounds | ( | const Gdk::Graphene::Rect & | rect | ) | const

Transforms a rectangle using the given transform.

The result is the bounding box containing the coplanar quad.

Parameters

  rect | The rectangle to transform.

Returns
  The transformed rectangle.

## ◆ transform_point()

Gdk::Graphene::Point Gsk::Transform::transform_point | ( | const Gdk::Graphene::Point & | point | ) | const

Transforms a point using the given transform.

Parameters

  point | The point to transform.

Returns
  The transformed point.

## ◆ translate()

Glib::RefPtr< Transform > Gsk::Transform::translate | ( | const Gdk::Graphene::Point & | point | ) | const

Translates this transform in 2-dimensional space by point.

Parameters

  point | The point to translate the transform by.

Returns
  The new transform.

## ◆ unreference()

void Gsk::Transform::unreference | ( |  | ) | const

Decrement the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## Friends And Related Symbol Documentation

## ◆ wrap()

Glib::RefPtr< Gsk::Transform > wrap | ( | GskTransform * | object,
|  | bool | take_copy = false )
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.