The BitmapData.draw() Method

In many circumstances you may want to draw a DisplayObject into a Bitmap. Perhaps you want to take a 'snapshot' of a Sprite, or create a particle effect in which particles leave trails. This very important method became even more important in development for mobile as Bitmaps are easier to process for mobile devices than vector content. We discuss BitmapData.draw method with special emphasis on the second, often overlooked, transform matrix parameter. Click the screen shot below or on this link to open the SWF version in a new window:

Download

Download the well-commented source files corresponding to the how-to.

Comments and Code

Below is the Timeline code behind the example above. We left the comments within the code for greater clarity.

import flash.display.MovieClip;

import flash.display.BitmapData;

import flash.display.Bitmap;

import flash.geom.Matrix;

/*
A MovieClip has been created on the stage, stored in the Library, and linked to AS3 under the name of 'ClipToDraw'.
*/

var clip:MovieClip=new ClipToDraw();

/*
We are adding an instance of ClipToDraw, 'clip',to the Display List for comparison purposes, although the BitmapData.draw method will work regardless if 'clip' is or is not on the Display List.
*/

this.addChild(clip);

clip.x=50;

clip.y=40;

var clipWidth:Number=220;

var clipHeight:Number=160;

/*
We creating a BitmapData, 'bd1', with the same dimensions as our 'clip'. The BitmapData does not support transparency ('false' parameter), and is filled with white color. We create a Bitmap, 'bitmap1', with bitmapData 'bd1', add the Bitmap to the Display List and position it.
*/

var bd1:BitmapData=new BitmapData(clipWidth,clipHeight,false,0xFFFFFFFF);

var bitmap1:Bitmap=new Bitmap(bd1);

this.addChild(bitmap1);

bitmap1.x=100+clipWidth;

bitmap1.y=40;

/*
We call the BitmapData method 'draw'. The first and the only non-optional parameter of the method is the DisplayObject that we want to draw - in our case 'clip'. If no other parameters of 'draw' method are supplied, 'clip' will be drawn at the original scale and positioned at (0,0) of 'bitmap1'. (At runtime, 'bitmap1', is the one next to 'clip').
*/

bd1.draw(clip);

/*
To illustrate the second (optional) matrix parameter of the BitmapData.draw method, we create a second larger BitmapData object, 'bd2', filled with white, create a corresponding Bitmap, 'bitmap2', and add it to the Display List.
*/

var bd2:BitmapData=new BitmapData(460,200,false,0xFFFFFFFF);

var bitmap2:Bitmap=new Bitmap(bd2);

this.addChild(bitmap2);

bitmap2.x=70;

bitmap2.y=260;

/*
We want to draw 'clip' into 'bd2' but a version of it that is scaled down by 70%, and translated with respect to 'bd2' by 30 and 40 pixels. We create a matrix, 'mat', apply 'scale' and 'translate' to it, and draw 'clip' into 'bd2' with the matrix 'mat'. This gives the first copy of 'clip' in the white Bitmap. Note that the transform matrix, 'mat' is used only for drawing purposes and does not affect the transform matrix of 'clip'. And vice-versa clip.transform.matrix (which is all along (a=1, b=0, c=0, d=1, tx=50, ty=40) as 'clip' is positioned at (50,40) on the stage) does not affect drawing into a BitmapData.
*/

var mat:Matrix=new Matrix();

mat.scale(0.7,0.7);

mat.translate(30,40);

bd2.draw(clip,mat);

/*
Now we want another copy of 'clip' drawn into 'bd2', scaled even more, rotated, and translated. We use the same matrix, 'mat', but clear previous transformations by resetting the matrix to 'new Matrix()' that returns the identity matrix.
*/

mat=new Matrix();

mat.rotate(-45);

mat.scale(0.6,0.6);

mat.translate(260,130);

bd2.draw(clip,mat);

Note:   The BitmapData.draw method has several other parameters:

BitmapData.draw(source:IBitmapDrawable, matrix:Matrix = null,
                colorTransform:flash.geom:ColorTransform = null, blendMode:String = null,
                        clipRect:Rectangle = null, smoothing:Boolean = false):void

We used the first two: 'source' which is most typically a DisplayObject (it can also be a BitmapData), and 'matrix' which defines the transform matrix to be applied to 'source' before drawing. The other (optional) parameters define the ColorTransform to be applied before drawing, or specify a blend mode. A useful 'clipRect' parameter defines a rectangular region in the source object to be drawn in the case when you do not wish the whole source object to be drawn. We find the first two parameters most useful.

This tutorial was written by Barbara Kaskosz of flashandmath.

Back to AS3 How-Tos and Tips              Back to Flash and Math Home

We welcome your comments, suggestions, and contributions. Click the Contact Us link below and email one of us.

Adobe®, Flash®, ActionScript®, Flex® are registered trademarks of Adobe Systems Incorporated.