Back to Doc.qt.io
Contact Us Blog Download Qt

C

Transform Class

class Qul::PlatformInterface::Transform

The 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)

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

m11m12m13
m21m22m23
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 transformsA * 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.

Note: This feature may not be supported by hardware on all reference boards. For more information, see Supported Features table. See also Transform QML type

Member Type Documentation

enum Transform::Type

ConstantValueDescription
Qul::PlatformInterface::Transform::Identity0identity transform
Qul::PlatformInterface::Transform::Translate1pure translation
Qul::PlatformInterface::Transform::UniformScale2scale uniformly and then translate
Qul::PlatformInterface::Transform::Scale3scale and then translate
Qul::PlatformInterface::Transform::Rotation4rotate, scale uniformly (potentially), and then translate.
Qul::PlatformInterface::Transform::ScaleRotation5scale, rotate, and then translate.
Qul::PlatformInterface::Transform::Shear6rotate, scale (non-uniformly), and then translate.
Qul::PlatformInterface::Transform::Project7arbitrary 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.