HTML
Living Standard — Last Updated 16 January 2024
Living Standard — Last Updated 16 January 2024
Support in all current engines.
[Exposed =(Window ,Worker ), Serializable , Transferable ]
interface ImageBitmap {
readonly attribute unsigned long width ;
readonly attribute unsigned long height ;
undefined close ();
};
typedef (CanvasImageSource or
Blob or
ImageData ) ImageBitmapSource ;
enum ImageOrientation { " from-image " , " flipY " };
enum PremultiplyAlpha { " none " , " premultiply " , " default " };
enum ColorSpaceConversion { " none " , " default " };
enum ResizeQuality { " pixelated " , " low " , " medium " , " high " };
dictionary ImageBitmapOptions {
ImageOrientation imageOrientation = "from-image";
PremultiplyAlpha premultiplyAlpha = "default";
ColorSpaceConversion colorSpaceConversion = "default";
[EnforceRange ] unsigned long resizeWidth ;
[EnforceRange ] unsigned long resizeHeight ;
ResizeQuality resizeQuality = "low";
};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 ])Support in all current engines.
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()Support in all current engines.
Releases imageBitmap's underlying bitmap data.
imageBitmap.widthSupport in all current engines.
Returns the natural width of the image, in CSS pixels.
imageBitmap.heightSupport in all current engines.
Returns the natural height of the image, in CSS pixels.
An ImageBitmap object whose [[Detached]] internal slot value
is false always has associated bitmap data,
with a width and a height. However, it is possible for this data to be corrupted. If an
ImageBitmap object's media data can be decoded without errors, it is said to be fully decodable.
An ImageBitmap object's bitmap has an origin-clean flag, which indicates whether the
bitmap is tainted by content from a different origin. The flag is initially set to
true and may be changed to false by the steps of createImageBitmap().
ImageBitmap objects are serializable objects and transferable
objects.
Their serialization steps, given value and serialized, are:
If value's origin-clean
flag is not set, then throw a "DataCloneError"
DOMException.
Set serialized.[[BitmapData]] to a copy of value's bitmap data.
Their deserialization steps, given serialized, value, and targetRealm, are:
Set value's bitmap data to serialized.[[BitmapData]].
Their transfer steps, given value and dataHolder, are:
If value's origin-clean
flag is not set, then throw a "DataCloneError"
DOMException.
Set dataHolder.[[BitmapData]] to value's bitmap data.
Unset value's bitmap data.
Their transfer-receiving steps, given dataHolder and value, are:
Set value's bitmap data to dataHolder.[[BitmapData]].
The createImageBitmap(image,
options) and createImageBitmap(image
sx, sy, sw, sh, options) methods,
when invoked, must run these steps:
If either sw or sh is given and is 0, then return a promise
rejected with a RangeError.
If either options's resizeWidth or options's
resizeHeight is present and is 0, then
return a promise rejected with an "InvalidStateError"
DOMException.
Check the usability of the image argument. If this throws an
exception or returns bad, then return a promise rejected with an
"InvalidStateError" DOMException.
Let p be a new promise.
Let imageBitmap be a new ImageBitmap object.
Switch on image:
img
image
If image's media data has no natural dimensions (e.g., it's
a vector graphic with no specified content size) and either options's resizeWidth or options's resizeHeight is not present, then
a promise rejected with an "InvalidStateError"
DOMException.
If image's media data has no natural dimensions (e.g., it's
a vector graphics with no specified content size), it should be rendered to a bitmap of the
size specified by the resizeWidth
and the resizeHeight
options.
Set imageBitmap's bitmap data to a copy of image's media data, cropped to the source rectangle with formatting. If this is an animated image, imageBitmap's bitmap data must only be taken from the default image of the animation (the one that the format defines is to be used when animation is not supported or is disabled), or, if there is no such image, the first frame of the animation.
If image is not origin-clean, then set the origin-clean flag of imageBitmap's bitmap to false.
Run this step in parallel:
Resolve p with imageBitmap.
video
If image's networkState
attribute is NETWORK_EMPTY, then return
a promise rejected with an "InvalidStateError"
DOMException.
Set imageBitmap's bitmap data to a copy of the frame at the current playback position, at the media resource's natural width and natural height (i.e., after any aspect-ratio correction has been applied), cropped to the source rectangle with formatting.
If image is not origin-clean, then set the origin-clean flag of imageBitmap's bitmap to false.
Run this step in parallel:
Resolve p with imageBitmap.
canvas
Set imageBitmap's bitmap data to a copy of image's bitmap data, cropped to the source rectangle with formatting.
Set the origin-clean flag of the imageBitmap's bitmap to the same value as the origin-clean flag of image's bitmap.
Run this step in parallel:
Resolve p with imageBitmap.
Blob
Run these step in parallel:
Let imageData be the result of reading image's data. If an error occurs during reading of the object, then reject
p with an "InvalidStateError" DOMException
and abort these steps.
Apply the image sniffing rules to
determine the file format of imageData, with MIME type of image (as
given by image's type attribute) giving the
official type.
If imageData is not in a supported image file format (e.g., it's not an
image at all), or if imageData is corrupted in some fatal way such that the image
dimensions cannot be obtained (e.g., a vector graphic with no natural size), then reject
p with an "InvalidStateError" DOMException
and abort these steps.
Set imageBitmap's bitmap data to imageData, cropped to the source rectangle with formatting. If this is an animated image, imageBitmap's bitmap data must only be taken from the default image of the animation (the one that the format defines is to be used when animation is not supported or is disabled), or, if there is no such image, the first frame of the animation.
Resolve p with imageBitmap.
ImageData
Let buffer be image's data attribute value's [[ViewedArrayBuffer]] internal
slot.
If IsDetachedBuffer(buffer) is true, then return a
promise rejected with an "InvalidStateError"
DOMException.
Set imageBitmap's bitmap data to image's image data, cropped to the source rectangle with formatting.
Run this step in parallel:
Resolve p with imageBitmap.
ImageBitmap
Set imageBitmap's bitmap data to a copy of image's bitmap data, cropped to the source rectangle with formatting.
Set the origin-clean flag of imageBitmap's bitmap to the same value as the origin-clean flag of image's bitmap.
Run this step in parallel:
Resolve p with imageBitmap.
VideoFrame
Set imageBitmap's bitmap data to a copy of image's visible pixel data, cropped to the source rectangle with formatting.
Run this step in parallel:
Resolve p with imageBitmap.
Return p.
When the steps above require that the user agent crop bitmap data to the source rectangle with formatting, the user agent must run the following steps:
Let input be the bitmap data being transformed.
If sx, sy, sw and sh are specified, let sourceRectangle be a rectangle whose corners are the four points (sx, sy), (sx+sw, sy),(sx+sw, sy+sh), (sx,sy+sh). Otherwise let sourceRectangle be a rectangle whose corners are the four points (0,0), (width of input, 0), (width of input, height of input), (0, height of input).
If either sw or sh are negative, then the top-left corner of this rectangle will be to the left or above the (sx, sy) point.
Let outputWidth be determined as follows:
resizeWidth member of
options is specifiedresizeWidth
member of optionsresizeWidth member of
options is not specified, but the resizeHeight member is specifiedresizeHeight member of options,
divided by the height of sourceRectangle, rounded up to the nearest integerresizeWidth nor resizeHeight are specifiedLet outputHeight be determined as follows:
resizeHeight member of
options is specifiedresizeHeight
member of optionsresizeHeight member of
options is not specified, but the resizeWidth member is specifiedresizeWidth member of options,
divided by the width of sourceRectangle, rounded up to the nearest integerresizeWidth nor resizeHeight are specifiedPlace input on an infinite transparent black grid plane, positioned so that its top left corner is at the origin of the plane, with the x-coordinate increasing to the right, and the y-coordinate increasing down, and with each pixel in the input image data occupying a cell on the plane's grid.
Let output be the rectangle on the plane denoted by sourceRectangle.
Scale output to the size specified by outputWidth and
outputHeight. The user agent should use the value of the resizeQuality option to guide the
choice of scaling algorithm.
If the value of the imageOrientation member of
options is "flipY", output must be flipped
vertically, disregarding any image orientation metadata of the source (such as EXIF metadata),
if any. [EXIF]
If the value is "from-image", no extra step is needed.
There used to be a "none" enum value. It was
renamed to "from-image". In the future,
"none" will be added back
with a different meaning.
If image is an img element or a Blob object, let
val be the value of the colorSpaceConversion member
of options, and then run these substeps:
If val is "default",
the color space conversion behavior is implementation-specific, and should be chosen according
to the default color space that the implementation uses for drawing images onto the canvas.
If val is "none", output must be decoded
without performing any color space conversions. This means that the image decoding algorithm
must ignore color profile metadata embedded in the source data as well as the display device
color profile.
Let val be the value of premultiplyAlpha member of
options, and then run these substeps:
If val is "default", the alpha premultiplication
behavior is implementation-specific, and should be chosen according to implementation deems
optimal for drawing images onto the canvas.
If val is "premultiply", the output that
is not premultiplied by alpha must have its color components multiplied by alpha and that is premultiplied by alpha
must be left untouched.
If val is "none", the output that is not
premultiplied by alpha must be left untouched and that is premultiplied by alpha must have its
color components divided by alpha.
Return output.
The close()
method steps are:
Set this's [[Detached]] internal slot value to true.
Unset this's bitmap data.
The width
getter steps are:
If this's [[Detached]] internal slot's value is true, then return 0.
Return this's width, in CSS pixels.
The height
getter steps are:
If this's [[Detached]] internal slot's value is true, then return 0.
Return this's height, in CSS pixels.
The ResizeQuality enumeration is used to express a preference for the
interpolation quality to use when scaling images.
The "pixelated" value indicates a preference to scale
the image that maximizes the appearance. Scaling algorithms that "smooth" colors are acceptable,
such as bilinear interpolation.
The "low"
value indicates a preference for a low level of image interpolation quality. Low-quality image
interpolation may be more computationally efficient than higher settings.
The "medium" value indicates a preference for a medium
level of image interpolation quality.
The "high" value indicates a preference for a high level
of image interpolation quality. High-quality image interpolation may be more computationally
expensive than lower settings.
Bilinear scaling is an example of a relatively fast, lower-quality image-smoothing algorithm. Bicubic or Lanczos scaling are examples of image-scaling algorithms that produce higher-quality output. This specification does not mandate that specific interpolation algorithms be used unless the value is "pixelated".
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.
callback FrameRequestCallback = undefined (DOMHighResTimeStamp time );
interface mixin AnimationFrameProvider {
unsigned long requestAnimationFrame (FrameRequestCallback callback );
undefined cancelAnimationFrame (unsigned long handle );
};
Window includes AnimationFrameProvider ;
DedicatedWorkerGlobalScope includes AnimationFrameProvider ;Each AnimationFrameProvider object also has a target object that stores the
provider's internal state. It is defined as follows:
AnimationFrameProvider is a WindowWindow's associated
DocumentAnimationFrameProvider is a DedicatedWorkerGlobalScopeDedicatedWorkerGlobalScopeEach 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
hold:
Window.Document object.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:
Let callback be callbacks[handle].
Remove callbacks[handle].
Invoke callback, passing now as the only argument, and if an exception is thrown, report the exception.
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();
};