# 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:
    - gameobjects/BitmapData.js, line 21

### Members

#### baseTexture

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `baseTexture` | PIXI.BaseTexture | The PIXI.BaseTexture.

  Source:
    - gameobjects/BitmapData.js, line 103

#### buffer

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `buffer` | ArrayBuffer | An ArrayBuffer the same size as the context ImageData.

  Source:
    - gameobjects/BitmapData.js, line 83

#### canvas

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `canvas` | HTMLCanvasElement | The canvas to which this BitmapData draws.

  Source:
    - gameobjects/BitmapData.js, line 50

#### context

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `context` | CanvasRenderingContext2D | The 2d context of the canvas.

  Source:
    - gameobjects/BitmapData.js, line 56

#### ctx

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `ctx` | CanvasRenderingContext2D | A reference to BitmapData.context.

  Source:
    - gameobjects/BitmapData.js, line 61

#### data

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `data` | Uint8ClampedArray | A Uint8ClampedArray view into BitmapData.buffer.

  Source:
    - gameobjects/BitmapData.js, line 71

#### dirty

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `dirty` | boolean | If dirty this BitmapData will be re-rendered.

  Source:
    - gameobjects/BitmapData.js, line 131

#### 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:
    - gameobjects/BitmapData.js, line 126

#### game

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `game` | Phaser.Game | A reference to the currently running game.

  Source:
    - gameobjects/BitmapData.js, line 29

#### height

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `height` | number | The height of the BitmapData in pixels.

  Source:
    - gameobjects/BitmapData.js, line 44

#### imageData

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `imageData` | ImageData | The context image data.

  Source:
    - gameobjects/BitmapData.js, line 66

#### key

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `key` | string | The key of the BitmapData in the Cache, if stored there.

  Source:
    - gameobjects/BitmapData.js, line 34

#### pixels

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `pixels` | Uint32Array | An Uint32Array view into BitmapData.buffer.

  Source:
    - gameobjects/BitmapData.js, line 76

#### texture

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `texture` | PIXI.Texture | The PIXI.Texture.

  Source:
    - gameobjects/BitmapData.js, line 109

#### textureFrame

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `textureFrame` | Phaser.Frame | The Frame this BitmapData uses for rendering.

  Source:
    - gameobjects/BitmapData.js, line 115

#### type

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `type` | number | The const type of this object.

  Source:
    - gameobjects/BitmapData.js, line 121

#### width

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `width` | number | The width of the BitmapData in pixels.

  Source:
    - gameobjects/BitmapData.js, line 39

### 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:
    - gameobjects/BitmapData.js, line 159

#### alphaMask(source, mask)

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `source` | HTMLImage | string | The Image to draw. If you give a key it will try and find the Image in the Game.Cache.
  `mask` | HTMLImage | string | The Image to use as the alpha mask. If you give a key it will try and find the Image in the Game.Cache.

  Source:
    - gameobjects/BitmapData.js, line 783

#### 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:
    - gameobjects/BitmapData.js, line 879

#### clear()

  Clears the BitmapData context using a clearRect.

  Source:
    - gameobjects/BitmapData.js, line 186

#### cls()

  Clears the BitmapData context using a clearRect.

  Source:
    - gameobjects/BitmapData.js, line 184

#### copyPixels(source, area, destX, destY)

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `source` | HTMLImage | string | The Image to draw. If you give a key it will try and find the Image in the Game.Cache.
  `area` | Phaser.Rectangle | The Rectangle region to copy from the source image.
  `destX` | number | The destination x coordinate to copy the image to.
  `destY` | number | The destination y coordinate to copy the image to.

  Source:
    - gameobjects/BitmapData.js, line 710

#### draw(source, x, y)

  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
  --- | --- | --- | --- | ---
  `source` | 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.

  Source:
    - gameobjects/BitmapData.js, line 735

#### drawSprite(sprite, x, y)

  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:
    - gameobjects/BitmapData.js, line 762

#### extract(destination, r, g, b, a) → {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 destination BitmapData must be large enough to receive all of the pixels that are scanned. 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)`

  ##### 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.

  Source:
    - gameobjects/BitmapData.js, line 822

  ##### 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:
    - gameobjects/BitmapData.js, line 203

#### 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:
    - gameobjects/BitmapData.js, line 624

  ##### 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:
    - gameobjects/BitmapData.js, line 658

  ##### 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:
    - gameobjects/BitmapData.js, line 678

  ##### 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:
    - gameobjects/BitmapData.js, line 697

  ##### Returns:

  Returns a ImageData object containing a Uint8ClampedArray data property.

  Type
    ImageData

#### 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:
    - gameobjects/BitmapData.js, line 354

#### 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:
    - gameobjects/BitmapData.js, line 299

#### 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:
    - gameobjects/BitmapData.js, line 857

#### 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:
    - gameobjects/BitmapData.js, line 246

#### 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:
    - gameobjects/BitmapData.js, line 903

#### 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:
    - gameobjects/BitmapData.js, line 405

#### resize()

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

  Source:
    - gameobjects/BitmapData.js, line 222

#### 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:
    - gameobjects/BitmapData.js, line 452

#### 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:
    - gameobjects/BitmapData.js, line 606

#### 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:
    - gameobjects/BitmapData.js, line 570

#### 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:
    - gameobjects/BitmapData.js, line 510

#### 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:
    - gameobjects/BitmapData.js, line 244