Constructor

new BitmapData(game, key, width, height)

A BitmapData object contains a Canvas element to which you can draw anything you like via normal Canvas context operations.
A single BitmapData can be used as the texture for one or many Images/Sprites.
So if you need to dynamically create a Sprite texture then they are a good choice.

height : number

imageData :ImageData

The context image data.
Please note that a call to BitmapData.draw() or BitmapData.copy() does not update immediately this property for performance reason. Use BitmapData.update() to do so.
This property is updated automatically after the first game loop, according to the dirty flag property.

The object to be used as the mask. If you give a string it will try and find the Image in the Game.Cache first. This is quite expensive so try to provide the image itself. If you don't provide a mask it will use this BitmapData as the mask.

Copies a rectangular area from the source object to this BitmapData. If you give null as the source it will copy from itself.
You can optionally resize, translate, rotate, scale, alpha or blend as it's drawn.
All rotation, scaling and drawing takes place around the regions center point by default, but can be changed with the anchor parameters.
Note that the source image can also be this BitmapData, which can create some interesting effects.

This method has a lot of parameters for maximum control.
You can use the more friendly methods like copyRect and draw to avoid having to remember them all.

Draws the given Phaser.Sprite, Phaser.Image or Phaser.Text to this BitmapData at the coordinates specified.
You can use the optional width and height values to 'stretch' the sprite as it is drawn. This uses drawImage stretching, not scaling.
When drawing it will take into account the Sprites rotation, scale and alpha values.

Returns

Draws the Game Object or Group to this BitmapData and then recursively iterates through all of its children.

If a child has an exists property then it (and its children) will be only be drawn if exists is true.

The children will be drawn at their x and y world space coordinates. If this is outside the bounds of the BitmapData
they won't be drawn. Depending on your requirements you may need to resize the BitmapData in advance to match the
bounds of the top-level Game Object.

When drawing it will take into account the child's world rotation, scale and alpha values.

It's perfectly valid to pass in game.world as the parent object, and it will iterate through the entire display list.

Note: If you are trying to grab your entire game at the start of a State then you should ensure that at least 1 full update
has taken place before doing so, otherwise all of the objects will render with incorrect positions and scales. You can
trigger an update yourself by calling stage.updateTransform() before calling drawFull.

Returns

Draws the immediate children of a Phaser.Group to this BitmapData.
Children are only drawn if they have their exists property set to true.
The children will be drawn at their x and y world space coordinates. If this is outside the bounds of the BitmapData they won't be drawn.
When drawing it will take into account the child's rotation, scale and alpha values.
No iteration takes place. Groups nested inside other Groups will not be iterated through.

Returns

Scans this BitmapData for all pixels matching the given r,g,b values and then draws them into the given destination BitmapData.
The original BitmapData remains unchanged.
The destination BitmapData must be large enough to receive all of the pixels that are scanned unless the 'resize' parameter is true.
Although the destination BitmapData is returned from this method, it's actually modified directly in place, meaning this call is perfectly valid:
picture.extract(mask, r, g, b)
You can specify optional r2, g2, b2 color values. If given the pixel written to the destination bitmap will be of the r2, g2, b2 color.
If not given it will be written as the same color it was extracted. You can provide one or more alternative colors, allowing you to tint
the color during extraction.

Returns

Scans the BitmapData and calculates the bounds. This is a rectangle that defines the extent of all non-transparent pixels.
The rectangle returned will extend from the top-left of the image to the bottom-right, excluding transparent pixels.

Returns

getFirstPixel(direction) → {object}

Scans the BitmapData, pixel by pixel, until it encounters a pixel that isn't transparent (i.e. has an alpha value > 0).
It then stops scanning and returns an object containing the color of the pixel in r, g and b properties and the location in the x and y properties.

The direction parameter controls from which direction it should start the scan:

0 = top to bottom
1 = bottom to top
2 = left to right
3 = right to left

Parameters

Name

Type

Argument

Default

Description

direction

number

<optional>

0

The direction in which to scan for the first pixel. 0 = top to bottom, 1 = bottom to top, 2 = left to right and 3 = right to left.

Returns

object
-

Returns an object containing the color of the pixel in the r, g and b properties and the location in the x and y properties.

getPixel(x, y, out) → {object}

Get the color of a specific pixel in the context into a color object.
If you have drawn anything to the BitmapData since it was created you must call BitmapData.update to refresh the array buffer,
otherwise this may return out of date color values, or worse - throw a run-time error as it tries to access an array element that doesn't exist.

Parameters

Name

Type

Argument

Description

x

number

The x coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

y

number

The y coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

out

object

<optional>

An object into which 4 properties will be created: r, g, b and a. If not provided a new object will be created.

Returns

object
-

An object with the red, green, blue and alpha values set in the r, g, b and a properties.

getPixel32(x, y) → {number}

Get the color of a specific pixel including its alpha value.
If you have drawn anything to the BitmapData since it was created you must call BitmapData.update to refresh the array buffer,
otherwise this may return out of date color values, or worse - throw a run-time error as it tries to access an array element that doesn't exist.
Note that on little-endian systems the format is 0xAABBGGRR and on big-endian the format is 0xRRGGBBAA.

Parameters

Name

Type

Description

x

number

The x coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

y

number

The y coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

Returns

getPixelRGB(x, y, out, hsl, hsv) → {object}

Get the color of a specific pixel including its alpha value as a color object containing r,g,b,a and rgba properties.
If you have drawn anything to the BitmapData since it was created you must call BitmapData.update to refresh the array buffer,
otherwise this may return out of date color values, or worse - throw a run-time error as it tries to access an array element that doesn't exist.

Parameters

Name

Type

Argument

Default

Description

x

number

The x coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

y

number

The y coordinate of the pixel to be set. Must lay within the dimensions of this BitmapData.

out

object

<optional>

An object into which 3 properties will be created: r, g and b. If not provided a new object will be created.

hsl

boolean

<optional>

false

Also convert the rgb values into hsl?

hsv

boolean

<optional>

false

Also convert the rgb values into hsv?

Returns

object
-

An object with the red, green and blue values set in the r, g and b properties.

Returns

Takes the given Game Object, resizes this BitmapData to match it and then draws it into this BitmapDatas canvas, ready for further processing.
The source game object is not modified by this operation.
If the source object uses a texture as part of a Texture Atlas or Sprite Sheet, only the current frame will be used for sizing.
If a string is given it will assume it's a cache key and look in Phaser.Cache for an image key matching the string.

Returns

Scans through the area specified in this BitmapData and sends the color for every pixel to the given callback along with its x and y coordinates.
Whatever value the callback returns is set as the new color for that pixel, unless it returns the same color, in which case it's skipped.
Note that the format of the color received will be different depending on if the system is big or little endian.
It is expected that your callback will deal with endianess. If you'd rather Phaser did it then use processPixelRGB instead.
The callback will also be sent the pixels x and y coordinates respectively.

Parameters

Name

Type

Argument

Default

Description

callback

function

The callback that will be sent each pixel color to be processed.

callbackContext

object

The context under which the callback will be called.

x

number

<optional>

0

The x coordinate of the top-left of the region to process from.

y

number

<optional>

0

The y coordinate of the top-left of the region to process from.

width

number

<optional>

The width of the region to process.

height

number

<optional>

The height of the region to process.

Returns

Scans through the area specified in this BitmapData and sends a color object for every pixel to the given callback.
The callback will be sent a color object with 6 properties: { r: number, g: number, b: number, a: number, color: number, rgba: string }.
Where r, g, b and a are integers between 0 and 255 representing the color component values for red, green, blue and alpha.
The color property is an Int32 of the full color. Note the endianess of this will change per system.
The rgba property is a CSS style rgba() string which can be used with context.fillStyle calls, among others.
The callback will also be sent the pixels x and y coordinates respectively.
The callback must return either false, in which case no change will be made to the pixel, or a new color object.
If a new color object is returned the pixel will be set to the r, g, b and a color values given within it.

Parameters

Name

Type

Argument

Default

Description

callback

function

The callback that will be sent each pixel color object to be processed.

Returns

If the game is running in WebGL this will push the texture up to the GPU if it's dirty.
This is called automatically if the BitmapData is being used by a Sprite, otherwise you need to remember to call it in your render function.
If you wish to suppress this functionality set BitmapData.disableTextureUpload to true.

Returns

Replaces all pixels matching one color with another. The color values are given as two sets of RGBA values.
An optional region parameter controls if the replacement happens in just a specific area of the BitmapData or the entire thing.

Parameters

Name

Type

Argument

Description

r1

number

The red color value to be replaced. Between 0 and 255.

g1

number

The green color value to be replaced. Between 0 and 255.

b1

number

The blue color value to be replaced. Between 0 and 255.

a1

number

The alpha color value to be replaced. Between 0 and 255.

r2

number

The red color value that is the replacement color. Between 0 and 255.

g2

number

The green color value that is the replacement color. Between 0 and 255.

b2

number

The blue color value that is the replacement color. Between 0 and 255.

a2

number

The alpha color value that is the replacement color. Between 0 and 255.

Returns

Sets the shadow properties of this BitmapDatas context which will affect all draw operations made to it.
You can cancel an existing shadow by calling this method and passing no parameters.
Note: At the time of writing (October 2014) Chrome still doesn't support shadowBlur used with drawImage.

Parameters

Name

Type

Argument

Default

Description

color

string

The color of the shadow, given in a CSS format, i.e. #000000 or rgba(0,0,0,1). If null or undefined the shadow will be reset.

blur

number

<optional>

5

The amount the shadow will be blurred by. Low values = a crisp shadow, high values = a softer shadow.

x

number

<optional>

10

The horizontal offset of the shadow in pixels.

y

number

<optional>

10

The vertical offset of the shadow in pixels.

Returns

Shifts any or all of the hue, saturation and lightness values on every pixel in the given region, or the whole BitmapData if no region was specified.
Shifting will add the given value onto the current h, s and l values, not replace them.
The hue is wrapped to keep it within the range 0 to 1. Saturation and lightness are clamped to not exceed 1.

Returns

Draws text to the BitmapData in the given font and color.
The default font is 14px Courier, so useful for quickly drawing debug text.
If you need to do a lot of font work to this BitmapData we'd recommend implementing your own text draw method.

Parameters

Name

Type

Argument

Default

Description

text

string

The text to write to the BitmapData.

x

number

The x coordinate of the top-left of the text string.

y

number

The y coordinate of the top-left of the text string.

font

string

<optional>

'14px Courier'

The font. This is passed directly to Context.font, so anything that can support, this can.

Returns

This re-creates the BitmapData.imageData from the current context.
It then re-builds the ArrayBuffer, the data Uint8ClampedArray reference and the pixels Int32Array.
If not given the dimensions defaults to the full size of the context.