/*

 * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt.geom;

import java.awt.Shape;

import java.beans.ConstructorProperties;

/**

 * The <code>AffineTransform</code> class represents a 2D affine transform

 * that performs a linear mapping from 2D coordinates to other 2D

 * coordinates that preserves the "straightness" and

 * "parallelness" of lines.  Affine transformations can be constructed

 * using sequences of translations, scales, flips, rotations, and shears.

 * <p>

 * Such a coordinate transformation can be represented by a 3 row by

 * 3 column matrix with an implied last row of [ 0 0 1 ].  This matrix

 * transforms source coordinates {@code (x,y)} into

 * destination coordinates {@code (x',y')} by considering

 * them to be a column vector and multiplying the coordinate vector

 * by the matrix according to the following process:

 * <pre>

 *      [ x']   [  m00  m01  m02  ] [ x ]   [ m00x + m01y + m02 ]

 *      [ y'] = [  m10  m11  m12  ] [ y ] = [ m10x + m11y + m12 ]

 *      [ 1 ]   [   0    0    1   ] [ 1 ]   [         1         ]

 * </pre>

 * <p>

 * <h4><a name="quadrantapproximation">Handling 90-Degree Rotations</a></h4>

 * <p>

 * In some variations of the <code>rotate</code> methods in the

 * <code>AffineTransform</code> class, a double-precision argument

 * specifies the angle of rotation in radians.

 * These methods have special handling for rotations of approximately

 * 90 degrees (including multiples such as 180, 270, and 360 degrees),

 * so that the common case of quadrant rotation is handled more

 * efficiently.

 * This special handling can cause angles very close to multiples of

 * 90 degrees to be treated as if they were exact multiples of

 * 90 degrees.

 * For small multiples of 90 degrees the range of angles treated

 * as a quadrant rotation is approximately 0.00000121 degrees wide.

 * This section explains why such special care is needed and how

 * it is implemented.

 * <p>

 * Since 90 degrees is represented as <code>PI/2</code> in radians,

 * and since PI is a transcendental (and therefore irrational) number,

 * it is not possible to exactly represent a multiple of 90 degrees as

 * an exact double precision value measured in radians.

 * As a result it is theoretically impossible to describe quadrant

 * rotations (90, 180, 270 or 360 degrees) using these values.

 * Double precision floating point values can get very close to

 * non-zero multiples of <code>PI/2</code> but never close enough

 * for the sine or cosine to be exactly 0.0, 1.0 or -1.0.

 * The implementations of <code>Math.sin()</code> and

 * <code>Math.cos()</code> correspondingly never return 0.0

 * for any case other than <code>Math.sin(0.0)</code>.

 * These same implementations do, however, return exactly 1.0 and

 * -1.0 for some range of numbers around each multiple of 90

 * degrees since the correct answer is so close to 1.0 or -1.0 that

 * the double precision significand cannot represent the difference

 * as accurately as it can for numbers that are near 0.0.

 * <p>

 * The net result of these issues is that if the

 * <code>Math.sin()</code> and <code>Math.cos()</code> methods

 * are used to directly generate the values for the matrix modifications

 * during these radian-based rotation operations then the resulting

 * transform is never strictly classifiable as a quadrant rotation

 * even for a simple case like <code>rotate(Math.PI/2.0)</code>,

 * due to minor variations in the matrix caused by the non-0.0 values

 * obtained for the sine and cosine.

 * If these transforms are not classified as quadrant rotations then

 * subsequent code which attempts to optimize further operations based

 * upon the type of the transform will be relegated to its most general

 * implementation.

 * <p>

 * Because quadrant rotations are fairly common,

 * this class should handle these cases reasonably quickly, both in

 * applying the rotations to the transform and in applying the resulting

 * transform to the coordinates.

 * To facilitate this optimal handling, the methods which take an angle

 * of rotation measured in radians attempt to detect angles that are

 * intended to be quadrant rotations and treat them as such.

 * These methods therefore treat an angle <em>theta</em> as a quadrant

 * rotation if either <code>Math.sin(<em>theta</em>)</code> or

 * <code>Math.cos(<em>theta</em>)</code> returns exactly 1.0 or -1.0.

 * As a rule of thumb, this property holds true for a range of

 * approximately 0.0000000211 radians (or 0.00000121 degrees) around

 * small multiples of <code>Math.PI/2.0</code>.

 *

 * @author Jim Graham

 * @since 1.2

 */

public class AffineTransform implements Cloneable, java.io.Serializable {

    /*

     * This constant is only useful for the cached type field.

     * It indicates that the type has been decached and must be recalculated.

     */

    private static final int TYPE_UNKNOWN = -1;

    /**

     * This constant indicates that the transform defined by this object

     * is an identity transform.

     * An identity transform is one in which the output coordinates are

     * always the same as the input coordinates.

     * If this transform is anything other than the identity transform,

     * the type will either be the constant GENERAL_TRANSFORM or a

     * combination of the appropriate flag bits for the various coordinate

     * conversions that this transform performs.

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_IDENTITY = 0;

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a translation in addition to the conversions indicated

     * by other flag bits.

     * A translation moves the coordinates by a constant amount in x

     * and y without changing the length or angle of vectors.

     * @see #TYPE_IDENTITY

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_TRANSLATION = 1;

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a uniform scale in addition to the conversions indicated

     * by other flag bits.

     * A uniform scale multiplies the length of vectors by the same amount

     * in both the x and y directions without changing the angle between

     * vectors.

     * This flag bit is mutually exclusive with the TYPE_GENERAL_SCALE flag.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_UNIFORM_SCALE = 2;

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a general scale in addition to the conversions indicated

     * by other flag bits.

     * A general scale multiplies the length of vectors by different

     * amounts in the x and y directions without changing the angle

     * between perpendicular vectors.

     * This flag bit is mutually exclusive with the TYPE_UNIFORM_SCALE flag.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_GENERAL_SCALE = 4;

    /**

     * This constant is a bit mask for any of the scale flag bits.

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @since 1.2

     */

    public static final int TYPE_MASK_SCALE = (TYPE_UNIFORM_SCALE |

                                               TYPE_GENERAL_SCALE);

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a mirror image flip about some axis which changes the

     * normally right handed coordinate system into a left handed

     * system in addition to the conversions indicated by other flag bits.

     * A right handed coordinate system is one where the positive X

     * axis rotates counterclockwise to overlay the positive Y axis

     * similar to the direction that the fingers on your right hand

     * curl when you stare end on at your thumb.

     * A left handed coordinate system is one where the positive X

     * axis rotates clockwise to overlay the positive Y axis similar

     * to the direction that the fingers on your left hand curl.

     * There is no mathematical way to determine the angle of the

     * original flipping or mirroring transformation since all angles

     * of flip are identical given an appropriate adjusting rotation.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_FLIP = 64;

    /* NOTE: TYPE_FLIP was added after GENERAL_TRANSFORM was in public

     * circulation and the flag bits could no longer be conveniently

     * renumbered without introducing binary incompatibility in outside

     * code.

     */

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a quadrant rotation by some multiple of 90 degrees in

     * addition to the conversions indicated by other flag bits.

     * A rotation changes the angles of vectors by the same amount

     * regardless of the original direction of the vector and without

     * changing the length of the vector.

     * This flag bit is mutually exclusive with the TYPE_GENERAL_ROTATION flag.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_QUADRANT_ROTATION = 8;

    /**

     * This flag bit indicates that the transform defined by this object

     * performs a rotation by an arbitrary angle in addition to the

     * conversions indicated by other flag bits.

     * A rotation changes the angles of vectors by the same amount

     * regardless of the original direction of the vector and without

     * changing the length of the vector.

     * This flag bit is mutually exclusive with the

     * TYPE_QUADRANT_ROTATION flag.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_GENERAL_ROTATION = 16;

    /**

     * This constant is a bit mask for any of the rotation flag bits.

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @since 1.2

     */

    public static final int TYPE_MASK_ROTATION = (TYPE_QUADRANT_ROTATION |

                                                  TYPE_GENERAL_ROTATION);

    /**

     * This constant indicates that the transform defined by this object

     * performs an arbitrary conversion of the input coordinates.

     * If this transform can be classified by any of the above constants,

     * the type will either be the constant TYPE_IDENTITY or a

     * combination of the appropriate flag bits for the various coordinate

     * conversions that this transform performs.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #getType

     * @since 1.2

     */

    public static final int TYPE_GENERAL_TRANSFORM = 32;

    /**

     * This constant is used for the internal state variable to indicate

     * that no calculations need to be performed and that the source

     * coordinates only need to be copied to their destinations to

     * complete the transformation equation of this transform.

     * @see #APPLY_TRANSLATE

     * @see #APPLY_SCALE

     * @see #APPLY_SHEAR

     * @see #state

     */

    static final int APPLY_IDENTITY = 0;

    /**

     * This constant is used for the internal state variable to indicate

     * that the translation components of the matrix (m02 and m12) need

     * to be added to complete the transformation equation of this transform.

     * @see #APPLY_IDENTITY

     * @see #APPLY_SCALE

     * @see #APPLY_SHEAR

     * @see #state

     */

    static final int APPLY_TRANSLATE = 1;

    /**

     * This constant is used for the internal state variable to indicate

     * that the scaling components of the matrix (m00 and m11) need

     * to be factored in to complete the transformation equation of

     * this transform.  If the APPLY_SHEAR bit is also set then it

     * indicates that the scaling components are not both 0.0.  If the

     * APPLY_SHEAR bit is not also set then it indicates that the

     * scaling components are not both 1.0.  If neither the APPLY_SHEAR

     * nor the APPLY_SCALE bits are set then the scaling components

     * are both 1.0, which means that the x and y components contribute

     * to the transformed coordinate, but they are not multiplied by

     * any scaling factor.

     * @see #APPLY_IDENTITY

     * @see #APPLY_TRANSLATE

     * @see #APPLY_SHEAR

     * @see #state

     */

    static final int APPLY_SCALE = 2;

    /**

     * This constant is used for the internal state variable to indicate

     * that the shearing components of the matrix (m01 and m10) need

     * to be factored in to complete the transformation equation of this

     * transform.  The presence of this bit in the state variable changes

     * the interpretation of the APPLY_SCALE bit as indicated in its

     * documentation.

     * @see #APPLY_IDENTITY

     * @see #APPLY_TRANSLATE

     * @see #APPLY_SCALE

     * @see #state

     */

    static final int APPLY_SHEAR = 4;

    /*

     * For methods which combine together the state of two separate

     * transforms and dispatch based upon the combination, these constants

     * specify how far to shift one of the states so that the two states

     * are mutually non-interfering and provide constants for testing the

     * bits of the shifted (HI) state.  The methods in this class use

     * the convention that the state of "this" transform is unshifted and

     * the state of the "other" or "argument" transform is shifted (HI).

     */

    private static final int HI_SHIFT = 3;

    private static final int HI_IDENTITY = APPLY_IDENTITY << HI_SHIFT;

    private static final int HI_TRANSLATE = APPLY_TRANSLATE << HI_SHIFT;

    private static final int HI_SCALE = APPLY_SCALE << HI_SHIFT;

    private static final int HI_SHEAR = APPLY_SHEAR << HI_SHIFT;

    /**

     * The X coordinate scaling element of the 3x3

     * affine transformation matrix.

     *

     * @serial

     */

    double m00;

    /**

     * The Y coordinate shearing element of the 3x3

     * affine transformation matrix.

     *

     * @serial

     */

     double m10;

    /**

     * The X coordinate shearing element of the 3x3

     * affine transformation matrix.

     *

     * @serial

     */

     double m01;

    /**

     * The Y coordinate scaling element of the 3x3

     * affine transformation matrix.

     *

     * @serial

     */

     double m11;

    /**

     * The X coordinate of the translation element of the

     * 3x3 affine transformation matrix.

     *

     * @serial

     */

     double m02;

    /**

     * The Y coordinate of the translation element of the

     * 3x3 affine transformation matrix.

     *

     * @serial

     */

     double m12;

    /**

     * This field keeps track of which components of the matrix need to

     * be applied when performing a transformation.

     * @see #APPLY_IDENTITY

     * @see #APPLY_TRANSLATE

     * @see #APPLY_SCALE

     * @see #APPLY_SHEAR

     */

    transient int state;

    /**

     * This field caches the current transformation type of the matrix.

     * @see #TYPE_IDENTITY

     * @see #TYPE_TRANSLATION

     * @see #TYPE_UNIFORM_SCALE

     * @see #TYPE_GENERAL_SCALE

     * @see #TYPE_FLIP

     * @see #TYPE_QUADRANT_ROTATION

     * @see #TYPE_GENERAL_ROTATION

     * @see #TYPE_GENERAL_TRANSFORM

     * @see #TYPE_UNKNOWN

     * @see #getType

     */

    private transient int type;

    private AffineTransform(double m00, double m10,

                            double m01, double m11,

                            double m02, double m12,

                            int state) {

        this.m00 = m00;

        this.m10 = m10;

        this.m01 = m01;

        this.m11 = m11;

        this.m02 = m02;

        this.m12 = m12;

        this.state = state;

        this.type = TYPE_UNKNOWN;

    }

    /**

     * Constructs a new <code>AffineTransform</code> representing the

     * Identity transformation.

     * @since 1.2

     */

    public AffineTransform() {

        m00 = m11 = 1.0;

        // m01 = m10 = m02 = m12 = 0.0;         /* Not needed. */

        // state = APPLY_IDENTITY;              /* Not needed. */

        // type = TYPE_IDENTITY;                /* Not needed. */

    }

    /**

     * Constructs a new <code>AffineTransform</code> that is a copy of

     * the specified <code>AffineTransform</code> object.

     * @param Tx the <code>AffineTransform</code> object to copy

     * @since 1.2

     */

    public AffineTransform(AffineTransform Tx) {

        this.m00 = Tx.m00;

        this.m10 = Tx.m10;

        this.m01 = Tx.m01;

        this.m11 = Tx.m11;

        this.m02 = Tx.m02;

        this.m12 = Tx.m12;

        this.state = Tx.state;

        this.type = Tx.type;

    }

    /**

     * Constructs a new <code>AffineTransform</code> from 6 floating point

     * values representing the 6 specifiable entries of the 3x3

     * transformation matrix.

     *

     * @param m00 the X coordinate scaling element of the 3x3 matrix

     * @param m10 the Y coordinate shearing element of the 3x3 matrix

     * @param m01 the X coordinate shearing element of the 3x3 matrix

     * @param m11 the Y coordinate scaling element of the 3x3 matrix

     * @param m02 the X coordinate translation element of the 3x3 matrix

     * @param m12 the Y coordinate translation element of the 3x3 matrix

     * @since 1.2

     */

    @ConstructorProperties({ "scaleX", "shearY", "shearX", "scaleY", "translateX", "translateY" })

    public AffineTransform(float m00, float m10,

                           float m01, float m11,

                           float m02, float m12) {

        this.m00 = m00;

        this.m10 = m10;

        this.m01 = m01;

        this.m11 = m11;

        this.m02 = m02;

        this.m12 = m12;

        updateState();

    }

    /**

     * Constructs a new <code>AffineTransform</code> from an array of

     * floating point values representing either the 4 non-translation