class nape.geom.Mat23

Available on all platforms

2D Matrix class representing affine transformations: *

 * [ a  b  tx ]
 * [ c  d  ty ]
 * [ 0  0  1  ]
 * 
* * Note that in AS3, flash.geom.Matrix has 'b' and 'c' swapped! so if you are * converting between flash.geom.Matrix and nape.geom.Mat23 you should use the * methods provided to avoid any mistakes with this.

Class Fields

static function fromMatrix(matrix:Matrix):Mat23

Create a Mat23 matrix from a given AS3 flash.geom.Matrix. *

* This method should be used in preference to doing so manually * as the allocation of matrix entries to name is different and * it is easy to make this mistake! *

* This method is only available on flash and * openfl||nme targets. * *

matrix

The AS3 Matrix to create Mat23 from. This value must * not be null. *

returns

The constructed Mat23 matching AS3 Matrix.

static function rotation(angle:Float):Mat23

Construct a Mat23 representing a clockwise rotation. *

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

angle

The clockwise rotation in radians *

returns

The rotation matrix.

static function scale(sx:Float, sy:Float):Mat23

Construct a Mat23 representing a scaling *

     * [ sx  0  0 ]
     * [ 0  sy  0 ]
     * 
*

sx

The x factor of scaling. *

sy

The y factor of scaling. *

returns

The scaling matrix.

static function translation(tx:Float, ty:Float):Mat23

Construct a Mat23 representing a translation *

     * [ 1  0  tx ]
     * [ 0  1  ty ]
     * 
*

tx

The x translation. *

ty

The y translation. *

returns

The translation matrix.

Instance Fields

var a:Float

The (1,1) entry in Mat23: *

*

     * [ a  .  . ]
     * [ .  .  . ]
     * 
* * @default 1

var b:Float

The (1,2) entry in Mat23: *

*

     * [ .  b  . ]
     * [ .  .  . ]
     * 
* * @default 0

var c:Float

The (2,1) entry in Mat23: *

*

     * [ .  .  . ]
     * [ c  .  . ]
     * 
* * @default 0

var d:Float

The (2,2) entry in Mat23: *

*

     * [ .  .  . ]
     * [ .  d  . ]
     * 
* * @default 1

var determinant:Float

(readonly) The determinant of this matrix. *

* This represents the factor of change in area * for a region of the plane after transformation by matrix. *

* A determinant of 0 signifies that the matrix is not invertible. *

* A negative determinant signifies that for example, a clockwise wound * polygon would be transformed into a counter-clockwise polygon. * * @default 1

var tx:Float

The (1,3) entry in Mat23 which represents x translation *

*

     * [ .  .  tx ]
     * [ .  .  .  ]
     * 
* * @default 0

var ty:Float

The (2,3) entry in Mat23 which represents y translation *

*

     * [ .  .  .  ]
     * [ .  .  ty ]
     * 
* * @default 0

var zpp_inner:ZPP_Mat23

@private

function new(?a:Float = 1.0f, ?b:Float = 0.0f, ?c:Float = 0.0f, ?d:Float = 1.0f, ?tx:Float = 0.0f, ?ty:Float = 0.0f):Void

Construct new Mat23. *

*

     * [ a  b  tx ]
     * [ c  d  ty ]
     * 
* *

a

The (1,1) entry in matrix (default 1) *

b

The (1,2) entry in matrix (default 0) *

c

The (2,1) entry in matrix (default 0) *

d

The (2,2) entry in matrix (default 1) *

tx

The (1,3) entry in matrix (default 0) *

ty

The (2,3) entry in matrix (default 0) *

returns

The newly constructed Mat23.

function concat(matrix:Mat23):Mat23

Concatenate matrices (left-multiplication), returning new Mat23. *

* mat1.concat(mat2) is the transformation that first * performs transformation represented by mat1, followed by transformation * represented by mat2. *
* *

matrix

Matrix to concatenate with. *

returns

The result of the concatenation. *

function copy():Mat23

Produce copy of this Mat23 * *

returns

The new Mat23 representing copy of this.

function equiorthogonal():Bool

Determine if matrix is equiorthogonal *

* This is a term I invented after * failing to find an existing name. It describes that this matrix maps * circles into other circles (of not necessarigly the same radius). In * otherwords the matrix can be decomposed into a rotation, translation * and scaling of equal x/y factors. *

* This property is required for any Mat23 that is used to transform a * Circle, or any Body containing a Circle, or to transform a Debug view. *

* This is a weaker property than orthogonality which describes a mapping * to a circle of equal radius. *

* Mathematically speaking a matrix is equiorthogonal iff. * transpose(M) * M = kI for some non-zero scalar k. * *

returns

True if matrix is equiorthogonal.

function equiorthogonalise():Mat23

Equiorthogonalise matrix. *

* We do this by finding the 'nearest' orthogonal matrix; * scaling the basis vectors of matrix to their mean length * and applying an equal and opposite rotation to each basis vector to * make them perpendicular. * *

returns

A reference to this Mat23. *

function inverse():Mat23

Compute the inverse of this matrix, returning the inverse in a new * Mat23 object. *

* The inverse is such that mat.concat(mat.inverse()) is the identity * matrix, as well as mat.inverse().concat(mat) * *

returns

The inverse matrix. *

function inverseTransform(point:Vec2, ?noTranslation:Bool = false, ?weak:Bool = false):Vec2

Perform inverse transformation with Vec2, returning new Vec2. *

* The matrix inverse will be performed implicitly and should this * method be called many times for the same Mat23, it would be better * to instead compute the matrix inverse only once. *

* The new Vec2 will be allocated from the global object pool. * *

point

The Vec2 to transform. *

noTranslation

If true then the input Vec2 will be treat as a * vector instead of a point, treating the tx/ty * values of this Mat23 as though they were 0. * (default false) *

weak

If true, then the allocated Vec2 will be * automatically released to global object pool when * used as an argument to a Nape function. *

returns

The result of the transformation as a newly allocated (possibly weak) Vec2. (default false)

function orthogonal():Bool

Determine if matrix is orthogonal *

* This property describes a matrix * which maps circles into other circles of equal radius. In otherwords * the matrix can be decomposed into a rotation and a translation. *

* Mathematically speaking a matrix is orthogonal iff. * transpose(M) * M = I. * *

returns

True if matrix is orthogonal.

function orthogonalise():Mat23

Orthogonalise matrix. *

* We do this by finding the 'nearest' orthogonal matrix; * normalising the basis vectors of matrix * and applying an equal and opposite rotation to each basis vector to * make them perpendicular. * *

returns

A reference to this Mat23. *

function reset():Mat23

Reset matrix to identity. *

* Equivalent to calling setAs with default argument values. *

*

returns

A reference to this Mat23.

function set(matrix:Mat23):Mat23

Set values of matrix from another. * *

matrix

The matrix to copy values from. *

returns

A reference to this Mat23. *

function setAs(?a:Float = 1.0f, ?b:Float = 0.0f, ?c:Float = 0.0f, ?d:Float = 1.0f, ?tx:Float = 0.0f, ?ty:Float = 0.0f):Mat23

Set values of matrix from numbers. *

* So that: mat.setAs(...) is * semantically equivalent to: mat.set(new Mat23(...)) *

*

a

The value to which the (1,1) entry will be set (default 1) *

b

The value to which the (1,2) entry will be set (default 0) *

c

The value to which the (2,1) entry will be set (default 0) *

d

The value to which the (2,2) entry will be set (default 1) *

tx

The value to which the (1,3) entry will be set (default 0) *

ty

The value to which the (2,3) entry will be set (default 0) *

returns

A reference to this Mat23.

function singular():Bool

Determine if the matrix is singular. * This check is based on computing the condition number of the matrix * by the Frobenius norm, and comparing against 2 / epsilon. *

* If matrix is singular, then inversion of the matrix cannot be performed * *

returns

True, if matrix is singular.

function toMatrix(?output:Matrix = null):Matrix

Create an AS3 flash.geom.Matrix from this Mat23. *

* This method should be used in preference to doing so manually * as the allocation of matrix entries to name is different and * it is easy to make this mistake! * * @preturn The constructed AS3 Matrix.

output

If supplied, this Matrix will have its properties * populated insteaad of creating a new Matrix. *

function toString():String

@private

function transform(point:Vec2, ?noTranslation:Bool = false, ?weak:Bool = false):Vec2

Transform a Vec2 by this matrix in new Vec2. *

* The Vec2 object will be allocated form the global object pool. * *

point

The Vec2 to transform by this matrix. *

noTranslation

If true, then the input Vec2 will be treat as a * vector, rather than a point with the tx/ty values * treat as 0. (default false) *

weak

If true, then the allocated Vec2 will be * automatically released to global object pool when * used as an argument to a Nape function. *

returns

The result of the transformation as a newly allocated (possibly weak) Vec2. (default false)

function transpose():Mat23

Compute the transpose of this matrix, returning the transpose in a new * Mat23 object. *

* Technically speaking, we cannot transpose a matrix if the tx/ty values * are non-zero as the implicit bottom row of matrix must be (0, 0, 1) * so the tx/ty values of output matrix are set so that should the main * 2x2 block of the matrix be orthogonal (Representing a rotation), then * the transpose will be able to act as the matrix inverse. *

     * var mat = Mat23.rotation(..).concat(Mat23.translation(...));
     * trace(mat.concat(mat.transpose())); // Identity matrix
     * trace(mat.concat(mat.inverse())); // Identity matrix
     * 
* If the main 2x2 block of matrix is 'not' orthogonal, then the transpose * will not be equal to the inverse. * *

returns

The transposed matrix.