| window.runtime property | window.runtime.flash.display.BitmapData |
| Inheritance | BitmapData  Object |
| Runtime Versions: | 1.0 |
A BitmapData object contains an array of pixel data. This data can represent either a fully opaque bitmap or a transparent bitmap that contains alpha channel data. Either type of BitmapData object is stored as a buffer of 32-bit integers. Each 32-bit integer determines the properties of a single pixel in the bitmap.
Each 32-bit integer is a combination of four 8-bit channel values (from 0 to 255) that describe the alpha transparency and the red, green, and blue (ARGB) values of the pixel. (For ARGB values, the most significant byte represents the alpha channel value, followed by red, green, and blue.)
The four channels (alpha, red, green, and blue) are represented as numbers
when you use them with the BitmapData.copyChannel() method or the
DisplacementMapFilter.componentX
and DisplacementMapFilter.componentY properties, and these numbers
are represented by the following constants in the BitmapDataChannel class:
-
BitmapDataChannel.ALPHA -
BitmapDataChannel.RED -
BitmapDataChannel.GREEN -
BitmapDataChannel.BLUE
In the AIR runtime, the DockIcon, Icon, InteractiveIcon, and SystemTrayIcon classes each include
a bitmaps property that is an array of BitmapData objects that define the bitmap images
for an icon.
In AIR 1.5 and Flash Player 10, the maximum size for a BitmapData object is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels. (So, if a BitmapData object is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier and AIR 1.1 and earlier, the limitation is 2,880 pixels in height and 2,880 in width.
Calls to any method or property of a BitmapData object throw an ArgumentError error if
the BitmapData object is invalid (for example, if it has height == 0 and
width == 0) or it has been disposed of via dispose().
See also
Hide Inherited Public Properties
Show Inherited Properties| Property | Defined By | ||
|---|---|---|---|
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| height : int [read-only]
The height of the bitmap image in pixels. | BitmapData | ||
| prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | |
| rect : Rectangle [read-only]
The rectangle that defines the size and location of the bitmap image. | BitmapData | ||
| transparent : Boolean [read-only]
Defines whether the bitmap image supports per-pixel transparency. | BitmapData | ||
| width : int [read-only]
The width of the bitmap image in pixels. | BitmapData | ||
| Method | Defined By | ||
|---|---|---|---|
BitmapData(width:int, height:int, transparent:Boolean = true, fillColor:uint = 0xFFFFFFFF)
Creates a BitmapData object with a specified width and height. | BitmapData | ||
applyFilter(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, filter:BitmapFilter):void
Takes a source image and a filter object and generates the
filtered image. | BitmapData | ||
Returns a new BitmapData object that is a clone of the original instance
with an exact copy of the contained bitmap. | BitmapData | ||
colorTransform(rect:Rectangle, colorTransform:flash.geom:ColorTransform):void
Adjusts the color values in a specified area of a bitmap image by using a
ColorTransform object. | BitmapData | ||
compare(otherBitmapData:BitmapData):Object
Compares two BitmapData objects. | BitmapData | ||
copyChannel(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, sourceChannel:uint, destChannel:uint):void
Transfers data from one channel of another BitmapData object or the current
BitmapData object into a channel of the current BitmapData object. | BitmapData | ||
copyPixels(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, alphaBitmapData:BitmapData = null, alphaPoint:Point = null, mergeAlpha:Boolean = false):void
Provides a fast routine to perform pixel manipulation
between images with no stretching, rotation, or color effects. | BitmapData | ||
dispose():void
Frees memory that is used to store the BitmapData object. | BitmapData | ||
draw(source:IBitmapDrawable, matrix:Matrix = null, colorTransform:flash.geom:ColorTransform = null, blendMode:String = null, clipRect:Rectangle = null, smoothing:Boolean = false):void
Draws the source display object onto the bitmap image, using the
Flash runtime vector renderer. | BitmapData | ||
Fills a rectangular area of pixels with a specified ARGB color. | BitmapData | ||
floodFill(x:int, y:int, color:uint):void
Performs a flood fill operation on an image starting
at an (x, y) coordinate and filling with a certain color. | BitmapData | ||
Determines the destination rectangle that the applyFilter() method call affects, given a
BitmapData object, a source rectangle, and a filter object. | BitmapData | ||
getColorBoundsRect(mask:uint, color:uint, findColor:Boolean = true):Rectangle
Determines a rectangular region that either fully encloses all pixels of a specified color within the
bitmap image (if the findColor parameter is set to true) or fully encloses
all pixels that do not include the specified color (if the findColor parameter is set
to false). | BitmapData | ||
getPixel(x:int, y:int):uint
Returns an integer that represents an RGB pixel value from a BitmapData object at
a specific point (x, y). | BitmapData | ||
getPixel32(x:int, y:int):uint
Returns an ARGB color value that contains alpha channel data and RGB
data. | BitmapData | ||
Generates a byte array from a rectangular region of pixel data. | BitmapData | ||
Generates a vector array from a rectangular region of pixel data. | BitmapData | ||
| hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined. | Object | |
Computes a 256-value binary number histogram of a BitmapData object. | BitmapData | ||
hitTest(firstPoint:Point, firstAlphaThreshold:uint, secondObject:Object, secondBitmapDataPoint:Point = null, secondAlphaThreshold:uint = 1):Boolean
Performs pixel-level hit detection between one bitmap image
and a point, rectangle, or other bitmap image. | BitmapData | ||
| isPrototypeOf(theClass:Object):Boolean
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
lock():void
Locks an image so that any objects that reference the BitmapData object, such as Bitmap objects,
are not updated when this BitmapData object changes. | BitmapData | ||
merge(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, redMultiplier:uint, greenMultiplier:uint, blueMultiplier:uint, alphaMultiplier:uint):void
Performs per-channel blending from a source image to a destination image. | BitmapData | ||
noise(randomSeed:int, low:uint = 0, high:uint = 255, channelOptions:uint = 7, grayScale:Boolean = false):void
Fills an image with pixels representing random noise. | BitmapData | ||
paletteMap(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, redArray:Array = null, greenArray:Array = null, blueArray:Array = null, alphaArray:Array = null):void
Remaps the color channel values in an image that has up to four arrays of color palette data, one
for each channel. | BitmapData | ||
perlinNoise(baseX:Number, baseY:Number, numOctaves:uint, randomSeed:int, stitch:Boolean, fractalNoise:Boolean, channelOptions:uint = 7, grayScale:Boolean = false, offsets:Array = null):void
Generates a Perlin noise image. | BitmapData | ||
pixelDissolve(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, randomSeed:int = 0, numPixels:int = 0, fillColor:uint = 0):int
Performs a pixel dissolve either from a source image to a destination image or by using the same image. | BitmapData | ||
| propertyIsEnumerable(name:String):Boolean
Indicates whether the specified property exists and is enumerable. | Object | |
scroll(x:int, y:int):void
Scrolls an image by a certain (x, y) pixel amount. | BitmapData | ||
setPixel(x:int, y:int, color:uint):void
Sets a single pixel of a BitmapData object. | BitmapData | ||
setPixel32(x:int, y:int, color:uint):void
Sets the color and alpha transparency values of a single pixel of a BitmapData
object. | BitmapData | ||
Converts a byte array into a rectangular region of pixel data. | BitmapData | ||
| setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations. | Object | |
Converts a Vector into a rectangular region of pixel data. | BitmapData | ||
threshold(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, operation:String, threshold:uint, color:uint = 0, mask:uint = 0xFFFFFFFF, copySource:Boolean = false):uint
Tests pixel values in an image against a specified threshold and sets pixels that pass the test to new color values. | BitmapData | ||
| toLocaleString():String
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
| toString():String
Returns the string representation of the specified object. | Object | |
Unlocks an image so that any objects that reference the BitmapData object, such as Bitmap objects,
are updated when this BitmapData object changes. | BitmapData | ||
| valueOf():Object
Returns the primitive value of the specified object. | Object | |
height | property |
height:int [read-only] | Runtime Versions: | 1.0 |
The height of the bitmap image in pixels.
rect | property |
rect:Rectangle [read-only] | Runtime Versions: | 1.0 |
The rectangle that defines the size and location of the bitmap image. The top and left of the rectangle are 0; the width and height are equal to the width and height in pixels of the BitmapData object.
transparent | property |
transparent:Boolean [read-only] | Runtime Versions: | 1.0 |
Defines whether the bitmap image supports per-pixel transparency. You can set this value only when you construct
a BitmapData object by passing in true for the transparent parameter of the constructor. Then, after you create
a BitmapData object, you can check whether it supports per-pixel transparency by determining if the value of the
transparent property is true.
width | property |
width:int [read-only] | Runtime Versions: | 1.0 |
The width of the bitmap image in pixels.
BitmapData | () | Constructor |
public function BitmapData(width:int, height:int, transparent:Boolean = true, fillColor:uint = 0xFFFFFFFF)| Runtime Versions: | 1.0 |
Creates a BitmapData object with a specified width and height.
If you specify a value for the fillColor parameter, every pixel in the bitmap is set
to that color.
By default, the bitmap is created as transparent, unless you pass the value false
for the transparent parameter. After you create an opaque bitmap, you cannot change it to
a transparent bitmap. Every pixel in an opaque bitmap uses only 24 bits of color channel information.
If you define the bitmap as transparent, every pixel uses 32 bits of color channel information,
including an alpha transparency channel.
The maximum size of a BitmapData object depends on the SWF version:
- SWF 13+ (Flash Player 11, AIR 3) the practical limit is the amount of memory available. (The theoretical limit to width or height is the largest positive integer -- divided by 20 to allow for twips, but you will hit memory limits long before reaching this size.)
- SWF 10 (Flash Player 10, AIR 1.5) the maximum size for a BitmapData object is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels. (So, if a BitmapData object is 8,191 pixels wide, it can only be 2,048 pixels high.)
- SWF 9 (Flash Player 9, AIR 1.1) the limitation is 2,880 pixels in height and 2,880 pixels in width. If you specify a width or height value that is greater than 2880, a new instance is not created.
width:int — The width of the bitmap image in pixels.
| |
height:int — The height of the bitmap image in pixels.
| |
transparent:Boolean (default = true)true (transparent). To create a fully transparent bitmap, set the value
of the transparent parameter to true and the value of the fillColor
parameter to 0x00000000 (or to 0). Setting the transparent property to false
can result in minor improvements in rendering performance.
| |
fillColor:uint (default = 0xFFFFFFFF) |
Throws
ArgumentError — width and/or height exceed the maximum dimensions.
|
applyFilter | () | method |
public function applyFilter(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, filter:BitmapFilter):void| Runtime Versions: | 1.0 |
Takes a source image and a filter object and generates the filtered image.
This method relies on the behavior of built-in filter objects, which determine the destination rectangle that is affected by an input source rectangle.
After a filter is applied, the resulting image can be larger than the input image.
For example, if you use a BlurFilter class
to blur a source rectangle of (50,50,100,100) and a
destination point of (10,10), the area that changes in the
destination image is larger than (10,10,60,60) because of
the blurring. This happens internally during the applyFilter()
call.
If the sourceRect parameter of the sourceBitmapData parameter is
an interior region, such as (50,50,100,100) in a 200 x 200 image, the filter uses the source
pixels outside the sourceRect parameter to generate
the destination rectangle.
If the BitmapData object and the object specified as the sourceBitmapData
parameter are the same object, the application uses a temporary copy of the object to
perform the filter. For best performance, avoid this situation.
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different
BitmapData object or it can refer to the current BitmapData instance.
| |
sourceRect:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The point within the destination image (the current BitmapData
instance) that corresponds to the upper-left corner of the source rectangle.
| |
filter:BitmapFilter — The filter object that you use to perform the filtering operation. Each type
of filter has certain requirements, as follows:
|
Throws
TypeError — The sourceBitmapData, sourceRect, destPoint or filter are null.
| |
IllegalOperationError — The transparency of the BitmapData objects are not
compatible with the filter operation.
|
clone | () | method |
public function clone():BitmapData| Runtime Versions: | 1.0 |
Returns a new BitmapData object that is a clone of the original instance with an exact copy of the contained bitmap.
ReturnsBitmapData — A new BitmapData object that is identical to the original.
|
colorTransform | () | method |
public function colorTransform(rect:Rectangle, colorTransform:flash.geom:ColorTransform):void| Runtime Versions: | 1.0 |
Adjusts the color values in a specified area of a bitmap image by using a
ColorTransform object. If the rectangle
matches the boundaries of the bitmap image, this method transforms the color values of
the entire image.
Parameters
rect:Rectangle — A Rectangle object that defines the area of the image in which the
ColorTransform object is applied.
| |
colorTransform:flash.geom:ColorTransform — A ColorTransform object that describes the color transformation
values to apply.
|
Throws
TypeError — The rect or colorTransform are null.
|
See also
compare | () | method |
public function compare(otherBitmapData:BitmapData):Object| Runtime Versions: | 1.0 |
Compares two BitmapData objects. If the two BitmapData objects have the same dimensions (width and height), the method returns a new BitmapData object, in which each pixel is the "difference" between the pixels in the two source objects:
- If two pixels are equal, the difference pixel is 0x00000000.
- If two pixels have different RGB values (ignoring the alpha value), the difference
pixel is 0xRRGGBB where RR/GG/BB are the individual difference values between red, green,
and blue channels (the pixel value in the source object minus the pixel value in the
otherBitmapDataobject). Alpha channel differences are ignored in this case. - If only the alpha channel value is different, the pixel value is 0xZZFFFFFF,
where ZZ is the difference in the alpha values (the alpha value in the source object
minus the alpha value in the
otherBitmapDataobject).
For example, consider the following two BitmapData objects:
var bmd1 = new air.BitmapData(50, 50, true, 0xFFFF0000);
var bmd2 = new air.BitmapData(50, 50, true, 0xCCFFAA00);
var diffBmpData = bmd1.compare(bmd2);
Note: The colors used to fill the two BitmapData objects have slightly different RGB values
(0xFF0000 and 0xFFAA00). The result of the compare() method is a new BitmapData
object with each pixel showing the difference in the RGB values between the two bitmaps.
Consider the following two BitmapData objects, in which the RGB colors are the same, but the alpha values are different:
var bmd1 = new air.BitmapData(50, 50, true, 0xFFFFAA00);
var bmd2 = new air.BitmapData(50, 50, true, 0xCCFFAA00);
var diffBmpData = bmd1.compare(bmd2);
The result of the compare() method is a new BitmapData
object with each pixel showing the difference in the alpha values between the two bitmaps.
If the BitmapData objects are equivalent (with the same width, height, and identical pixel values), the method returns the number 0.
If the widths of the BitmapData objects are not equal, the method returns the number -3.
If the heights of the BitmapData objects are not equal, but the widths are the same, the method returns the number -4.
The following example compares two Bitmap objects with different widths (50 and 60):
var bmd1 = new air.BitmapData(100, 50, false, 0xFFFF0000);
var bmd2 = new air.BitmapData(100, 60, false, 0xFFFFAA00);
trace(bmd1.compare(bmd2)); // -4
Parameters
otherBitmapData:BitmapData — The BitmapData object to compare with the source BitmapData object.
|
Object — If the two BitmapData objects have the same dimensions (width and height), the
method returns a new BitmapData object that has the difference between the two objects (see the
main discussion). If the BitmapData objects are equivalent, the method returns the number 0.
If the widths of the BitmapData objects are not equal, the method returns the number -3.
If the heights of the BitmapData objects are not equal, the method returns the number -4.
|
Throws
TypeError — The otherBitmapData is null.
|
copyChannel | () | method |
public function copyChannel(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, sourceChannel:uint, destChannel:uint):void| Runtime Versions: | 1.0 |
Transfers data from one channel of another BitmapData object or the current BitmapData object into a channel of the current BitmapData object. All of the data in the other channels in the destination BitmapData object are preserved.
The source channel value and destination channel value can be one of following values:
BitmapDataChannel.REDBitmapDataChannel.GREENBitmapDataChannel.BLUEBitmapDataChannel.ALPHA
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different BitmapData object
or it can refer to the current BitmapData object.
| |
sourceRect:Rectangle — The source Rectangle object. To copy only channel data from a smaller area
within the bitmap, specify a source rectangle that is smaller than the overall size of the
BitmapData object.
| |
destPoint:Point — The destination Point object that represents the upper-left corner of the rectangular area
where the new channel data is placed.
To copy only channel data
from one area to a different area in the destination image, specify a point other than (0,0).
| |
sourceChannel:uint — The source channel. Use a value from the BitmapDataChannel class
(BitmapDataChannel.RED, BitmapDataChannel.BLUE,
BitmapDataChannel.GREEN, BitmapDataChannel.ALPHA).
| |
destChannel:uint — The destination channel. Use a value from the BitmapDataChannel class
(BitmapDataChannel.RED, BitmapDataChannel.BLUE,
BitmapDataChannel.GREEN, BitmapDataChannel.ALPHA).
|
Throws
TypeError — The sourceBitmapData, sourceRect or destPoint are null.
|
See also
copyPixels | () | method |
public function copyPixels(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, alphaBitmapData:BitmapData = null, alphaPoint:Point = null, mergeAlpha:Boolean = false):void| Runtime Versions: | 1.0 |
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 you 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 copy
pixels with the alpha channel data, set the mergeAlpha
property to true. By default, the mergeAlpha property is
false.
Parameters
sourceBitmapData: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:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The destination point that represents the upper-left corner of the rectangular
area where the new pixels are placed.
| |
alphaBitmapData:BitmapData (default = null) | |
alphaPoint:Point (default = null)sourceRect parameter.
| |
mergeAlpha:Boolean (default = false)true. To copy pixels with no alpha channel, set the value to
false.
|
Throws
TypeError — The sourceBitmapData, sourceRect, destPoint are null.
|
dispose | () | method |
public function dispose():void| Runtime Versions: | 1.0 |
Frees memory that is used to store the BitmapData object.
When the dispose() method is called on an image, the width and height of the image are set to 0.
All subsequent calls to methods or properties of this BitmapData instance fail, and an
exception is thrown.
BitmapData.dispose() releases the memory occupied by the actual bitmap data, immediately (a bitmap can consume up to 64 MB of memory).
After using BitmapData.dispose(), the BitmapData object is no longer usable and the Flash runtime throws an exception if you call
functions on the BitmapData object.
However, BitmapData.dispose() does not garbage collect the BitmapData object (approximately 128 bytes); the memory occupied by the actual
BitmapData object is released at the time the BitmapData object is collected by the garbage collector.
See also
draw | () | method |
public function draw(source:IBitmapDrawable, matrix:Matrix = null, colorTransform:flash.geom:ColorTransform = null, blendMode:String = null, clipRect:Rectangle = null, smoothing:Boolean = false):void| Runtime Versions: | 1.0 |
Draws the source display object onto the bitmap image, using the
Flash runtime vector renderer.
You can specify matrix, colorTransform,
blendMode, and a destination clipRect parameter to control
how the rendering performs. Optionally, you can specify whether the bitmap
should be smoothed when scaled (this works only if the source object
is a BitmapData object).
This method directly corresponds to how objects are drawn with the standard vector renderer for objects in the authoring tool interface.
The source display object does not use any of its applied transformations
for this call. It is treated as it exists in the library or
file, with no matrix transform, no color transform, and no blend
mode. To draw a display object (such as a movie clip) by using its own transform properties,
you can copy its transform property object to the transform property
of the Bitmap object that uses the BitmapData object.
This method is supported over RTMP in Adobe AIR. You can control access to streams on
Flash Media Server in a server-side script. For more information, see the Client.audioSampleAccess
and Client.videoSampleAccess properties in
Server-Side ActionScript Language Reference for Adobe Flash Media Server.
On Windows, the draw() method cannot capture SWF content embedded in an HTML
page.
The draw() method cannot capture PDF content.
Nor can it capture or SWF content embedded in HTML in which the wmode attribute is set
to "window".
Parameters
source:IBitmapDrawable — The display object or BitmapData object to draw to the BitmapData object.
(The DisplayObject and BitmapData classes implement the IBitmapDrawable interface.)
| |
matrix:Matrix (default = null)new Matrix() constructor, or pass a null value.
| |
colorTransform:flash.geom:ColorTransform (default = null)new ColorTransform()
constructor.
| |
blendMode:String (default = null) | |
clipRect:Rectangle (default = null) | |
smoothing:Boolean (default = false)matrix
parameter. The smoothing parameter only applies if the source
parameter is a BitmapData object. With smoothing set to false,
the rotated or scaled BitmapData image can appear pixelated or jagged. For example, the following
two images use the same BitmapData object for the source parameter, but the
smoothing parameter is set to true on the left and false
on the right:
Drawing a bitmap with |
Throws
ArgumentError — The source parameter is not a BitmapData
or DisplayObject object.
| |
SecurityError — The source object and (in the case of
a Sprite or MovieClip object) all of its child objects do not come from the same domain as
the caller, or are not in a content that is accessible to the caller by having called the
Security.allowDomain() method. This restriction does not apply
to AIR content in the application security sandbox.
| |
ArgumentError — The source is null or not a valid IBitmapDrawable object.
|
See also
fillRect | () | method |
public function fillRect(rect:Rectangle, color:uint):void| Runtime Versions: | 1.0 |
Fills a rectangular area of pixels with a specified ARGB color.
Parameters
rect:Rectangle — The rectangular area to fill.
| |
color:uint — The ARGB color value that fills the area. ARGB colors are often
specified in hexadecimal format; for example, 0xFF336699.
|
Throws
TypeError — The rect is null.
|
See also
floodFill | () | method |
public function floodFill(x:int, y:int, color:uint):void| Runtime Versions: | 1.0 |
Performs a flood fill operation on an image starting
at an (x, y) coordinate and filling with a certain color. The
floodFill() method is similar to the paint bucket tool in various paint
programs. The color is an ARGB color that contains alpha information and
color information.
Parameters
x:int — The x coordinate of the image.
| |
y:int — The y coordinate of the image.
| |
color:uint — The ARGB color to use as a fill.
|
generateFilterRect | () | method |
public function generateFilterRect(sourceRect:Rectangle, filter:BitmapFilter):Rectangle| Runtime Versions: | 1.0 |
Determines the destination rectangle that the applyFilter() method call affects, given a
BitmapData object, a source rectangle, and a filter object.
For example, a blur filter normally affects an area larger than the size of the original
image. A 100 x 200 pixel image that is being filtered by a default BlurFilter
instance, where blurX = blurY = 4 generates a destination rectangle of
(-2,-2,104,204).
The generateFilterRect() method lets you find out the size of this destination
rectangle in advance so that you can size the destination image appropriately before you perform a filter
operation.
Some filters clip their destination rectangle based on the source image size.
For example, an inner DropShadow does not generate a larger result than its source
image. In this API, the BitmapData object is used as the source bounds and not the
source rect parameter.
Parameters
sourceRect:Rectangle — A rectangle defining the area of the source image to use as input.
| |
filter:BitmapFilter — A filter object that you use to calculate the destination rectangle.
|
Rectangle — A destination rectangle computed by using an image, the sourceRect parameter,
and a filter.
|
Throws
TypeError — The sourceRect or filter are null.
|
getColorBoundsRect | () | method |
public function getColorBoundsRect(mask:uint, color:uint, findColor:Boolean = true):Rectangle| Runtime Versions: | 1.0 |
Determines a rectangular region that either fully encloses all pixels of a specified color within the
bitmap image (if the findColor parameter is set to true) or fully encloses
all pixels that do not include the specified color (if the findColor parameter is set
to false).
For example, if you have a source image and you want to determine the rectangle of
the image that contains a nonzero alpha channel, pass
{mask: 0xFF000000, color: 0x00000000} as parameters. If the findColor
parameter is set to true, the entire image is searched for the bounds of pixels
for which (value & mask) == color (where value is the color value
of the pixel). If the findColor parameter is set to false, the entire
image is searched for the bounds of pixels for which (value & mask) != color
(where value is the color value of the pixel). To determine white space around an
image, pass {mask: 0xFFFFFFFF, color: 0xFFFFFFFF}
to find the bounds of nonwhite pixels.
Parameters
mask:uint — A hexadecimal value, specifying the bits of the ARGB color to consider. The color
value is combined with this hexadecimal value, by using the & (bitwise AND) operator.
| |
color:uint — A hexadecimal value, specifying the ARGB color to match (if findColor
is set to true) or not to match (if findColor
is set to false).
| |
findColor:Boolean (default = true)true, returns the bounds of a color value in an image.
If the value is set to false, returns the bounds of where this color doesn't exist in an image.
|
Rectangle — The region of the image that is the specified color.
|
getPixel | () | method |
public function getPixel(x:int, y:int):uint| Runtime Versions: | 1.0 |
Returns an integer that represents an RGB pixel value from a BitmapData object at
a specific point (x, y). The getPixel() method returns an
unmultiplied pixel value. No alpha information is returned.
All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.
Parameters
x:int — The x position of the pixel.
| |
y:int — The y position of the pixel.
|
uint — A number that represents an RGB pixel value. If the (x, y) coordinates are
outside the bounds of the image, the method returns 0.
|
See also
getPixel32 | () | method |
public function getPixel32(x:int, y:int):uint| Runtime Versions: | 1.0 |
Returns an ARGB color value that contains alpha channel data and RGB
data. This method is similar to the getPixel() method, which returns an
RGB color without alpha channel data.
All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.
Parameters
x:int — The x position of the pixel.
| |
y:int — The y position of the pixel.
|
uint — A number representing an ARGB pixel value. If the (x, y) coordinates are
outside the bounds of the image, 0 is returned.
|
See also
getPixels | () | method |
public function getPixels(rect:Rectangle):ByteArray| Runtime Versions: | 1.0 |
Generates a byte array from a rectangular region of pixel data. Writes an unsigned integer (a 32-bit unmultiplied pixel value) for each pixel into the byte array.
Parameters
rect:Rectangle — A rectangular area in the current BitmapData object.
|
ByteArray — A ByteArray representing the pixels in the given Rectangle.
|
Throws
TypeError — The rect is null.
|
See also
getVector | () | method |
public function getVector(rect:Rectangle):Vector.<uint>| Runtime Versions: | 1.5 |
Generates a vector array from a rectangular region of pixel data. Returns a Vector object of unsigned integers (a 32-bit unmultiplied pixel value) for the specified rectangle.
Parameters
rect:Rectangle — A rectangular area in the current BitmapData object.
|
Vector.<uint> — A Vector representing the given Rectangle.
|
Throws
TypeError — The rect is null.
|
histogram | () | method |
public function histogram(hRect:Rectangle = null):Vector.<Vector.<Number>>| Runtime Versions: | 1.5 |
Computes a 256-value binary number histogram of a BitmapData object. This method returns a Vector object containing four Vector.<Number> instances (four Vector objects that contain Number objects). The four Vector instances represent the red, green, blue and alpha components in order. Each Vector instance contains 256 values that represent the population count of an individual component value, from 0 to 255.
Parameters
hRect:Rectangle (default = null) |
Vector.<Vector.<Number>> |
hitTest | () | method |
public function hitTest(firstPoint:Point, firstAlphaThreshold:uint, secondObject:Object, secondBitmapDataPoint:Point = null, secondAlphaThreshold:uint = 1):Boolean| Runtime Versions: | 1.0 |
Performs pixel-level hit detection between one bitmap image and a point, rectangle, or other bitmap image. A hit is defined as an overlap of a point or rectangle over an opaque pixel, or two overlapping opaque pixels. No stretching, rotation, or other transformation of either object is considered when the hit test is performed.
If an image is an opaque image, it is considered a fully opaque rectangle for this method. Both images must be transparent images to perform pixel-level hit testing that considers transparency. When you are testing two transparent images, the alpha threshold parameters control what alpha channel values, from 0 to 255, are considered opaque.
Parameters
firstPoint:Point — A position of the upper-left corner of the BitmapData image in an arbitrary coordinate space.
The same coordinate space is used in defining the secondBitmapPoint parameter.
| |
firstAlphaThreshold:uint — The smallest alpha channel value that is considered opaque for this hit test.
| |
secondObject:Object — A Rectangle, Point, Bitmap, or BitmapData object.
| |
secondBitmapDataPoint:Point (default = null)secondObject is a
BitmapData object.
| |
secondAlphaThreshold:uint (default = 1)secondObject is a
BitmapData object and both BitmapData objects are transparent.
|
Boolean — A value of true if a hit occurs; otherwise, false.
|
Throws
ArgumentError — The secondObject parameter is not a Point, Rectangle,
Bitmap, or BitmapData object.
| |
TypeError — The firstPoint is null.
|
lock | () | method |
public function lock():void| Runtime Versions: | 1.0 |
Locks an image so that any objects that reference the BitmapData object, such as Bitmap objects,
are not updated when this BitmapData object changes. To improve performance, use this method
along with the unlock() method before and after numerous calls to the
setPixel() or setPixel32() method.
See also
merge | () | method |
public function merge(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, redMultiplier:uint, greenMultiplier:uint, blueMultiplier:uint, alphaMultiplier:uint):void| Runtime Versions: | 1.0 |
Performs per-channel blending from a source image to a destination image. For each channel
and each pixel, a new value is computed based on the channel values of the source and destination
pixels. For example, in the red channel, the new value is computed as follows (where redSrc
is the red channel value for a pixel in the source image and redDest is the red channel
value at the corresponding pixel of the destination image):
new redDest = [(redSrc * redMultiplier) + (redDest * (256 - redMultiplier))] / 256;
The redMultiplier, greenMultiplier, blueMultiplier, and
alphaMultiplier values are the multipliers used for each color channel. Use a hexadecimal
value ranging from 0 to 0x100 (256) where 0 specifies the full
value from the destination is used in the result, 0x100 specifies the full value from the
source is used, and numbers in between specify a blend is used (such as 0x80 for 50%).
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different
BitmapData object, or it can refer to the current BitmapData object.
| |
sourceRect:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The point within the destination image (the current BitmapData
instance) that corresponds to the upper-left corner of the source rectangle.
| |
redMultiplier:uint — A hexadecimal uint value by which to multiply the red channel value.
| |
greenMultiplier:uint — A hexadecimal uint value by which to multiply the green channel value.
| |
blueMultiplier:uint — A hexadecimal uint value by which to multiply the blue channel value.
| |
alphaMultiplier:uint — A hexadecimal uint value by which to multiply the alpha transparency value.
|
Throws
TypeError — The sourceBitmapData, sourceRect or destPoint are null.
|
noise | () | method |
public function noise(randomSeed:int, low:uint = 0, high:uint = 255, channelOptions:uint = 7, grayScale:Boolean = false):void| Runtime Versions: | 1.0 |
Fills an image with pixels representing random noise.
Parameters
randomSeed:int — The random seed number to use. If you keep all other parameters
the same, you can generate different pseudo-random results by varying the random seed value. The noise
function is a mapping function, not a true random-number generation function, so it creates the same
results each time from the same random seed.
| |
low:uint (default = 0) | |
high:uint (default = 255) | |
channelOptions:uint (default = 7)BitmapDataChannel.RED,
BitmapDataChannel.BLUE, BitmapDataChannel.GREEN, and
BitmapDataChannel.ALPHA). You can use the logical OR
operator (|) to combine channel values.
| |
grayScale:Boolean (default = false)true, a grayscale image is created by setting
all of the color channels to the same value.
The alpha channel selection is not affected by
setting this parameter to true.
|
paletteMap | () | method |
public function paletteMap(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, redArray:Array = null, greenArray:Array = null, blueArray:Array = null, alphaArray:Array = null):void| Runtime Versions: | 1.0 |
Remaps the color channel values in an image that has up to four arrays of color palette data, one for each channel.
Flash runtimes use the following steps to generate the resulting image:
- After the red, green, blue, and alpha values are computed, they are added together using standard 32-bit-integer arithmetic.
- The red, green, blue, and alpha channel values of each pixel are extracted into separate 0 to 255 values.
These values are used to look up new color values in the appropriate array:
redArray,greenArray,blueArray, andalphaArray. Each of these four arrays should contain 256 values. - After all four of the new channel values are retrieved, they are combined into a standard ARGB value that is applied to the pixel.
Cross-channel effects can be supported with this method. Each input array can contain full 32-bit values, and no shifting occurs when the values are added together. This routine does not support per-channel clamping.
If no array is specified for a channel, the color channel is copied from the source image to the destination image.
You can use this method for a variety of effects such as general palette mapping (taking one channel and converting it to a false color image). You can also use this method for a variety of advanced color manipulation algorithms, such as gamma, curves, levels, and quantizing.
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different
BitmapData object, or it can refer to the current BitmapData instance.
| |
sourceRect:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The point within the destination image (the current BitmapData
object) that corresponds to the upper-left corner of the source rectangle.
| |
redArray:Array (default = null)redArray is not null, red = redArray[source red value]
else red = source rect value.
| |
greenArray:Array (default = null)greenArray is not null, green = greenArray[source
green value] else green = source green value.
| |
blueArray:Array (default = null)blueArray is not null, blue = blueArray[source blue
value] else blue = source blue value.
| |
alphaArray:Array (default = null)alphaArray is not null, alpha = alphaArray[source
alpha value] else alpha = source alpha value.
|
Throws
TypeError — The sourceBitmapData, sourceRect or destPoint are null.
|
perlinNoise | () | method |
public function perlinNoise(baseX:Number, baseY:Number, numOctaves:uint, randomSeed:int, stitch:Boolean, fractalNoise:Boolean, channelOptions:uint = 7, grayScale:Boolean = false, offsets:Array = null):void| Runtime Versions: | 1.0 |
Generates a Perlin noise image.
The Perlin noise generation algorithm interpolates and combines individual random noise functions (called octaves) into a single function that generates more natural-seeming random noise. Like musical octaves, each octave function is twice the frequency of the one before it. Perlin noise has been described as a "fractal sum of noise" because it combines multiple sets of noise data with different levels of detail.
You can use Perlin noise functions to simulate natural phenomena and landscapes, such as wood grain, clouds, and mountain ranges. In most cases, the output of a Perlin noise function is not displayed directly but is used to enhance other images and give them pseudo-random variations.
Simple digital random noise functions often produce images with harsh, contrasting points. This kind of harsh contrast is not often found in nature. The Perlin noise algorithm blends multiple noise functions that operate at different levels of detail. This algorithm results in smaller variations among neighboring pixel values.
Parameters
baseX:Number — Frequency to use in the x direction. For example, to generate a noise that
is sized for a 64 x 128 image, pass 64 for the baseX value.
| |
baseY:Number — Frequency to use in the y direction. For example, to generate a noise that
is sized for a 64 x 128 image, pass 128 for the baseY value.
| |
numOctaves:uint — Number of octaves or individual noise functions to combine to create this noise. Larger numbers of octaves create
images with greater detail. Larger numbers of octaves also require more processing time.
| |
randomSeed:int — The random seed number to use. If you keep all other parameters the same, you can generate different
pseudo-random results by varying the random seed value. The Perlin noise function is a mapping function, not a
true random-number generation function, so it creates the same results each time from the same random seed.
| |
stitch:Boolean — A Boolean value. If the value is true, the method attempts to smooth the transition edges of the image to create seamless textures for
tiling as a bitmap fill.
| |
fractalNoise:Boolean — A Boolean value. If the value is true, the method generates fractal noise; otherwise,
it generates turbulence. An image with turbulence has visible discontinuities in the gradient
that can make it better approximate sharper visual effects like flames and ocean waves.
| |
channelOptions:uint (default = 7)BitmapDataChannel.RED,
BitmapDataChannel.BLUE, BitmapDataChannel.GREEN, and
BitmapDataChannel.ALPHA). You can use the logical OR
operator (|) to combine channel values.
| |
grayScale:Boolean (default = false)true, a grayscale image is created by setting
each of the red, green, and blue color channels to
identical values. The alpha channel value is not affected if this value is
set to true.
| |
offsets:Array (default = null) |
pixelDissolve | () | method |
public function pixelDissolve(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, randomSeed:int = 0, numPixels:int = 0, fillColor:uint = 0):int| Runtime Versions: | 1.0 |
Performs a pixel dissolve either from a source image to a destination image or by using the same image.
Flash runtimes use a randomSeed value
to generate a random pixel dissolve. The return value
of the function must be passed in on subsequent calls to
continue the pixel dissolve until it is finished.
If the source image does not equal the destination image, pixels are copied from the source to the destination by using all of the properties. This process allows dissolving from a blank image into a fully populated image.
If the source and destination images are equal, pixels are
filled with the color parameter. This process allows dissolving away
from a fully populated image. In this mode, the destination
point parameter is ignored.
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different
BitmapData object, or it can refer to the current BitmapData instance.
| |
sourceRect:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The point within the destination image (the current BitmapData
instance) that corresponds to the upper-left corner of the source rectangle.
| |
randomSeed:int (default = 0) | |
numPixels:int (default = 0) | |
fillColor:uint (default = 0) |
int — The new random seed value to use for subsequent calls.
|
Throws
TypeError — The sourceBitmapData, sourceRect or destPoint are null.
| |
TypeError — The numPixels value is negative
|
scroll | () | method |
public function scroll(x:int, y:int):void| Runtime Versions: | 1.0 |
Scrolls an image by a certain (x, y) pixel amount. Edge regions outside the scrolling area are left unchanged.
Parameters
x:int — The amount by which to scroll horizontally.
| |
y:int — The amount by which to scroll vertically.
|
setPixel | () | method |
public function setPixel(x:int, y:int, color:uint):void| Runtime Versions: | 1.0 |
Sets a single pixel of a BitmapData object. The current alpha channel value of the image pixel is preserved during this operation. The value of the RGB color parameter is treated as an unmultiplied color value.
Note: To increase performance, when you use the setPixel() or
setPixel32() method repeatedly, call the lock() method before
you call the setPixel() or setPixel32() method, and then call
the unlock() method when you have made all pixel changes. This process prevents objects
that reference this BitmapData instance from updating until you finish making
the pixel changes.
Parameters
x:int — The x position of the pixel whose value changes.
| |
y:int — The y position of the pixel whose value changes.
| |
color:uint — The resulting RGB color for the pixel.
|
See also
setPixel32 | () | method |
public function setPixel32(x:int, y:int, color:uint):void| Runtime Versions: | 1.0 |
Sets the color and alpha transparency values of a single pixel of a BitmapData
object. This method is similar to the setPixel() method; the main difference is
that the setPixel32() method takes an
ARGB color value that contains alpha channel information.
All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.
Note: To increase performance, when you use the setPixel() or
setPixel32() method repeatedly, call the lock() method before
you call the setPixel() or setPixel32() method, and then call
the unlock() method when you have made all pixel changes. This process prevents objects
that reference this BitmapData instance from updating until you finish making
the pixel changes.
Parameters
x:int — The x position of the pixel whose value changes.
| |
y:int — The y position of the pixel whose value changes.
| |
color:uint — The resulting ARGB color for the pixel. If the bitmap is opaque
(not transparent), the alpha transparency portion of this color value is ignored.
|
See also
setPixels | () | method |
public function setPixels(rect:Rectangle, inputByteArray:ByteArray):void| Runtime Versions: | 1.0 |
Converts a byte array into a rectangular region of pixel data. For each
pixel, the ByteArray.readUnsignedInt() method is called and the return value is
written into the pixel. If the byte array ends before the full rectangle
is written, the function returns. The data in the byte array is
expected to be 32-bit ARGB pixel values. No seeking is performed
on the byte array before or after the pixels are read.
Parameters
rect:Rectangle — Specifies the rectangular region of the BitmapData object.
| |
inputByteArray:ByteArray — A ByteArray object that consists of 32-bit unmultiplied pixel values
to be used in the rectangular region.
|
Throws
EOFError — The inputByteArray object does not include enough data
to fill the area of the rect rectangle. The method fills as many pixels as
possible before throwing the exception.
| |
TypeError — The rect or inputByteArray are null.
|
See also
setVector | () | method |
public function setVector(rect:Rectangle, inputVector:Vector.<uint>):void| Runtime Versions: | 1.5 |
Converts a Vector into a rectangular region of pixel data. For each pixel, a Vector element is read and written into the BitmapData pixel. The data in the Vector is expected to be 32-bit ARGB pixel values.
Parameters
rect:Rectangle — Specifies the rectangular region of the BitmapData object.
| |
inputVector:Vector.<uint> — A Vector object that consists of 32-bit unmultiplied pixel values to be used
in the rectangular region.
|
Throws
RangeError — The vector array is not large enough to read all the pixel data.
|
threshold | () | method |
public function threshold(sourceBitmapData:BitmapData, sourceRect:Rectangle, destPoint:Point, operation:String, threshold:uint, color:uint = 0, mask:uint = 0xFFFFFFFF, copySource:Boolean = false):uint| Runtime Versions: | 1.0 |
Tests pixel values in an image against a specified threshold and sets pixels that pass the test to new color values.
Using the threshold() method, you can isolate and replace color ranges in an image and perform other
logical operations on image pixels.
The threshold() method's test logic is as follows:
- If
((pixelValue & mask) operation (threshold & mask)), then set the pixel tocolor; - Otherwise, if
copySource == true, then set the pixel to corresponding pixel value fromsourceBitmap.
The operation parameter specifies the comparison operator to use for the threshold test.
For example, by using "==" as the operation parameter, you
can isolate a specific color value in an image. Or by using {operation:
"<", mask: 0xFF000000, threshold: 0x7F000000, color:
0x00000000}, you can set all destination pixels to be fully transparent
when the source image pixel's alpha is less than 0x7F. You can use this technique
for animated transitions and other effects.
Parameters
sourceBitmapData:BitmapData — The input bitmap image to use. The source image can be a different
BitmapData object or it can refer to the current BitmapData instance.
| |
sourceRect:Rectangle — A rectangle that defines the area of the source image to use as input.
| |
destPoint:Point — The point within the destination image (the current BitmapData
instance) that corresponds to the upper-left corner of the source rectangle.
| |
operation:String — One of the following comparison operators, passed as a String: "<", "<=", ">", ">=", "==", "!="
| |
threshold:uint — The value that each pixel is tested against to see if it meets or exceeds the threshhold.
| |
color:uint (default = 0) | |
mask:uint (default = 0xFFFFFFFF) | |
copySource:Boolean (default = false)true, pixel values from the source image are copied to the destination
when the threshold test fails. If the value is false, the source image is not copied when the
threshold test fails.
|
uint — The number of pixels that were changed.
|
Throws
TypeError — The sourceBitmapData, sourceRect destPoint or operation are null.
| |
ArgumentError — The operation string is not a valid operation
|
unlock | () | method |
public function unlock(changeRect:Rectangle = null):void| Runtime Versions: | 1.0 |
Unlocks an image so that any objects that reference the BitmapData object, such as Bitmap objects,
are updated when this BitmapData object changes. To improve performance, use this method
along with the lock() method before and after numerous calls to the
setPixel() or setPixel32() method.
Parameters
changeRect:Rectangle (default = null) |
See also
Note: To test this example, do the following:
- Add the AIRAliases.js file to the project directory.
- Add an 128x128 pixel PNG image file named AIRApp_128.png file to an icons subdirectory of the project directory.
- Create an application descriptor file for the project, and test the project using ADL.
<html>
<head>
<script src="AIRAliases.js" />
<script>
function init() {
var loader = new air.Loader(); // new runtime.flash.display.Loader();
loader.contentLoaderInfo.addEventListener(air.Event.COMPLETE, imgLoaded)
var request = new air.URLRequest("icons/AIRApp_128.png");
loader.load(request);
}
function imgLoaded(event)
{
var image = air.Bitmap(loader.content);
air.NativeApplication.nativeApplication.icon.bitmaps = [image.bitmapData];
}
</script>
</head>
<body onload='init()'>
</body>
</html>
Thu Sep 29 2011, 02:34 AM -07:00