/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the QtGui module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "qtransform.h"

#include "qdatastream.h"

#include "qdebug.h"

#include "qmatrix.h"

#include "qregion.h"

#include "qpainterpath.h"

#include "qvariant.h"

#include <qmath.h>

#include <private/qbezier_p.h>

QT_BEGIN_NAMESPACE

#define Q_NEAR_CLIP (sizeof(qreal) == sizeof(double) ? 0.000001 : 0.0001)

#ifdef MAP

#  undef MAP

#endif

#define MAP(x, y, nx, ny) \

    do { \

        qreal FX_ = x; \

        qreal FY_ = y; \

        switch(t) {   \

        case TxNone:  \

            nx = FX_;   \

            ny = FY_;   \

            break;    \

        case TxTranslate:    \

            nx = FX_ + affine._dx;                \

            ny = FY_ + affine._dy;                \

            break;                              \

        case TxScale:                           \

            nx = affine._m11 * FX_ + affine._dx;  \

            ny = affine._m22 * FY_ + affine._dy;  \

            break;                              \

        case TxRotate:                          \

        case TxShear:                           \

        case TxProject:                                      \

            nx = affine._m11 * FX_ + affine._m21 * FY_ + affine._dx;        \

            ny = affine._m12 * FX_ + affine._m22 * FY_ + affine._dy;        \

            if (t == TxProject) {                                       \

                qreal w = (m_13 * FX_ + m_23 * FY_ + m_33);              \

                if (w < qreal(Q_NEAR_CLIP)) w = qreal(Q_NEAR_CLIP);     \

                w = 1./w;                                               \

                nx *= w;                                                \

                ny *= w;                                                \

            }                                                           \

        }                                                               \

    } while (0)

/*!

    \class QTransform

    \brief The QTransform class specifies 2D transformations of a coordinate system.

    \since 4.3

    \ingroup painting

    A transformation specifies how to translate, scale, shear, rotate

    or project the coordinate system, and is typically used when

    rendering graphics.

    QTransform differs from QMatrix in that it is a true 3x3 matrix,

    allowing perspective transformations. QTransform's toAffine()

    method allows casting QTransform to QMatrix. If a perspective

    transformation has been specified on the matrix, then the

    conversion will cause loss of data.

    QTransform is the recommended transformation class in Qt.

    A QTransform object can be built using the setMatrix(), scale(),

    rotate(), translate() and shear() functions.  Alternatively, it

    can be built by applying \l {QTransform#Basic Matrix

    Operations}{basic matrix operations}. The matrix can also be

    defined when constructed, and it can be reset to the identity

    matrix (the default) using the reset() function.

    The QTransform class supports mapping of graphic primitives: A given

    point, line, polygon, region, or painter path can be mapped to the

    coordinate system defined by \e this matrix using the map()

    function. In case of a rectangle, its coordinates can be

    transformed using the mapRect() function. A rectangle can also be

    transformed into a \e polygon (mapped to the coordinate system

    defined by \e this matrix), using the mapToPolygon() function.

    QTransform provides the isIdentity() function which returns true if

    the matrix is the identity matrix, and the isInvertible() function

    which returns true if the matrix is non-singular (i.e. AB = BA =

    I). The inverted() function returns an inverted copy of \e this

    matrix if it is invertible (otherwise it returns the identity

    matrix), and adjoint() returns the matrix's classical adjoint.

    In addition, QTransform provides the determinant() function which

    returns the matrix's determinant.

    Finally, the QTransform class supports matrix multiplication, addition

    and subtraction, and objects of the class can be streamed as well

    as compared.

    \tableofcontents

    \section1 Rendering Graphics

    When rendering graphics, the matrix defines the transformations

    but the actual transformation is performed by the drawing routines

    in QPainter.

    By default, QPainter operates on the associated device's own

    coordinate system.  The standard coordinate system of a

    QPaintDevice has its origin located at the top-left position. The

    \e x values increase to the right; \e y values increase

    downward. For a complete description, see the \l {The Coordinate

    System}{coordinate system} documentation.

    QPainter has functions to translate, scale, shear and rotate the

    coordinate system without using a QTransform. For example:

    \table 100%

    \row

    \o \inlineimage qtransform-simpletransformation.png

    \o

    \snippet doc/src/snippets/transform/main.cpp 0

    \endtable

    Although these functions are very convenient, it can be more

    efficient to build a QTransform and call QPainter::setTransform() if you

    want to perform more than a single transform operation. For

    example:

    \table 100%

    \row

    \o \inlineimage qtransform-combinedtransformation.png

    \o

    \snippet doc/src/snippets/transform/main.cpp 1

    \endtable

    \section1 Basic Matrix Operations

    \image qtransform-representation.png

    A QTransform object contains a 3 x 3 matrix.  The \c m31 (\c dx) and

    \c m32 (\c dy) elements specify horizontal and vertical translation.

    The \c m11 and \c m22 elements specify horizontal and vertical scaling.

    The \c m21 and \c m12 elements specify horizontal and vertical \e shearing.

    And finally, the \c m13 and \c m23 elements specify horizontal and vertical

    projection, with \c m33 as an additional projection factor.

    QTransform transforms a point in the plane to another point using the

    following formulas:

    \snippet doc/src/snippets/code/src_gui_painting_qtransform.cpp 0

    The point \e (x, y) is the original point, and \e (x', y') is the

    transformed point. \e (x', y') can be transformed back to \e (x,

    y) by performing the same operation on the inverted() matrix.

    The various matrix elements can be set when constructing the

    matrix, or by using the setMatrix() function later on. They can also

    be manipulated using the translate(), rotate(), scale() and

    shear() convenience functions. The currently set values can be

    retrieved using the m11(), m12(), m13(), m21(), m22(), m23(),

    m31(), m32(), m33(), dx() and dy() functions.

    Translation is the simplest transformation. Setting \c dx and \c

    dy will move the coordinate system \c dx units along the X axis

    and \c dy units along the Y axis.  Scaling can be done by setting

    \c m11 and \c m22. For example, setting \c m11 to 2 and \c m22 to

    1.5 will double the height and increase the width by 50%.  The

    identity matrix has \c m11, \c m22, and \c m33 set to 1 (all others are set

    to 0) mapping a point to itself. Shearing is controlled by \c m12

    and \c m21. Setting these elements to values different from zero

    will twist the coordinate system. Rotation is achieved by

    setting both the shearing factors and the scaling factors. Perspective

    transformation is achieved by setting both the projection factors and

    the scaling factors.

    Here's the combined transformations example using basic matrix

    operations:

    \table 100%

    \row

    \o \inlineimage qtransform-combinedtransformation2.png

    \o

    \snippet doc/src/snippets/transform/main.cpp 2

    \endtable

    \sa QPainter, {The Coordinate System}, {demos/affine}{Affine

    Transformations Demo}, {Transformations Example}

*/

/*!

    \enum QTransform::TransformationType

    \value TxNone

    \value TxTranslate

    \value TxScale

    \value TxRotate

    \value TxShear

    \value TxProject

*/

/*!

    \fn QTransform::QTransform(Qt::Initialization)

    \internal

*/

/*!

    Constructs an identity matrix.

    All elements are set to zero except \c m11 and \c m22 (specifying

    the scale) and \c m13 which are set to 1.

    \sa reset()

*/

QTransform::QTransform()

    : affine(true)

    , m_13(0), m_23(0), m_33(1)

    , m_type(TxNone)

    , m_dirty(TxNone)

{

}

/*!

    \fn QTransform::QTransform(qreal m11, qreal m12, qreal m13, qreal m21, qreal m22, qreal m23, qreal m31, qreal m32, qreal m33)

    Constructs a matrix with the elements, \a m11, \a m12, \a m13,

    \a m21, \a m22, \a m23, \a m31, \a m32, \a m33.

    \sa setMatrix()

*/

QTransform::QTransform(qreal h11, qreal h12, qreal h13,

                       qreal h21, qreal h22, qreal h23,

                       qreal h31, qreal h32, qreal h33)

    : affine(h11, h12, h21, h22, h31, h32, true)

    , m_13(h13), m_23(h23), m_33(h33)

    , m_type(TxNone)

    , m_dirty(TxProject)

{

}

/*!

    \fn QTransform::QTransform(qreal m11, qreal m12, qreal m21, qreal m22, qreal dx, qreal dy)

    Constructs a matrix with the elements, \a m11, \a m12, \a m21, \a m22, \a dx and \a dy.

    \sa setMatrix()

*/

QTransform::QTransform(qreal h11, qreal h12, qreal h21,

                       qreal h22, qreal dx, qreal dy)

    : affine(h11, h12, h21, h22, dx, dy, true)

    , m_13(0), m_23(0), m_33(1)

    , m_type(TxNone)

    , m_dirty(TxShear)

{

}

/*!

    \fn QTransform::QTransform(const QMatrix &matrix)

    Constructs a matrix that is a copy of the given \a matrix.

    Note that the \c m13, \c m23, and \c m33 elements are set to 0, 0,

    and 1 respectively.

 */

QTransform::QTransform(const QMatrix &mtx)

    : affine(mtx._m11, mtx._m12, mtx._m21, mtx._m22, mtx._dx, mtx._dy, true),

      m_13(0), m_23(0), m_33(1)

    , m_type(TxNone)

    , m_dirty(TxShear)

{

}

/*!

    Returns the adjoint of this matrix.

*/

QTransform QTransform::adjoint() const

{

    qreal h11, h12, h13,

        h21, h22, h23,

        h31, h32, h33;

    h11 = affine._m22*m_33 - m_23*affine._dy;

    h21 = m_23*affine._dx - affine._m21*m_33;

    h31 = affine._m21*affine._dy - affine._m22*affine._dx;

    h12 = m_13*affine._dy - affine._m12*m_33;

    h22 = affine._m11*m_33 - m_13*affine._dx;

    h32 = affine._m12*affine._dx - affine._m11*affine._dy;

    h13 = affine._m12*m_23 - m_13*affine._m22;

    h23 = m_13*affine._m21 - affine._m11*m_23;

    h33 = affine._m11*affine._m22 - affine._m12*affine._m21;

    return QTransform(h11, h12, h13,

                      h21, h22, h23,

                      h31, h32, h33, true);

}

/*!

    Returns the transpose of this matrix.

*/

QTransform QTransform::transposed() const

{

    QTransform t(affine._m11, affine._m21, affine._dx,

                 affine._m12, affine._m22, affine._dy,

                 m_13, m_23, m_33, true);

    t.m_type = m_type;

    t.m_dirty = m_dirty;

    return t;

}

/*!

    Returns an inverted copy of this matrix.

    If the matrix is singular (not invertible), the returned matrix is

    the identity matrix. If \a invertible is valid (i.e. not 0), its

    value is set to true if the matrix is invertible, otherwise it is

    set to false.

    \sa isInvertible()

*/

QTransform QTransform::inverted(bool *invertible) const

{

    QTransform invert(true);

    bool inv = true;

    switch(inline_type()) {

    case TxNone:

        break;

    case TxTranslate:

        invert.affine._dx = -affine._dx;

        invert.affine._dy = -affine._dy;

        break;

    case TxScale:

        inv = !qFuzzyIsNull(affine._m11);

        inv &= !qFuzzyIsNull(affine._m22);

        if (inv) {

            invert.affine._m11 = 1. / affine._m11;

            invert.affine._m22 = 1. / affine._m22;

            invert.affine._dx = -affine._dx * invert.affine._m11;

            invert.affine._dy = -affine._dy * invert.affine._m22;

        }

        break;

    case TxRotate:

    case TxShear:

        invert.affine = affine.inverted(&inv);

        break;

    default:

        // general case

        qreal det = determinant();

        inv = !qFuzzyIsNull(det);

        if (inv)

            invert = adjoint() / det;

        break;

    }

    if (invertible)

        *invertible = inv;

    if (inv) {

        // inverting doesn't change the type

        invert.m_type = m_type;

        invert.m_dirty = m_dirty;

    }

    return invert;

}

/*!

    Moves the coordinate system \a dx along the x axis and \a dy along

    the y axis, and returns a reference to the matrix.

    \sa setMatrix()

*/

QTransform &QTransform::translate(qreal dx, qreal dy)

{

    if (dx == 0 && dy == 0)

        return *this;

    switch(inline_type()) {

    case TxNone:

        affine._dx = dx;

        affine._dy = dy;

        break;

    case TxTranslate:

        affine._dx += dx;

        affine._dy += dy;

        break;

    case TxScale:

        affine._dx += dx*affine._m11;

        affine._dy += dy*affine._m22;

        break;

    case TxProject:

        m_33 += dx*m_13 + dy*m_23;

        // Fall through

    case TxShear:

    case TxRotate:

        affine._dx += dx*affine._m11 + dy*affine._m21;

        affine._dy += dy*affine._m22 + dx*affine._m12;

        break;

    }

    if (m_dirty < TxTranslate)

        m_dirty = TxTranslate;

    return *this;

}

/*!

    Creates a matrix which corresponds to a translation of \a dx along

    the x axis and \a dy along the y axis. This is the same as

    QTransform().translate(dx, dy) but slightly faster.

    \since 4.5

*/

QTransform QTransform::fromTranslate(qreal dx, qreal dy)

{

    QTransform transform(1, 0, 0, 0, 1, 0, dx, dy, 1, true);

    if (dx == 0 && dy == 0)

        transform.m_type = TxNone;

    else

        transform.m_type = TxTranslate;

    transform.m_dirty = TxNone;

    return transform;

}

/*!

    Scales the coordinate system by \a sx horizontally and \a sy

    vertically, and returns a reference to the matrix.

    \sa setMatrix()

*/

QTransform & QTransform::scale(qreal sx, qreal sy)

{

    if (sx == 1 && sy == 1)

        return *this;

    switch(inline_type()) {

    case TxNone:

    case TxTranslate:

        affine._m11 = sx;

        affine._m22 = sy;

        break;

    case TxProject:

        m_13 *= sx;

        m_23 *= sy;

        // fall through

    case TxRotate:

    case TxShear:

        affine._m12 *= sx;

        affine._m21 *= sy;

        // fall through

    case TxScale:

        affine._m11 *= sx;

        affine._m22 *= sy;

        break;

    }

    if (m_dirty < TxScale)

        m_dirty = TxScale;

    return *this;

}

/*!

    Creates a matrix which corresponds to a scaling of

    \a sx horizontally and \a sy vertically.

    This is the same as QTransform().scale(sx, sy) but slightly faster.

    \since 4.5

*/

QTransform QTransform::fromScale(qreal sx, qreal sy)

{

    QTransform transform(sx, 0, 0, 0, sy, 0, 0, 0, 1, true);

    if (sx == 1. && sy == 1.)

        transform.m_type = TxNone;

    else

        transform.m_type = TxScale;

    transform.m_dirty = TxNone;

    return transform;

}

/*!

    Shears the coordinate system by \a sh horizontally and \a sv

    vertically, and returns a reference to the matrix.

    \sa setMatrix()

*/

QTransform & QTransform::shear(qreal sh, qreal sv)

{

    if (sh == 0 && sv == 0)

        return *this;

    switch(inline_type()) {

    case TxNone:

    case TxTranslate:

        affine._m12 = sv;

        affine._m21 = sh;