This specification is like no other — it has been processed with you, the humble web developer, in mind.
The focus of this specification is readability and ease of access. Unlike the full HTML Standard, this "developer's edition" removes information that only browser vendors need know. It is automatically produced from the full specification by our build tooling, and thus always in sync with the latest developments in HTML.
To read about its conception, construction, and future, read the original press release, and the blog post about its relaunch.
Finally, feel free to contribute on GitHub to make this edition better for everyone!
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.
createImageBitmap
(image [, options ])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 [[Detached]]
internal slot value is true, 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).
close
()Releases imageBitmap's underlying bitmap data.
width
Returns the intrinsic width of the image, in CSS pixels.
height
Returns the intrinsic 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.woman = image }), createImageBitmap(image, 40, 0, 40, 40).then(function (image) { sprites.man = 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);
Each Document
has a list of animation frame callbacks, which must be
initially empty, and an animation frame callback identifier, which is a number which
must initially be zero.
When the requestAnimationFrame()
method is called,
the user agent must run the following steps:
Let document be this Window
object's associated Document
.
Increment document's animation frame callback identifier by one.
Append the method's argument to document's list of animation frame callbacks, associated with document's animation frame callback identifier's current value.
Return document's animation frame callback identifier's current value.
When the cancelAnimationFrame()
method is called,
the user agent must run the following steps:
Let document be this Window
object's associated Document
.
Find the entry in document's list of animation frame callbacks that is associated with the value given by the method's argument.
If there is such an entry, remove it from document's list of animation frame callbacks.
When the user agent is to run the animation frame callbacks for a
Document
doc with a timestamp now, it must run the following
steps:
Let callbacks be a list of the entries in doc's list of animation frame callbacks, in the order in which they were added to the list.
Set doc's list of animation frame callbacks to the empty list.
For each entry in callbacks, in order: invoke the callback, passing now as the only argument, and if an exception is thrown, report the exception. [WEBIDL]