Programming ActionScript 3.0 > Flash Player APIs > Working with Geometry > Using Matrix objects

Using Matrix objects

The Matrix class represents a transformation matrix that determines how to map points from one coordinate space to another. You can perform various graphical transformations on a display object by setting the properties of a Matrix object, applying that Matrix object to the matrix property of a Transform object, and then applying that Transform object as the transform property of the display object. These transformation functions include translation (x and y repositioning), rotation, scaling, and skewing.

Subtopics

Defining Matrix objects
Defining a Matrix object for use with a gradient

Defining Matrix objects

Although you could define a matrix by directly adjusting the properties (a, b, c, d, tx, ty) of a Matrix object, it is easier to use the createBox() method. This method includes parameters that let you directly define the scaling, rotation, and translation effects of the resulting matrix. For example, the following code creates a Matrix object that has the effect of scaling an object horizontally by 2.0, scaling it vertically by 3.0, rotating it by 45 degrees, moving (translating) it 10 pixels to the right, and moving it 20 pixels down:

var matrix:Matrix = new Matrix();
var scaleX:Number = 2.0;
var scaleY:Number = 3.0;
var rotation:Number = 2 * Math.PI * (45 / 360);
var tx:Number = 10;
var ty:Number = 20;
matrix.createBox(scaleX, scaleY, rotation, tx, ty);

You can also adjust the scaling, rotation, and translation effects of a Matrix object by using the scale(), rotate(), and translate() methods. Note that these methods combine with the values of the existing Matrix object. For instance, the following code sets a Matrix object that scales an object by a factor of 4 and rotates it 60 degrees, since the scale() and rotate() methods are called twice: 

var matrix:Matrix = new Matrix();
var rotation:Number = 2 * Math.PI * (30 / 360); // 30˚
var scaleFactor:Number = 2;
matrix.scale(scaleFactor, scaleFactor);
matrix.rotate(rotation);
matrix.scale(scaleX, scaleY);
matrix.rotate(rotation);

myDisplayObject.transform.matrix = matrix;

To apply a skew transformation to a Matrix object, adjust its b or c property. Adjusting the b property skews the matrix vertically, and adjusting the c property skews the matrix horizontally. The following code skews the myMatrix Matrix object vertically by a factor of 2:

var skewMatrix:Matrix = new Matrix();
skewMatrix.b = Math.tan(2);
myMatrix.concat(skewMatrix);

You can apply a Matrix transformation to the transform property of a display object. For example, the following code applies a matrix transformation to a display object named myDisplayObject: 

var matrix:Matrix = myDisplayObject.transform.matrix;
var scaleFactor:Number = 2;
var rotation:Number = 2 * Math.PI * (60 / 360); // 60˚
matrix.scale(scaleFactor, scaleFactor);
matrix.rotate(rotation);

myDisplayObject.transform.matrix = matrix;

The first line sets a Matrix object to the existing transformation matrix used by the myDisplayObject display object (the matrix property of the transformation property of the myDisplayObject display object). This way, the Matrix class methods that you call will have a cumulative effect on the display object's existing position, scale, and rotation.

NOTE

 

The ColorTransform class is also included in the flash.geometry package. This class is used to set the colorTransform property of a Transform object. Since it does not apply any sort of geometrical transformation, it is not discussed in this chapter. For more information, see the ColorTransform class in the ActionScript 3.0 Language Reference.

Defining a Matrix object for use with a gradient

You use the beginGradientFill() and lineGradientStyle() methods of the flash.display.Graphics class to define gradients for use in shapes. When you define a gradient, you supply a matrix as one of the parameters of these methods.

The easiest way to define the matrix is by using the createGradientBox() method, which defines a rectangle that is used to define the gradient. You define the scale, rotation, and position of the gradient by using the parameters passed to the createGradientBox() method.

For example, consider a gradient with the following characteristics:

The following examples show gradients in which the rotation parameter of the createGradientBox() method differs as indicated, but all other settings stay the same:

width = 100;
height = 100;
rotation = 0;
tx = 0;
ty = 0;


Square with a gradient which starts green on the left edge and fades to blue on the right edge.

width = 100;
height = 100;
rotation = Math.PI/4; // 45˚
tx = 0;
ty = 0;


Square with a gradient which starts green on the top-left corner and fades to blue on the bottom-right corner.

width = 100;
height = 100;
rotation = Math.PI/2; // 90˚
tx = 0;
ty = 0;


Square with a gradient which starts green on the top edge and fades to blue on the bottom edge.

The following examples show the effects on a green-to-blue linear gradient in which the rotation, tx, and ty parameters of the createGradientBox() method differ as indicated, but all other settings stay the same:

width = 50;
height = 100;
rotation = 0;
tx = 0;
ty = 0;


Square with a gradient which starts green on the left edge and fades to blue on the right edge. The actual gradient covers the left half of the square; the right half of the square is solid blue.

width = 50;
height = 100;
rotation = 0
tx = 50;
ty = 0;


Square with a gradient which starts green on the left edge and fades to blue on the right edge. The gradient actually begins in the center of the square, and fades across the right half of the square.

width = 100;
height = 50;
rotation = Math.PI/2; // 90˚
tx = 0;
ty = 0;


Square with a gradient which starts green on the top edge and fades to blue on the bottom edge. The actual gradient covers the top half of the square; the bottom half of the square is solid blue.

width = 100;
height = 50;
rotation = Math.PI/2; // 90˚
tx = 0;
ty = 50;


Square with a gradient which starts green on the top edge and fades to blue on the bottom edge. The actual gradient covers the bottom half of the square; the top half of the square is solid green.

The width, height, tx, and ty parameters of the createGradientBox() method affect the size and position of a radial gradient fill as well, as the following example shows:

width = 50;
height = 100;
rotation = 0;
tx = 25;
ty = 0;


Image showing a green radial gradient centered on a blue square. The gradient is elliptical, covering the square from top to bottom but only the middle half of the square horizontally.

The following code produces the last radial gradient illustrated:

import flash.display.Shape;
import flash.display.GradientType;
import flash.geom.Matrix;

var type:String = GradientType.RADIAL;
var colors:Array = [0x00FF00, 0x000088];
var alphas:Array = [1, 1];
var ratios:Array = [0, 255];
var spreadMethod:String = SpreadMethod.PAD;
var interp:String = InterpolationMethod.LINEAR_RGB;
var focalPtRatio:Number = 0;

var matrix:Matrix = new Matrix();
var boxWidth:Number = 50;
var boxHeight:Number = 100;
var boxRotation:Number = Math.PI/2; // 90˚
var tx:Number = 25;
var ty:Number = 0;
matrix.createGradientBox(boxWidth, boxHeight, boxRotation, tx, ty);

var square:Shape = new Shape;
square.graphics.beginGradientFill(type, 
                            colors,
                            alphas,
                            ratios, 
                            matrix, 
                            spreadMethod, 
                            interp, 
                            focalPtRatio);
square.graphics.drawRect(0, 0, 100, 100);
addChild(square);

Flex 2.01

Take a survey