1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 package org.w3c.dom.svg;

    18 

    19 import org.w3c.dom.svg.SVGException;

    20 import org.w3c.dom.DOMException;

    21 

    22 /**

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

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

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

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

    27  * performing the necessary matrix operation.

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

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

    30  * according to the following process:</p>

    31  *

    32  * <p>

    33  * <pre>

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

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

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

    37  * </pre>

    38  * </p>

    39  */

    40 public interface SVGMatrix

    41 {

    42 

    43     /**

    44      * 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.

    45      *

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

    47      * @return the component for the specified index.

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

    49      */

    50     public float getComponent(int index)

    51     throws DOMException;

    52 

    53     /**

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

    55      *

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

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

    58      * @throws NullPointerException  - if secondMatrix is null.

    59      */

    60     public SVGMatrix mMultiply(SVGMatrix secondMatrix);

    61 

    62     /**

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

    64      *

    65      * @return the inverse of the current matrix.

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

    67      */

    68     public SVGMatrix inverse()

    69     throws SVGException;

    70 

    71     /**

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

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

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

    75      * matrix:

    76      *

    77      * <p>

    78      * <pre>

    79      *      [   1    0    x  ]

    80      *      [   0    1    y  ]

    81      *      [   0    0    1   ]

    82      * </pre>

    83      * </p>

    84      *

    85      * @param x the distance by which coordinates are translated

    86      * in the X axis direction.

    87      * @param y the distance by which coordinates are translated

    88      * in the Y axis direction.

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

    90      */

    91     public SVGMatrix mTranslate(float x, float y);

    92 

    93     /**

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

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

    96      * object represented by the following matrix:

    97      *

    98      * <p>

    99      * <pre>

   100      *      [   scaleFactor      0          0   ]

   101      *      [   0          scaleFactor      0   ]

   102      *      [   0                0          1   ]

   103      * </pre>

   104      * </p>

   105      *

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

   107      * X and Y axis.

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

   109      */

   110     public SVGMatrix mScale(float scaleFactor);

   111 

   112     /**

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

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

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

   116      *

   117      * <p>

   118      * <pre>

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

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

   121      *      [ 0           0          1 ]

   122      * </pre>

   123      * </p>

   124      *

   125      * @param angle the angle of rotation in degrees.

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

   127      */

   128     public SVGMatrix mRotate(float angle);

   129 }