Edition for Web Developers — Last Updated 8 November 2024
An ImageBitmap
object represents a bitmap image that can be painted to a canvas
without undue latency.
The exact judgement of what is undue latency of this is left up to the implementer, but in general if making use of the bitmap requires network I/O, or even local disk I/O, then the latency is probably undue; whereas if it only requires a blocking read from a GPU or system RAM, the latency is probably acceptable.
promise = self.createImageBitmap(image [, options ])
promise = self.createImageBitmap(image, sx, sy, sw, sh [, options ])
Takes image, which can be an img
element, an SVG
image
element, a video
element, a canvas
element,
a Blob
object, an ImageData
object, or another
ImageBitmap
object, and returns a promise that is resolved when a new
ImageBitmap
is created.
If no ImageBitmap
object can be constructed, for example because the provided
image data is not actually an image, then the promise is rejected instead.
If sx, sy, sw, and sh arguments are provided, the source image is cropped to the given pixels, with any pixels missing in the original replaced by transparent black. These coordinates are in the source image's pixel coordinate space, not in CSS pixels.
If options is provided, the ImageBitmap
object's bitmap data is
modified according to options. For example, if the premultiplyAlpha
option is set to "premultiply
", the bitmap data's color channels are premultiplied by its alpha channel.
Rejects the promise with an "InvalidStateError
"
DOMException
if the source image is not in a valid state (e.g., an img
element that hasn't loaded successfully, an ImageBitmap
object whose
[[Detached]] internal slot value is true, an ImageData
object whose
data
attribute value's [[ViewedArrayBuffer]] internal
slot is detached, or a Blob
whose data cannot be interpreted as a bitmap
image).
Rejects the promise with a "SecurityError
"
DOMException
if the script is not allowed to access the image data of the source
image (e.g. a video
that is CORS-cross-origin, or a
canvas
being drawn on by a script in a worker from another
origin).
imageBitmap.close()
Releases imageBitmap's underlying bitmap data.
imageBitmap.width
Returns the natural width of the image, in CSS pixels.
imageBitmap.height
Returns the natural height of the image, in CSS pixels.
Using this API, a sprite sheet can be precut and prepared:
var sprites = {};
function loadMySprites() {
var image = new Image();
image. src = 'mysprites.png' ;
var resolver;
var promise = new Promise( function ( arg) { resolver = arg });
image. onload = function () {
resolver( Promise. all([
createImageBitmap( image, 0 , 0 , 40 , 40 ). then( function ( image) { sprites. person = image }),
createImageBitmap( image, 40 , 0 , 40 , 40 ). then( function ( image) { sprites. grass = image }),
createImageBitmap( image, 80 , 0 , 40 , 40 ). then( function ( image) { sprites. tree = image }),
createImageBitmap( image, 0 , 40 , 40 , 40 ). then( function ( image) { sprites. hut = image }),
createImageBitmap( image, 40 , 40 , 40 , 40 ). then( function ( image) { sprites. apple = image }),
createImageBitmap( image, 80 , 40 , 40 , 40 ). then( function ( image) { sprites. snake = image })
]));
};
return promise;
}
function runDemo() {
var canvas = document. querySelector( 'canvas#demo' );
var context = canvas. getContext( '2d' );
context. drawImage( sprites. tree, 30 , 10 );
context. drawImage( sprites. snake, 70 , 10 );
}
loadMySprites(). then( runDemo);
Some objects include the AnimationFrameProvider
interface mixin.
Each AnimationFrameProvider
object also has a target object that stores the
provider's internal state. It is defined as follows:
AnimationFrameProvider
is a Window
Window
's associated
Document
AnimationFrameProvider
is a DedicatedWorkerGlobalScope
DedicatedWorkerGlobalScope
Each target object has a map of animation frame callbacks, which is an ordered map that must be initially empty, and an animation frame callback identifier, which is a number that must initially be zero.
An AnimationFrameProvider
provider is considered supported if any of the following are
true:
provider is a Window
.
provider's owner set contains
a Document
object.
Any of the DedicatedWorkerGlobalScope
objects in provider's
owner set are supported.
Support in all current engines.
The requestAnimationFrame(callback)
method steps are:
If this is not supported, then throw a
"NotSupportedError
" DOMException
.
Let target be this's target object.
Increment target's animation frame callback identifier by one, and let handle be the result.
Let callbacks be target's map of animation frame callbacks.
Set callbacks[handle] to callback.
Return handle.
Support in all current engines.
The cancelAnimationFrame(handle)
method steps are:
If this is not supported, then throw a
"NotSupportedError
" DOMException
.
Let callbacks be this's target object's map of animation frame callbacks.
Remove callbacks[handle].
To run the animation frame callbacks for a target object target with a timestamp now:
Let callbacks be target's map of animation frame callbacks.
Let callbackHandles be the result of getting the keys of callbacks.
For each handle in callbackHandles, if handle exists in callbacks:
Inside workers, requestAnimationFrame()
can be
used together with an OffscreenCanvas
transferred from a canvas
element. First, in the document, transfer control to the worker:
const offscreenCanvas = document. getElementById( "c" ). transferControlToOffscreen();
worker. postMessage( offscreenCanvas, [ offscreenCanvas]);
Then, in the worker, the following code will draw a rectangle moving from left to right:
let ctx, pos = 0 ;
function draw( dt) {
ctx. clearRect( 0 , 0 , 100 , 100 );
ctx. fillRect( pos, 0 , 10 , 10 );
pos += 10 * dt;
requestAnimationFrame( draw);
}
self. onmessage = function ( ev) {
const transferredCanvas = ev. data;
ctx = transferredCanvas. getContext( "2d" );
draw();
};