gtkmm 4.19.0
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
Transformoperator= (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< Transformtransform (const Glib::RefPtr< const Transform > & other) const
 Applies all the operations from other to this transform.
Glib::RefPtr< Transforminvert () const
 Inverts the given transform.
Glib::RefPtr< Transformtranslate (const Gdk::Graphene::Point & point) const
 Translates this transform in 2-dimensional space by point.
Glib::RefPtr< Transformskew (float skew_x, float skew_y) const
 Applies a skew transform.
Glib::RefPtr< Transformrotate (float angle) const
 Rotates this transform by an angle around the Z axis.
Glib::RefPtr< Transformscale (float factor_x, float factor_y) const
 Scales this transform in 2-dimensional space by the given factors.
Glib::RefPtr< Transformscale_3d (float factor_x, float factor_y, float factor_z) const
 Scales this transform by the given factors.
Glib::RefPtr< Transformperspective (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< Transformcreate ()
static Glib::RefPtr< Transformcreate (const Glib::ustring &string)
 Parses a given string into a transform.

Protected Member Functions

void operator delete (void *, std::size_t)

(Note that these are not member symbols.)

Glib::RefPtr< Gsk::Transformwrap (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
stringThe 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
secondThe 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.

◆ 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
depthDistance 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
angleThe 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_xScaling factor on the X axis.
factor_yScaling 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_xScaling factor on the X axis.
factor_yScaling factor on the Y axis.
factor_zScaling 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_xSkew factor, in degrees, on the X axis.
skew_ySkew 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_xxReturn location for the xx member.
out_yxReturn location for the yx member.
out_xyReturn location for the xy member.
out_yyReturn location for the yy member.
out_dxReturn location for the x0 member.
out_dyReturn 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_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() >= GSK_TRANSFORM_CATEGORY_2D

to check.

Since gtkmm 4.20
Parameters
out_skew_xReturn location for the skew factor in the x direction.
out_skew_yReturn location for the skew factor in the y direction.
out_scale_xReturn location for the scale factor in the x direction.
out_scale_yReturn location for the scale factor in the y direction.
out_angleReturn location for the rotation angle.
out_dxReturn location for the translation in the x direction.
out_dyReturn 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_xReturn location for the scale factor in the x direction.
out_scale_yReturn location for the scale factor in the y direction.
out_dxReturn location for the translation in the x direction.
out_dyReturn 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_dxReturn location for the translation in the x direction.
out_dyReturn 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
otherTransform 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
rectThe 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
pointThe 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
pointThe 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.

◆ wrap()

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

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

Parameters
objectThe C instance.
take_copyFalse 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.