W3cubDocs

/Web APIs

createImageBitmap() global function

The createImageBitmap() method creates a bitmap from a given source, optionally cropped to contain only a portion of that source. The method exists on the global scope in both windows and workers. It accepts a variety of different image sources, and returns a Promise which resolves to an ImageBitmap.

Syntax

js

createImageBitmap(image)
createImageBitmap(image, options)
createImageBitmap(image, sx, sy, sw, sh)
createImageBitmap(image, sx, sy, sw, sh, options)

Parameters

image

An image source, which can be any one of the following:

sx

The x coordinate of the reference point of the rectangle from which the ImageBitmap will be extracted.

sy

The y coordinate of the reference point of the rectangle from which the ImageBitmap will be extracted.

sw

The width of the rectangle from which the ImageBitmap will be extracted. This value can be negative.

sh

The height of the rectangle from which the ImageBitmap will be extracted. This value can be negative.

options Optional

An object that sets options for the image's extraction. The available options are:

imageOrientation

Specifies whether the image should be presented as is or flipped vertically. Either none (default) or flipY.

premultiplyAlpha

Specifies whether the bitmap's color channels should be premultiplied by the alpha channel. One of none, premultiply, or default (default).

colorSpaceConversion

Specifies whether the image should be decoded using color space conversion. Either none or default (default). The value default indicates that implementation-specific behavior is used.

resizeWidth

A long integer that indicates the output width.

resizeHeight

A long integer that indicates the output height.

resizeQuality

Specifies the algorithm to be used for resizing the input to match the output dimensions. One of pixelated, low (default), medium, or high.

Return value

A Promise which resolves to an ImageBitmap object containing bitmap data from the given rectangle.

Examples

Creating sprites from a sprite sheet

This example loads a sprite sheet, extracts individual sprites, and then renders each sprite to the canvas. A sprite sheet is an image containing multiple smaller images, each of which you want to be able to render separately.

js

const canvas = document.getElementById("myCanvas"),
  ctx = canvas.getContext("2d"),
  image = new Image();

// Wait for the sprite sheet to load
image.onload = () => {
  Promise.all([
    // Cut out two sprites from the sprite sheet
    createImageBitmap(image, 0, 0, 32, 32),
    createImageBitmap(image, 32, 0, 32, 32),
  ]).then((sprites) => {
    // Draw each sprite onto the canvas
    ctx.drawImage(sprites[0], 0, 0);
    ctx.drawImage(sprites[1], 32, 32);
  });
};

// Load the sprite sheet from an image file
image.src = "sprites.png";

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
createImageBitmap 50 79 42 No 37 15 50 50 42 37 15 5.0
options_colorSpaceConversion_parameter 58 79 98 No 45 15 58 58 98 43 15 7.0
options_imageOrientation_parameter 52 79 93 No 39 15 52 52 93 41 15 6.0
options_premultiplyAlpha_parameter 52 79 93 No 39 15 52 52 93 41 15 6.0
options_resizeHeight_parameter 54 79 98 No 41 15 54 54 98 41 15 6.0
options_resizeQuality_parameter 54 79 No No 41 15 54 54 No 41 15 6.0
options_resizeWidth_parameter 54 79 98 No 41 15 54 54 98 41 15 6.0
svgimageelement_as_source_image 59 79 65 No 46 No 59 59 65 43 No 7.0
worker_support 50 79 42 No 37 No 50 50 42 37 No 5.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/createImageBitmap