Matrix4x4 proposal

[Apologies if this mail comes out badly formatted - I'm using a crappy web mail app]


This is picking up from Igor's proposal [1] and completes my action (given at the W3C TP) to propose a more "native" matrix class.

Open questions:


- should include ortho() and perspective() functions? (suggestion: YES)
- should include a matrix decomposition method? (suggestion: YES)
- should include a lookAt() method? (suggestion: PROBABLY, requires vectors or multiple parameters)
- ok to remove skew? (suggestion: I HOPE SO)




// -----------------------------------------------------------------------
// CONSTRUCTORS
// -----------------------------------------------------------------------


[
    // Creates an identity matrix
    Constructor(),


    // Creates a new matrix from the value passed in (which is CSS transform string with
    // matrix() or matrix3d() - not other functions).
    Constructor(in DOMString string),
    
    // Creates a new matrix from the Float32Array value passed in (length of 6 for a 2d matrix, or 16 for a 4x4 matrix).
    Constructor(in Float32array array),


    // Creates a new matrix identical to the passed matrix.
    Constructor(in Matrix4x4 matrix),


    // Creates a new matrix from the array of 6 or 16 values passed in
    Constructor(in sequence<float> array)
]


interface Matrix4x4 {


    // 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;


    // -----------------------------------------------------------------------
    // TRANSFORMATION FUNCTIONS
    // -----------------------------------------------------------------------


    // Multiply itself by a otherMatrix, on the right (this = this * otherMatrix)
    void multiply(in Matrix4x4 otherMatrix);


    // Multiply this matrix by otherMatrix, on the right (result = this * otherMatrix)
    [Immutable] Matrix4x4 multipliedBy(in Matrix4x4 otherMatrix);


    // Multiply itself by a otherMatrix, on the left (this = otherMatrix * this)
    void leftMultiply(in Matrix4x4 otherMatrix);


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


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


    // Translate this matrix in place using the passed values.
    // Undefined or NaN parameters will use a value of 0. This allows the 3D form to used for 2D operations.
    void translate(in double x,
                   in double y,
                   in double z);


    // Return a new matrix that is this matrix translated by the passed values.
    // Undefined or NaN parameters will use a value of 0. This allows the 3D form to used for 2D operations
    [Immutable] Matrix4x4 translatedBy(in double x,
                                       in double y,
                                       in double z);


    // Scale this matrix in place using the passed values.
    // Passing undefined or NaN for scaleY uses the value of scaleX.
    // Passing undefined or NaN for scaleZ uses the value 1.0.
    void scale(in double scaleX,
               in double scaleY,
               in double scaleZ);


    // Return a new matrix that is this matrix scaled by the passed values.
    // Passing undefined or NaN for scaleY uses the value of scaleX.
    // Passing undefined or NaN for scaleZ uses the value 1.0.
    [Immutable] Matrix4x4 scaledBy(in double scaleX,
                                   in double scaleY,
                                   in double scaleZ);


    // Rotate this matrix in place using the passed values. Each parameter defines
    // an angle of rotation around the (corresponding) X, Y or Z axes.
    // Passing undefined or NaN for rotY and rotZ instead rotates around the Z axis
    // (i.e. rotX = 0, rotY = 0, rotZ = <input rotX>)
    // Input values are in radians.
    void rotate(in double rotX,
                in double rotY,
                in double rotZ);


    // Return a new matrix that is this matrix rotated by the passed values. Each parameter
    // defines an angle of rotation around the (corresponding) X, Y or Z axes.
    // Passing undefined or NaN for rotY and rotZ instead rotates around the Z axis
    // (i.e. rotX = 0, rotY = 0, rotZ = <input rotX>)
    // Input values are in radians.
    [Immutable] Matrix4x4 rotatedBy(in double rotX,
                                    in double rotY,
                                    in double rotZ);


    // Rotate this matrix in place using the passed values. The x, y and z values
    // define a vector about which the matrix is rotated.
    // The value of angle is in radians.
    void rotateAxisAngle(in double x,
                         in double y,
                         in double z,
                         in double angle);


    // Return a new matrix that is this matrix rotated using the passed values. The x, y and z values
    // define a vector about which the matrix is rotated.
    // The value of angle is in radians.
    [Immutable] Matrix4x4 rotatedByAxisAngle(in double x,
                                             in double y,
                                             in double z,
                                             in double angle);


    // -----------------------------------------------------------------------
    // CONVERSION FUNCTIONS
    // -----------------------------------------------------------------------


    // Copy the matrix elements into a Float32Array
    // Throws an exception if the input is invalid (e.g. wrong length, etc).
    void copyIntoFloat32Array(inout Float32Array array) raises (DOMException);


    // return a Float32Array (length 16) with the values [m11, m12, ...]
    Float32Array toFloat32Array();


    // Returns a string that is in the format of a CSS transform.
    // (e.g. "matrix3d(m11, m12, ...)")
    DOMString toString();
};








[1] http://lists.w3.org/Archives/Public/public-webapps/2011OctDec/0376.html