# C

# Transform Class

class Qul::PlatformInterface::TransformThe Transform class specifies 2D transformations of a coordinate system. More...

Header: | #include <platforminterface/transform.h> |

Since: | Qt Quick Ultralite (Platform) 1.5 |

Inherits: | Qul::PlatformInterface::GenericMatrix (private) |

This class was introduced in Qt Quick Ultralite (Platform) 1.5.

## Public Types

enum | Type { Identity, Translate, UniformScale, Scale, Rotation, …, Project } |

## Public Functions

Transform(float m11, float m12, float m13, float m21, float m22, float m23, float m31, float m32, float m33) | |

Transform(Qul::PlatformInterface::Transform::Type type, float m11, float m12, float m21, float m22, float dx, float dy) | |

Transform() | |

float | m11() const |

float | m12() const |

float | m13() const |

float | m21() const |

float | m22() const |

float | m23() const |

float | m31() const |

float | m32() const |

float | m33() const |

float | determinant() const |

float | dx() const |

float | dy() const |

Qul::PlatformInterface::Transform | inverted(bool *invertible) const |

PlatformInterface::PointF | map(PlatformInterface::PointF point) const |

PlatformInterface::RectF | map(const PlatformInterface::RectF &rect) const |

Qul::PlatformInterface::Transform::Type | optimize() |

Qul::PlatformInterface::Transform & | rotate(float angle) |

Qul::PlatformInterface::Transform & | scale(float sx, float sy) |

Qul::PlatformInterface::Transform & | translate(float x, float y) |

Qul::PlatformInterface::Transform | translated(float x, float y) const |

PlatformInterface::PointF | translation() const |

Qul::PlatformInterface::Transform::Type | type() const |

Qul::PlatformInterface::Transform | operator*(const Qul::PlatformInterface::Transform &transform) const |

bool | operator==(const Qul::PlatformInterface::Transform &transform) const |

## Static Public Members

Qul::PlatformInterface::Transform | fromRotation(float angle) |

Qul::PlatformInterface::Transform | fromScale(float sx, float sy) |

Qul::PlatformInterface::Transform | fromTranslation(float dx, float dy) |

## Detailed Description

A transformation specifies how to translate, scale, shear, rotate, or project the coordinate system. It is typically used when rendering graphics.

The Transform type and its matrix can be set when a Transform object is constructed. The default constructor creates a Transform object with Identity type and matrix. Alternatively, a Transform object can be created using the fromTranslation(), fromRotation(), or fromScale() static functions. It is also possible to create Transform objects by applying basic matrix operations.

The Transform class supports mapping graphic primitives by using the map() functions. For example, a given point or rectangle can be mapped to the coordinate system defined by the transformation.

Transform provides the type() function to get information of the current transformation type, and the optimize() function to force type recheck. The inverted() function returns an inverted copy of the transformation, if it is invertible, otherwise returns the identity transform. In addition, Transform provides the determinant() function, which returns the matrix's determinant.

Finally, the Transform class supports multiplication and equality comparison.

### Basic Matrix Operations

`m11` | `m12` | `m13` |
---|---|---|

`m21` | `m22` | `m23` |

`m31` (dx) | `m32` (dy) | `m33` |

A Transform object contains a 3 x 3 matrix. Where,

`m31 (dx)`

and`m32 (dy)`

specifies horizontal and vertical translation.`m11`

and`m22`

specifies horizontal and vertical scaling.`m12`

and`m21`

specifies horizontal and vertical*shearing*.`m13`

and`m23`

specifies horizontal and vertical projection, with`m33`

as an additional projection factor.

Transform applies transformation on a point in the plane using the following formulas:

x' = m11*x + m21*y + dx y' = m22*y + m12*x + dy if (is not affine) { w' = m13*x + m23*y + m33 x' /= w' y' /= w' }

Where, *(x, y)* is the original point, and *(x', y')* is the transformed point. *(x', y')* can be transformed back to *(x, y)* by performing the same operation on the inverted() matrix.

Various matrix elements can be set when constructing the Transform. They can also be manipulated using the translate(), rotate(), and scale() convenience functions. The current values can be retrieved using the m11(), m12(), m13(), m21(), m22(), m23(), m31(), m32(), m33(), dx(), and dy() functions.

The following transformations are supported:

- Translation can be done by setting
`dx`

and`dy`

, moving the coordinate system`dx`

units along the X axis and`dy`

units along the Y axis. - Scaling can be done by setting
`m11`

and`m22`

. For example, setting`m11`

to 2 and`m22`

to 1.5 doubles the height and increases the width by 50%. - Identity transform by setting
`m11`

,`m22`

, and`m33`

to 1 (all others are set to 0), mapping a point to itself. - Shearing is controlled by
`m12`

and`m21`

. Setting these elements to any value other than zero will twist the coordinate system. - Rotation can be done by setting the shearing and scaling factors.
- Perspective transformation can be done by setting the projection and scaling factors.

**Notes**:

- Internal Transform representation uses a transposed matrix, which changes the order of transformation composition.
- Applying Transform (A) to a vector (V) (x, y, 1) is calculated as
`(m11 * x + m21 * y + m31, m12 * x + m22 * y + m32)`

. This is achieved by calling`A.map(V)`

. Equivalent operations are: (V * A) or (A^T * V). This could be also interpreted as applying the transform from the right. - Consequently chaining two transforms
`A * B`

, means A is applied first, followed by B. - Shearing or projection can be represented by Transform, but non-affine transfromed blending is not supported by the drawing engine yet.

**See also** Transform QML type

## Member Type Documentation

### enum Transform::Type

Constant | Value | Description |
---|---|---|

`Qul::PlatformInterface::Transform::Identity` | `0` | identity transform |

`Qul::PlatformInterface::Transform::Translate` | `1` | pure translation |

`Qul::PlatformInterface::Transform::UniformScale` | `2` | scale uniformly and then translate |

`Qul::PlatformInterface::Transform::Scale` | `3` | scale and then translate |

`Qul::PlatformInterface::Transform::Rotation` | `4` | rotate, scale uniformly (potentially), and then translate. |

`Qul::PlatformInterface::Transform::ScaleRotation` | `5` | scale, rotate, and then translate. |

`Qul::PlatformInterface::Transform::Shear` | `6` | rotate, scale (non-uniformly), and then translate. |

`Qul::PlatformInterface::Transform::Project` | `7` | arbitrary projection transformation |

## Member Function Documentation

### Transform::Transform(float *m11*, float *m12*, float *m13*, float *m21*, float *m22*, float *m23*, float *m31*, float *m32*, float *m33*)

Constructs a Transform object with the Project type and the factors: *m11*, *m12*, *m13*, *m21*, *m22*, *m23*, *m31*, *m32*, *m33*.

**See also **optimize() and Basic Matrix Operations.

### Transform::Transform(Qul::PlatformInterface::Transform::Type *type*, float *m11*, float *m12*, float *m21*, float *m22*, float *dx*, float *dy*)

Constructs a Transform object with the given *type* and factors: *m11*, *m12*, *m21*, *m22*, *dx* and *dy*.

**See also **Basic Matrix Operations.

### Transform::Transform()

The default constructor creates a Transform object with Identity type.

All elements are set to zero except the `m11`

and `m22`

(specifying the scale), and `m33`

, which are set to 1.

**See also **Basic Matrix Operations.

### float Transform::m11() const

Returns the horizontal scaling factor.

**See also **scale() and Basic Matrix Operations.

### float Transform::m12() const

Returns the vertical shearing factor.

**Note: **Shearing can be represented by Transform, but sheared blending is not supported by the drawing engine.

**See also **Basic Matrix Operations.

### float Transform::m13() const

Returns the horizontal projection factor.

**Note: **Projection can be represented by Transform, but projected blending is not supported by the drawing engine, yet.

**See also **Basic Matrix Operations.

### float Transform::m21() const

Returns the horizontal shearing factor.

**See also **Basic Matrix Operations.

### float Transform::m22() const

Returns the vertical scaling factor.

**See also **scale() and Basic Matrix Operations.

### float Transform::m23() const

Returns the vertical projection factor.

**Note: **Projection can be represented by Transform, but projected blending is not supported by the drawing engine.

**See also **Basic Matrix Operations.

### float Transform::m31() const

Returns the horizontal translation factor.

**See also **dx(), translate(), and Basic Matrix Operations.

### float Transform::m32() const

Returns the vertical translation factor.

**See also **dy(), translate(), and Basic Matrix Operations.

### float Transform::m33() const

Returns the division factor.

**See also **Basic Matrix Operations.

### float Transform::determinant() const

Returns the determinant of this transformation's matrix.

### float Transform::dx() const

Returns the horizontal translation factor.

**See also **m31(), translate(), and Basic Matrix Operations.

### float Transform::dy() const

Returns the vertical translation factor.

**See also **m32(), translate(), and Basic Matrix Operations.

`[static] `

Qul::PlatformInterface::Transform Transform::fromRotation(float *angle*)

Returns a Transform object rotated by given *angle*.

**See also **rotate() and Basic Matrix Operations.

`[static] `

Qul::PlatformInterface::Transform Transform::fromScale(float *sx*, float *sy*)

Returns a Transform object with the given *sx* and *sy* scale factors.

**See also **scale() and Basic Matrix Operations.

`[static] `

Qul::PlatformInterface::Transform Transform::fromTranslation(float *dx*, float *dy*)

Returns a Transform object with the given *dx* and *dy* translation factors.

**See also **translated(), translate(), and Basic Matrix Operations.

### Qul::PlatformInterface::Transform Transform::inverted(bool **invertible*) const

Returns inverted copy of this transformation.

If the matrix of this transformation is not invertible, an identity transform is returned. If the given *invertible* is a valid pointer, its value is set to `true`

if the matrix is invertible, otherwise to `false`

.

**See also **Transform().

### PlatformInterface::PointF Transform::map(PlatformInterface::PointF *point*) const

Returns a copy of the given *point*, mapped to the coordinate system defined by this transformation.

**See also **Basic Matrix Operations.

### PlatformInterface::RectF Transform::map(const PlatformInterface::RectF &*rect*) const

Returns a copy of the given *rect*, mapped to the coordinate system defined by this transformation.

**See also **Basic Matrix Operations.

### Qul::PlatformInterface::Transform::Type Transform::optimize()

Optimize the usage of this transform from its current elements.

Some operations such as translate(), scale(), and rotate() can be performed more efficiently on an indentity matrix, or it is previously translated or scaled.

Normally, the Transform class keeps track of this special type internally as operations are performed. However, it can lose track of the special type if the matrix is set directly or if a chain of translation, scale, and rotation can result in a simplified matrix. For example, rotate left, then right by the same angle. In such cases, Transform reverts to the safest but least efficient operations thereafter.

If the Transform's factors conforms to one of the known optimized types, you can force it to recover the special type by calling optimize().

**See also **type().

### Qul::PlatformInterface::Transform &Transform::rotate(float *angle*)

Returns a reference to `this`

transform object rotated by the given *angle*.

The *angle* is specified in degrees.

**See also **Basic Matrix Operations.

### Qul::PlatformInterface::Transform &Transform::scale(float *sx*, float *sy*)

Returns a reference to `this`

transform object scaled by the given *sx* and *sy* factors.

**See also **Basic Matrix Operations.

### Qul::PlatformInterface::Transform &Transform::translate(float *x*, float *y*)

Returns a reference to `this`

transform object, translated by the given *x* and *y* factors.

**See also **translated() and Basic Matrix Operations.

### Qul::PlatformInterface::Transform Transform::translated(float *x*, float *y*) const

Returns a copy of this transformation, translated by the given *x* and *y* factors.

**See also **translate() and Basic Matrix Operations.

### PlatformInterface::PointF Transform::translation() const

Returns a Qul::PlatformInterface::PointF containing the translation factors of this transformation.

**See also **m31(), m32(), dx(), dy(), and Basic Matrix Operations.

### Qul::PlatformInterface::Transform::Type Transform::type() const

Returns the transformation type of this transform.

The transformation type captures all transformations. For example, if the transform is suppose to scale and rotate, the type would be ScaleRotation.

Knowing the transformation type is useful for optimization: you can often optimize how specific transformations are handled.

**See also **optimize().

### Qul::PlatformInterface::Transform Transform::operator*(const Qul::PlatformInterface::Transform &*transform*) const

Returns the result of multiplying this transformation with the given *transform*.

**Note: **Matrix multiplication is not commutative. That is, `a*b != b*a`

.

### bool Transform::operator==(const Qul::PlatformInterface::Transform &*transform*) const

Returns `true`

if this transformation is equal to the given *transform*, otherwise returns `false`

.

Available under certain Qt licenses.

Find out more.