W3C home > Mailing lists > Public > public-webapps@w3.org > October to December 2011

Proposal for a new Matrix API

From: Igor Oliveira <igor.oliveira@openbossa.org>
Date: Thu, 20 Oct 2011 10:39:56 -0400
Message-ID: <CA+Ym7xSKgmyz16rsyUFBcn8QRZ73LGEU0RG04eOQ3gyMZzO8qQ@mail.gmail.com>
To: public-webapps@w3.org
Hello,

Currently CSSMatrix and SVGMatrix has an immutable API. None of the
method calls change the Matrix, instead, it creates a new Matrix with
the changed value. It can be a problem specially when CSSMatrix is
used together with WebGL. [1]

We from WebKit are proposing a new Matrix API(simple as possible), see
below or [2], where the standard methods change the matrix(in place
operations) and additional methods (multipliedBy, scaledBy and so on)
create a new Matrix as is done by CSSMatrix and SVGMatrix.

The idea is make this class accepted where CSSMatrix and SVGMatrix is
used and be the preferred class for all Matrix needs. [3]

Any comments or suggestions?

[1] http://www.khronos.org/webgl/public-mailing-list/archives/1006/msg00171.html
[2] https://gist.github.com/1301236
[3] https://bugs.webkit.org/show_bug.cgi?id=50633

-------------------------

IDL file for WebKitMatrix:

module css {

     // Introduced in DOM Level ?:
    interface [
        CanBeConstructed,
        JSCustomConstructor,
        ConstructorParameters=1,
        Constructor(in [Optional=CallWithNullValue] DOMString cssValue),
        ConstructorRaisesException,
    ] WebKitMatrix {

        // These attributes are simple aliases for certain elements of
the 4x4 matrix
        attribute double a; // alias for m11
        attribute double b; // alias for m12
        attribute double c; // alias for m21
        attribute double d; // alias for m22
        attribute double e; // alias for m41
        attribute double f; // alias for m42

        attribute double m11;
        attribute double m12;
        attribute double m13;
        attribute double m14;
        attribute double m21;
        attribute double m22;
        attribute double m23;
        attribute double m24;
        attribute double m31;
        attribute double m32;
        attribute double m33;
        attribute double m34;
        attribute double m41;
        attribute double m42;
        attribute double m43;
        attribute double m44;

        void setMatrixValue(in [Optional=CallWithDefaultValue]
DOMString string) raises (DOMException);

        // Copy the matrix elements for a single precision float point array
        void toArray(in Float32Array array);
        // Copy the matrix elements for a double precision float point array
        void toArray(in Float64Array array);

        // Multiply this matrix by secondMatrix, on the right (result
= this * secondMatrix)
        [Immutable] WebKitMatrix multipliedBy(in
[Optional=CallWithDefaultValue] WebKitMatrix secondMatrix);

        // Multiply itself by a secondMatrix, on the right (this =
this * secondMatrix)
        void multiply(in [Optional=CallWithDefaultValue] WebKitMatrix
secondMatrix);

	// Inverse this matrix. Throw an exception if the matrix is not invertible
	void inverse() raises (DOMException)

        // Return the inverse of this matrix. Throw an exception if
the matrix is not invertible
        [Immutable] WebKitMatrix inversedBy() raises (DOMException);

        // Return this matrix translated by the passed values.
        // Passing a NaN will use a value of 0. This allows the 3D
form to used for 2D operations
        [Immutable] WebKitMatrix translatedBy(in
[Optional=CallWithDefaultValue] double x,
                                              in
[Optional=CallWithDefaultValue] double y,
                                              in
[Optional=CallWithDefaultValue] double z);

        // Translate itself using the passed values.
        // Passing a NaN will use a value of 0. This allows the 3D
form to used for 2D operations
        void translate(in [Optional=CallWithDefaultValue] double x,
                       in [Optional=CallWithDefaultValue] double y,
                       in [Optional=CallWithDefaultValue] double z);

        // Returns this matrix scaled by the passed values.
        // Passing scaleX or scaleZ as NaN uses a value of 1, but
passing scaleY of NaN
        // makes it the same as scaleX. This allows the 3D form to
used for 2D operations
        [Immutable] WebKitMatrix scaledBy(in
[Optional=CallWithDefaultValue] double scaleX,
                                          in
[Optional=CallWithDefaultValue] double scaleY,
                                          in
[Optional=CallWithDefaultValue] double scaleZ);

        // Scale itself using the passed values.
        // Passing scaleX or scaleZ as NaN uses a value of 1, but
passing scaleY of NaN
        // makes it the same as scaleX. This allows the 3D form to
used for 2D operations
        void scale(in [Optional=CallWithDefaultValue] double scaleX,
                   in [Optional=CallWithDefaultValue] double scaleY,
                   in [Optional=CallWithDefaultValue] double scaleZ);

        // Returns this matrix rotated by the passed values.
        // If rotY and rotZ are NaN, rotate about Z (rotX=0,
rotateY=0, rotateZ=rotX).
        // Otherwise use a rotation value of 0 for any passed NaN.
        [Immutable] WebKitMatrix rotatedBy(in
[Optional=CallWithDefaultValue] double rotX,
                                           in
[Optional=CallWithDefaultValue] double rotY,
                                           in
[Optional=CallWithDefaultValue] double rotZ);

        // Rotate itself using the passed values.
        // If rotY and rotZ are NaN, rotate about Z (rotX=0,
rotateY=0, rotateZ=rotX).
        // Otherwise use a rotation value of 0 for any passed NaN.
        void rotate(in [Optional=CallWithDefaultValue] double rotX,
                    in [Optional=CallWithDefaultValue] double rotY,
                    in [Optional=CallWithDefaultValue] double rotZ);

        // Returns this matrix rotated about the passed axis by the
passed angle.
        // Passing a NaN will use a value of 0. If the axis is (0,0,0)
use a value
        // of (0,0,1).
        [Immutable] WebKitMatrix rotatedAxisAngleBy(in
[Optional=CallWithDefaultValue] double x,
                                                    in
[Optional=CallWithDefaultValue] double y,
                                                    in
[Optional=CallWithDefaultValue] double z,
                                                    in
[Optional=CallWithDefaultValue] double angle);

        // Rotate itself using the passed axis by the passed angle.
        void rotateAxisAngle(in [Optional=CallWithDefaultValue] double x,
                             in [Optional=CallWithDefaultValue] double y,
                             in [Optional=CallWithDefaultValue] double z,
                             in [Optional=CallWithDefaultValue] double angle);

        // Returns this matrix skewed along the X axis by the passed values.
        // Passing a NaN will use a value of 0.
        [Immutable] WebKitMatrix skewedXBy(in
[Optional=CallWithDefaultValue] double angle);

        // Skew itself along the X axis using the passed values.
        // Passing a NaN will use a value of 0.
        void skewX(in [Optional=CallWithDefaultValue] double angle);

        // Returns this matrix skewed along the Y axis by the passed values.
        // Passing a NaN will use a value of 0.
        [Immutable] WebKitMatrix skewedYBy(in
[Optional=CallWithDefaultValue] double angle);

        // Skew itself along the Y axis using the passed values.
        // Passing a NaN will use a value of 0.
        void skewY(in [Optional=CallWithDefaultValue] double angle);

        [DontEnum] DOMString toString();
    };
}
Received on Thursday, 20 October 2011 20:29:54 GMT

This archive was generated by hypermail 2.3.1 : Tuesday, 26 March 2013 18:49:48 GMT