createImageBitmap()
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
const imageBitmapPromise = createImageBitmap(image[, options]);
const imageBitmapPromise = createImageBitmap(image, sx, sy, sw, sh[, options]);
Parameters
image
-
An image source, which can be an
<img>
, SVG<image>
,<video>
,<canvas>
,HTMLImageElement
,SVGImageElement
,HTMLVideoElement
,HTMLCanvasElement
,Blob
,ImageData
,ImageBitmap
, orOffscreenCanvas
object. 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. Eithernone
(default) orflipY
. -
premultiplyAlpha
: Specifies whether the bitmap's color channels should be premultiplied by the alpha channel. One ofnone
,premultiply
, ordefault
(default). -
colorSpaceConversion
: Specifies whether the image should be decoded using color space conversion. Eithernone
ordefault
(default). The valuedefault
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 ofpixelated
,low
(default),medium
, orhigh
.
-
Return value
A Promise
which resolves to an ImageBitmap
object
containing bitmap data from the given rectangle.
Example
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.
var canvas = document.getElementById('myCanvas'),
ctx = canvas.getContext('2d'),
image = new Image();
// Wait for the sprite sheet to load
image.onload = function() {
Promise.all([
// Cut out two sprites from the sprite sheet
createImageBitmap(image, 0, 0, 32, 32),
createImageBitmap(image, 32, 0, 32, 32)
]).then(function(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
Specification |
---|
HTML Standard # dom-createimagebitmap-dev |
Browser compatibility
BCD tables only load in the browser