copyPixels (BitmapData.copyPixels method) -- Version 8

Provides a fast routine to perform pixel manipulation between images with no stretching, rotation, or color effects. This method copies a rectangular area of a source image to a rectangular area of the same size at the destination point of the destination BitmapData object.

If include the alphaBitmap and alphaPoint parameters, you can use a secondary image as an alpha source for the source image. If the source image has alpha data, both sets of alpha data are used to composite pixels from the source image to the destination image. The alphaPoint parameter is the point in the alpha image that corresponds to the upper-left corner of the source rectangle. Any pixels outside the intersection of the source image and alpha image are not copied to the destination image.

The mergeAlpha property controls whether or not the alpha channel is used when a transparent image is copied onto another transparent image. To simply copy pixels (with no alpha used), set the mergeAlpha property to false. Then all pixels are copied from source to destination. By default, the mergeAlpha property is true.

Parameters

sourceBitmap:flash.display.BitmapData - The input bitmap image from which to copy pixels. The source image can be a different BitmapData instance, or it can refer to the current BitmapData instance.

sourceRect:flash.geom.Rectangle - A rectangle that defines the area of the source image to use as input.

destPoint:flash.geom.Point - The destination point, that represents the upper-left corner of the rectangular area where the new pixels are placed.

alphaBitmap:flash.display.BitmapData [optional] - A secondary, alpha BitmapData object source.

alphaPoint:flash.geom.Point [optional] - The point in the alpha BitmapData object source that corresponds to the upper-left corner of the sourceRect parameter.

mergeAlpha:Boolean [optional] - A Boolean value:To use the alpha channel, set the value to true. To copy pixels with no alpha channel, set the value to false.

Example

The following example shows how to copy pixels from one BitmapData instance to another.

import flash.display.BitmapData;
import flash.geom.Rectangle;
import flash.geom.Point;

var bitmapData_1:BitmapData = new BitmapData(100, 80, false, 0x00CCCCCC);
var bitmapData_2:BitmapData = new BitmapData(100, 80, false, 0x00FF0000);

var mc_1:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc_1.attachBitmap(bitmapData_1, this.getNextHighestDepth());

var mc_2:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc_2.attachBitmap(bitmapData_2, this.getNextHighestDepth());
mc_2._x = 101;

mc_1.onPress = function() {
    bitmapData_2.copyPixels(bitmapData_1, new Rectangle(0, 0, 50, 80), new Point(51, 0));
}

mc_2.onPress = function() {
    bitmapData_1.copyPixels(bitmapData_2, new Rectangle(0, 0, 50, 80), new Point(51, 0));
}

Comments

reinier77 said on Jan 29, 2006 at 3:29 AM :

About mergeAlpha the doc says:

"The mergeAlpha property controls whether or not the alpha channel is used when a transparent image is copied onto another transparent image. To simply copy pixels (with no alpha used), set the mergeAlpha property to false. Then all pixels are copied from source to destination. By default, the mergeAlpha property is true."

This is not correct! By default the mergeAlpha property is FALSE!

swartz1999 said on Feb 1, 2006 at 4:56 PM :

You are right, reinier77. The default value for the mergeAlpha parameter is false. Thank you for the correction.

mrayinteractive said on Oct 13, 2006 at 6:15 AM :

Any idea when this detail will be fixed in the docs? Seems like it's been around for 10 months now, the error has been confirmed, and the solution only requires one word to be changed...might save some people a bit of time who are just getting into bitmap stuff...

Hedasul said on Nov 2, 2006 at 3:10 PM :

var mc_1:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mc_1.attachBitmap(bitmapData_1, this.getNextHighestDepth());

var mc_2:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());

Should you really be giving 2 movieclips on the same timeline identical names?

fillcell Gerra said on May 14, 2007 at 2:20 PM :

I got a problem on merging transparent bitmaps, which seems a bit difficult to explain. Please take a look on it on our server, if you can. I've uploaded it with pictures, SWF, and some source.

http://www.fillcell.com/poster

Dmitry Astretsov said on Jun 11, 2007 at 8:36 AM :

The trick is it's really FALSE by default and it actually has to be FALSE to perform operations with alpha. If you set mergeAlpha to TRUE it ignores alpha data from alphaBitmap, but when set to FALSE or omitted then it works fine.
.......
var alpha_bitmap=BitmapData.loadBitmap("mask");
var tmp_source_bitmap=new BitmapData(bmp_size.w,bmp_size.h,true,0x00000000);
tmp_source_bitmap.draw(this.Pic_mc);
this.dest_bitmap=new BitmapData(bmp_size.w,bmp_size.h,true,0xff000000);
this.Pic2_mc.attachBitmap(this.dest_bitmap,1);
this.dest_bitmap.copyPixels(tmp_source_bitmap,new Rectangle(0,0,bmp_size.w,bmp_size.h),
new Point(0,0),alpha_bitmap,new Point(0,0),false);
..............