Phaser

Class: BitmapData

Phaser. BitmapData

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 one or many Images/Sprites. So if you need to dynamically create a Sprite texture then they are a good choice.

new BitmapData(game, key, width, height)

Creates a new BitmapData object.

Parameters:
Name Type Argument Default Description
game Phaser.Game

A reference to the currently running game.
key string

Internal Phaser reference key for the render texture.
width number <optional>
 100

The width of the BitmapData in pixels.
height number <optional>
 100

The height of the BitmapData in pixels.
Source:

Members

baseTexture

Properties:
Name Type Description
baseTexture PIXI.BaseTexture

The PIXI.BaseTexture.
Source:

buffer

Properties:
Name Type Description
buffer ArrayBuffer

An ArrayBuffer the same size as the context ImageData.
Source:

canvas

Properties:
Name Type Description
canvas HTMLCanvasElement

The canvas to which this BitmapData draws.
Source:

context

Properties:
Name Type Description
context CanvasRenderingContext2D

The 2d context of the canvas.
Source:

ctx

Properties:
Name Type Description
ctx CanvasRenderingContext2D

A reference to BitmapData.context.
Source:

data

Properties:
Name Type Description
data Uint8ClampedArray

A Uint8ClampedArray view into BitmapData.buffer.
Source:

dirty

Properties:
Name Type Description
dirty boolean

If dirty this BitmapData will be re-rendered.
Source:

disableTextureUpload

Properties:
Name Type Description
disableTextureUpload boolean

If disableTextureUpload is true this BitmapData will never send its image data to the GPU when its dirty flag is true.
Source:

game

Properties:
Name Type Description
game Phaser.Game

A reference to the currently running game.
Source:

height

Properties:
Name Type Description
height number

The height of the BitmapData in pixels.
Source:

imageData

Properties:
Name Type Description
imageData ImageData

The context image data.
Source:

key

Properties:
Name Type Description
key string

The key of the BitmapData in the Cache, if stored there.
Source:

pixels

Properties:
Name Type Description
pixels Uint32Array

An Uint32Array view into BitmapData.buffer.
Source:

texture

Properties:
Name Type Description
texture PIXI.Texture

The PIXI.Texture.
Source:

textureFrame

Properties:
Name Type Description
textureFrame Phaser.Frame

The Frame this BitmapData uses for rendering.
Source:

type

Properties:
Name Type Description
type number

The const type of this object.
Source:

width

Properties:
Name Type Description
width number

The width of the BitmapData in pixels.
Source:

Methods

add(object)

Updates the given objects so that they use this BitmapData as their texture. This will replace any texture they will currently have set.

Parameters:
Name Type Description
object Phaser.Sprite | Array.<Phaser.Sprite> | Phaser.Image | Array.<Phaser.Image>

Either a single Sprite/Image or an Array of Sprites/Images.
Source:

addToWorld(x, y) → {Phaser.Image}

Creates a new Phaser.Image object, assigns this BitmapData to be its texture, adds it to the world then returns it.

Parameters:
Name Type Argument Default Description
x number <optional>
 0

The x coordinate to place the image at.
y number <optional>
 0

The y coordinate to place the image at.
Source:
Returns:

The newly added Image object.

Type
Phaser.Image

alphaMask(source, mask, sourceRect, maskRect)

Draws the given image onto this BitmapData using an image as an alpha mask.

Parameters:
Name Type Argument Description
source Phaser.Sprite | Phaser.Image | Phaser.BitmapData | HTMLImage | string

The Image to draw. If you give a key it will try and find the Image in the Game.Cache.
mask Phaser.Sprite | Phaser.Image | Phaser.BitmapData | HTMLImage | string | null <optional>

The Image to use as the alpha mask. If you give a key it will try and find the Image in the Game.Cache. If you pass nothing or null it will use itself.
sourceRect Phaser.Rectangle <optional>

A Rectangle where x/y define the coordinates to draw the Source image to and width/height define the size.
maskRect Phaser.Rectangle <optional>

A Rectangle where x/y define the coordinates to draw the Mask image to and width/height define the size.
Source:

circle(x, y, radius, fillStyle)

Draws a filled Circle to the BitmapData at the given x, y coordinates and radius in size.

Parameters:
Name Type Argument Description
x number

The x coordinate to draw the Circle at. This is the center of the circle.
y number

The y coordinate to draw the Circle at. This is the center of the circle.
radius number

The radius of the Circle in pixels. The radius is half the diameter.
fillStyle string <optional>

If set the context fillStyle will be set to this value before the circle is drawn.
Source:

clear()

Clears the BitmapData context using a clearRect.

Source:

cls()

Clears the BitmapData context using a clearRect.

Source:

copyPixels(source, area, x, y)

Copies the pixels from the source image to this BitmapData based on the given area and destination.

Parameters:
Name Type Description
source Phaser.Sprite | Phaser.Image | Phaser.BitmapData | HTMLImage | string

The Image to copy from. If you give a string it will try and find the Image in the Game.Cache.
area Phaser.Rectangle

The Rectangle region to copy from the source image.
x number

The destination x coordinate to copy the image to.
y number

The destination y coordinate to copy the image to.
Source:

draw(source, x, y, width, height)

Draws the given image or Game Object to this BitmapData at the coordinates specified. You can use the optional width and height values to 'stretch' the image as it's drawn.

Parameters:
Name Type Argument Default Description
source Phaser.Sprite | Phaser.Image | Phaser.BitmapData | HTMLImage | string

The Image to draw. If you give a string it will try and find the Image in the Game.Cache.
x number <optional>
 0

The x coordinate to draw the image to.
y number <optional>
 0

The y coordinate to draw the image to.
width number <optional>

The width when drawing the image. You can use this to optionally stretch the drawn image horizontally.
height number <optional>

The height when drawing the image. You can use this to optionally stretch the drawn image vertically.
Source:

drawSprite(sprite, x, y)

DEPRECATED: Use BitmapData.draw instead.

Draws the given image to this BitmapData at the coordinates specified. If you need to only draw a part of the image use BitmapData.copyPixels instead.

Parameters:
Name Type Argument Default Description
sprite Phaser.Sprite | Phaser.Image

The Sprite to draw. Must have a loaded texture and frame.
x number <optional>
 0

The x coordinate to draw the Sprite to.
y number <optional>
 0

The y coordinate to draw the Sprite to.
Source:

extract(destination, r, g, b, a, resize, r2, g2, b2) → {Phaser.BitmapData}

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.

Parameters:
Name Type Argument Default Description
destination Phaser.BitmapData

The BitmapData that the extracts pixels will be drawn to.
r number

The red color component, in the range 0 - 255.
g number

The green color component, in the range 0 - 255.
b number

The blue color component, in the range 0 - 255.
a number <optional>
 255

The alpha color component, in the range 0 - 255 that the new pixel will be drawn at.
resize boolean <optional>
 false

Should the destination BitmapData be resized to match this one before the pixels are copied?
r2 number <optional>

An alternative red color component to be written to the destination, in the range 0 - 255.
g2 number <optional>

An alternative green color component to be written to the destination, in the range 0 - 255.
b2 number <optional>

An alternative blue color component to be written to the destination, in the range 0 - 255.
Source:
Returns:

The BitmapData that the extract pixels were drawn on.

Type
Phaser.BitmapData

fill(r, g, b, a)

Fills the BitmapData with the given color.

Parameters:
Name Type Argument Default Description
r number

The red color value, between 0 and 0xFF (255).
g number

The green color value, between 0 and 0xFF (255).
b number

The blue color value, between 0 and 0xFF (255).
a number <optional>
 1

The alpha color value, between 0 and 1.
Source:

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.
Source:
Returns:

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

Type
object

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.
Source:
Returns:

A native color value integer (format: 0xAARRGGBB)

Type
number

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?
Source:
Returns:

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

Type
object

getPixels(rect) → {ImageData}

Gets all the pixels from the region specified by the given Rectangle object.

Parameters:
Name Type Description
rect Phaser.Rectangle

The Rectangle region to get.
Source:
Returns:

Returns a ImageData object containing a Uint8ClampedArray data property.

Type
ImageData

load(source)

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 and draw. 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.

Parameters:
Name Type Description
source Phaser.Sprite | Phaser.Image | Phaser.BitmapData | string

The object that will be used to populate this BitmapData.
Source:

processPixel(callback, callbackContext, x, y, width, height)

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.
Source:

processPixelRGB(callback, callbackContext, x, y, width, height)

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.
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.
Source:

rect(x, y, width, height, fillStyle)

Draws a filled Rectangle to the BitmapData at the given x, y coordinates and width / height in size.

Parameters:
Name Type Argument Description
x number

The x coordinate of the top-left of the Rectangle.
y number

The y coordinate of the top-left of the Rectangle.
width number

The width of the Rectangle.
height number

The height of the Rectangle.
fillStyle string <optional>

If set the context fillStyle will be set to this value before the rect is drawn.
Source:

refreshBuffer(x, y, width, height)

DEPRECATED: This method will be removed in Phaser 2.1. Please use BitmapData.update instead.

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.

Parameters:
Name Type Argument Default Description
x number <optional>
 0

The x coordinate of the top-left of the image data area to grab from.
y number <optional>
 0

The y coordinate of the top-left of the image data area to grab from.
width number <optional>

The width of the image data area.
height number <optional>

The height of the image data area.
Source:

render()

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.

Source:

replaceRGB(r1, g1, b1, a1, r2, g2, b2, a2, region)

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.
region Phaser.Rectangle <optional>

The area to perform the search over. If not given it will replace over the whole BitmapData.
Source:

resize()

Resizes the BitmapData. This changes the size of the underlying canvas and refreshes the buffer.

Source:

setHSL(h, s, l, region)

Sets the hue, saturation and lightness values on every pixel in the given region, or the whole BitmapData if no region was specified.

Parameters:
Name Type Argument Default Description
h number <optional>
 null

The hue, in the range 0 - 1.
s number <optional>
 null

The saturation, in the range 0 - 1.
l number <optional>
 null

The lightness, in the range 0 - 1.
region Phaser.Rectangle <optional>

The area to perform the operation on. If not given it will run over the whole BitmapData.
Source:

setPixel(x, y, red, green, blue, alpha, immediate)

Sets the color of the given pixel to the specified red, green and blue values.

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.
red number

The red color value, between 0 and 0xFF (255).
green number

The green color value, between 0 and 0xFF (255).
blue number

The blue color value, between 0 and 0xFF (255).
alpha number

The alpha color value, between 0 and 0xFF (255).
immediate boolean <optional>
 true

If true the context.putImageData will be called and the dirty flag set.
Source:

setPixel32(x, y, red, green, blue, alpha, immediate)

Sets the color of the given pixel to the specified red, green, blue and alpha values.

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.
red number

The red color value, between 0 and 0xFF (255).
green number

The green color value, between 0 and 0xFF (255).
blue number

The blue color value, between 0 and 0xFF (255).
alpha number

The alpha color value, between 0 and 0xFF (255).
immediate boolean <optional>
 true

If true the context.putImageData will be called and the dirty flag set.
Source:

shiftHSL(h, s, l, region)

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.

Parameters:
Name Type Argument Default Description
h number <optional>
 null

The amount to shift the hue by.
s number <optional>
 null

The amount to shift the saturation by.
l number <optional>
 null

The amount to shift the lightness by.
region Phaser.Rectangle <optional>

The area to perform the operation on. If not given it will run over the whole BitmapData.
Source:

update(x, y, width, height)

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.

Parameters:
Name Type Argument Default Description
x number <optional>
 0

The x coordinate of the top-left of the image data area to grab from.
y number <optional>
 0

The y coordinate of the top-left of the image data area to grab from.
width number <optional>

The width of the image data area.
height number <optional>

The height of the image data area.
Source:
Phaser Copyright © 2012-2014 Photon Storm Ltd.
Documentation generated by JSDoc 3.3.0-dev on Fri Jul 18 2014 12:36:38 GMT+0100 (BST) using the DocStrap template.