/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

package org.w3c.dom.svg;

import org.w3c.dom.svg.SVGException;

import org.w3c.dom.DOMException;

/**

 * This interface represents an "SVGMatrix" datatype, identified by an affine transform.

 * It can be used to read and modify the values of transform attribute as per SVG specification.

 * Note that the mTranslate, mMultiply, mScale and mRotate methods in this interface

 * mutate the SVGMatrix object and return a reference to the SVGMatrix instance itself, after

 * performing the necessary matrix operation.

 * <p>This matrix transforms source coordinates (x, y) into destination coordinates (x', y') by

 * considering them to be a column vector and multiplying the coordinate vector by the matrix

 * according to the following process:</p>

 *

 * <p>

 * <pre>

 *  [ x' ]    [  a  c  e  ]   [ x ]    [ a.x + c.y + e ]

 *  [ y' ] =  [  b  d  f  ]   [ y ] =  [ b.x + d.y + f ]

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

 * </pre>

 * </p>

 */

public interface SVGMatrix

{

    /**

     * Returns a component of the matrix by component's zero-based index. <code>getComponent(0)</code> is a, <code>getComponent(1)</code> is b, etc.

     *

     * @param index the index of the matrix component to retrieve.

     * @return the component for the specified index.

     * @throws DOMException  - INDEX_SIZE_ERR if the <code>index</code> is invalid.

     */

    public float getComponent(int index)

    throws DOMException;

    /**

     * Performs matrix multiplication. This matrix is post-multiplied by another matrix, returning the resulting current matrix.

     *

     * @param secondMatrix the matrix to post-multiply with.

     * @return the resulting current matrix after post-multiplication.

     * @throws NullPointerException  - if secondMatrix is null.

     */

    public SVGMatrix mMultiply(SVGMatrix secondMatrix);

    /**

     * Returns a new instance of SVGMatrix containing the inverse of the current matrix.

     *

     * @return the inverse of the current matrix.

     * @throws SVGException  - SVG_MATRIX_NOT_INVERTABLE when determinant of this matrix is zero.

     */

    public SVGMatrix inverse()

    throws SVGException;

    /**

     * Post-multiplies a translation transformation on the current matrix and returns the resulting current matrix.

     * This is equivalent to calling <code>multiply(T)</code>, where <code>T</code> is an

     * <code>SVGMatrix</code> object represented by the following

     * matrix:

     *

     * <p>

     * <pre>

     *      [   1    0    x  ]

     *      [   0    1    y  ]

     *      [   0    0    1   ]

     * </pre>

     * </p>

     *

     * @param x the distance by which coordinates are translated

     * in the X axis direction.

     * @param y the distance by which coordinates are translated

     * in the Y axis direction.

     * @return the resulting current matrix after post-multiplication.

     */

    public SVGMatrix mTranslate(float x, float y);

    /**

     * Post-multiplies a uniform scale transformation on the current matrix and returns the resulting current matrix.

     * This is equivalent to calling <code>multiply(S)</code>, where <code>S</code> is an <code>SVGMatrix</code>

     * object represented by the following matrix:

     *

     * <p>

     * <pre>

     *      [   scaleFactor      0          0   ]

     *      [   0          scaleFactor      0   ]

     *      [   0                0          1   ]

     * </pre>

     * </p>

     *

     * @param scaleFactor the factor by which coordinates are scaled along the

     * X and Y axis.

     * @return the resulting current matrix after post-mutiplication.

     */

    public SVGMatrix mScale(float scaleFactor);

    /**

     * Post-multiplies a rotation transformation on the current matrix and returns the resulting current matrix.

     * This is equivalent to calling <code>multiply(R)</code>, where <code>R</code> is an

     * <code>SVGMatrix</code> object represented by the following matrix:

     *

     * <p>

     * <pre>

     *      [ cos(angle) -sin(angle) 0 ]

     *      [ sin(angle)  cos(angle) 0 ]

     *      [ 0           0          1 ]

     * </pre>

     * </p>

     *

     * @param angle the angle of rotation in degrees.

     * @return the resulting current matrix after post-multiplication.

     */

    public SVGMatrix mRotate(float angle);

}