1. 8.8 Images
    2. 8.9 Animation frames

8.8 Images

[Exposed=(Window,Worker), Serializable, Transferable]
interface ImageBitmap {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
  void close();
};

typedef (CanvasImageSource or
         Blob or
         ImageData) ImageBitmapSource;

enum ImageOrientation { "none", "flipY" };
enum PremultiplyAlpha { "none", "premultiply", "default" };
enum ColorSpaceConversion { "none", "default" };
enum ResizeQuality { "pixelated", "low", "medium", "high" };

dictionary ImageBitmapOptions {
  ImageOrientation imageOrientation = "none";
  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 ])
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 intrinsic width of the image, in CSS pixels.

imageBitmap . height

Returns the intrinsic 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:

  1. Set serialized.[[BitmapData]] to a copy of value's bitmap data.

  2. Set serialized.[[OriginClean]] to true if value's origin-clean flag is set, and false otherwise.

Their deserialization steps, given serialized and value, are:

  1. Set value's bitmap data to serialized.[[BitmapData]].

  2. If serialized.[[OriginClean]] is true, set value's origin-clean flag.

Their transfer steps, given value and dataHolder, are:

  1. Set dataHolder.[[BitmapData]] to value's bitmap data.

  2. Set dataHolder.[[OriginClean]] to true if value's origin-clean flag is set, and false otherwise.

  3. Unset value's bitmap data.

Their transfer-receiving steps, given dataHolder and value, are:

  1. Set value's bitmap data to dataHolder.[[BitmapData]].

  2. If dataHolder.[[OriginClean]] is true, set value's origin-clean flag.

The createImageBitmap(image, options) and createImageBitmap(image sx, sy, sw, sh, options) methods, when invoked, must run these steps:

  1. Let p be a new promise.

  2. Let sourceRectangle be null.

  3. If sx is given, then:

    1. If sw or sh is 0, then return p rejected with a RangeError.

    2. Set sourceRectangle to a rectangle whose corners are the four points (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), and (sx, sy+sh).

      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.

  4. If either options's resizeWidth or options's resizeHeight is present and is 0, then return p rejected with an "InvalidStateError" DOMException.

  5. Check the usability of the image argument. If this throws an exception or returns bad, then return p rejected with an "InvalidStateError" DOMException.

  6. Switch on image:

    img
    SVG image

    1. If image's image data has no intrinsic dimensions (e.g., it's a vector image with no specified content size) and either options's resizeWidth or options's resizeHeight is not present, then return p rejected with an "InvalidStateError" DOMException.

    2. Let imageData be a copy of image's image data. If this fails, then return p rejected with an "InvalidStateError" DOMException.

    3. Let originClean be true if imageData's origin is same origin with entry settings object's origin, and false otherwise.

    4. Run these steps in parallel:

      1. Let vectorOrBitmap be imageData.

      2. If imageData is not a vector image, then set vectorOrBitmap to the result of rendering image data as a bitmap with imageData and options.

      3. If vectorOrBitmap is failure, then reject p with an "InvalidStateError" DOMException and abort these steps.

      4. Run the final ImageBitmap creation steps with p, vectorOrBitmap, sourceRectangle, originClean, and options.

    video

    1. If image's networkState attribute is NETWORK_EMPTY, then return p rejected with an "InvalidStateError" DOMException.

    2. Let bitmap be a copy of image's frame at the current playback position, using media resource's intrinsic width and intrinsic height (i.e., after any aspect-ratio correction has been applied). If this fails, then return p rejected with an "InvalidStateError" DOMException.

    3. Let originClean be true if image's media resource's origin is same origin with entry settings object's origin, and false otherwise.

    4. Run this step in parallel:

      1. Run the final ImageBitmap creation steps with p, bitmap, sourceRectangle, originClean, and options.

    canvas

    1. Let bitmap be a copy of image's bitmap data. If this fails, then return p rejected with an "InvalidStateError" DOMException.

    2. Let originClean be image's bitmap's origin-clean flag.

    3. Run this step in parallel:

      1. Run the final ImageBitmap creation steps with p, bitmap, sourceRectangle, originClean, and options.

    Blob

    Run these step in parallel:

    1. 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.

    2. 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.

    3. 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, then reject p with an "InvalidStateError" DOMException and abort these steps.

    4. If imageData has no intrinsic dimensions (e.g., it's a vector image with no specified content size) and either options's resizeWidth or options's resizeHeight is not present, then reject p with an "InvalidStateError" DOMException and abort these steps.

    5. Let vectorOrBitmap be imageData.

    6. If imageData is not a vector image, then set vectorOrBitmap to the result of rendering image data as a bitmap with imageData and options.

    7. If vectorOrBitmap is failure, then reject p with an "InvalidStateError" DOMException and abort these steps.

    8. Run the final ImageBitmap creation steps with p, vectorOrBitmap, sourceRectangle, true, and options.

    ImageData

    1. Let buffer be image's data attribute value's [[ViewedArrayBuffer]] internal slot.

    2. If IsDetachedBuffer(buffer) is true, then return p rejected with an "InvalidStateError" DOMException.

    3. Let bitmap be a copy of image's bitmap. If this fails, then return p rejected with an "InvalidStateError" DOMException.

    4. Run this step in parallel:

      1. Run the final ImageBitmap creation steps with p, bitmap, sourceRectangle, true, and options.

    ImageBitmap

    1. Let bitmap be a copy of image's bitmap data. If this fails, then return p rejected with an "InvalidStateError" DOMException.

    2. Let originClean be image's bitmap's origin-clean flag.

    3. Run this step in parallel:

      1. Run the final ImageBitmap creation steps with p, bitmap, sourceRectangle, originClean, and options.

  7. Return p.

Rendering image data as a bitmap, given imageData and options, is as follows:

  1. Return the result of rendering imageData onto a bitmap.

    If imageData is animated, then use 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 options's colorSpaceConversion is "default", then the color space conversion behavior is implementation-specific, and should be chosen according to the color space that the implementation uses for drawing images onto the canvas.

    Otherwise, it is "none", rendering is to be performed without any color space conversion. This means ignoring color profile metadata embedded in imageData as well as the display device color profile.

    The native color space of canvas is currently unspecified, but this is expected to change in the future.

    If any of this fails, then return failure.

The final ImageBitmap creation steps, given p, vectorOrBitmap, sourceRectangle, originClean, and options, are as follows:

  1. Let bitmap be the result of running crop and format an image with vectorOrBitmap, sourceRectangle, and options.

  2. Queue a task to run these steps:

    1. If bitmap is failure, then reject p with an "InvalidStateError" DOMException and abort these steps.

    2. Let imageBitmap be a new ImageBitmap object.

    3. Set imageBitmap's bitmap data to bitmap.

    4. Set imageBitmap's bitmap's origin-clean flag to originClean.

    5. Resolve p with imageBitmap.

To crop and format an image, given vectorOrBitmap, sourceRectangle, and options, run these steps:

  1. If vectorOrBitmap has no intrinsic width, then scale its width to options's resizeWidth.

  2. If vectorOrBitmap has no intrsinc height, then scale its height to options's resizeHeight.

  3. If sourceRectangle is null, then set sourceRectangle to a rectangle whose corners are the four points (0,0), (vectorOrBitmap's width, 0), (vectorOrBitmap's width, vectorOrBitmap's height), and (0, vectorOrBitmap's height).

  4. Clip sourceRectangle to the dimensions of vectorOrBitmap.

  5. Let outputWidth be determined as follows:

    If options's resizeWidth is present
    options's resizeWidth.
    If options's resizeWidth is not present, but options's resizeHeight is present
    The width of sourceRectangle, times the options's resizeHeight, divided by the height of sourceRectangle, rounded up to the nearest integer.
    If neither options's resizeWidth nor resizeHeight are present
    The width of sourceRectangle.

  6. Let outputHeight be determined as follows:

    If options's resizeHeight is present
    options's resizeHeight.
    If options's resizeHeight is not present, but options's resizeWidth is present
    The height of sourceRectangle, times options's resizeWidth, divided by the width of sourceRectangle, rounded up to the nearest integer.
    If neither options's resizeWidth nor resizeHeight are present
    The height of sourceRectangle.

  7. Let output be null.

  8. If vectorOrBitmap is a vector image, then:

    1. Let scaleX be outputWidth divided by sourceRectangle's width.

    2. Let scaleY be outputHeight divided by sourceRectangle's height.

    3. Scale sourceRectangle by scaleX and scaleY.

    4. Rasterize vectorOrBitmap as an outputWidth times scaleX by outputHeight times scaleY rectangle 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.

      Set output to the rectangle on the plane denoted by sourceRectangle.

      If this fails, then return failure.

      Implementations are encouraged to avoid rasterizing parts of the vector image that end up cropped.

  9. Otherwise:

    1. Place vectorOrBitmap 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 bitmap occupying a cell on the plane's grid.

      Set output to the rectangle on the plane denoted by sourceRectangle.

    2. Scale output to the size specified by outputWidth and outputHeight. When doing so, user agents should switch on options's resizeQuality:

      "pixelated"
      A preference to scale the image that maximizes the appearance. Scaling algorithms that "smooth" colors are acceptable, such as bilinear interpolation.
      "low"
      A preference for a low level of image interpolation quality. Low-quality image interpolation can be more computationally efficient than higher settings.
      "medium"
      A preference for a medium level of image interpolation quality.
      "high"
      A preference for a high level of image interpolation quality. High-quality image interpolation can 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.

      If this fails, then return failure.

  10. If options's imageOrientation is "flipY", then flip output vertically, disregarding any image orientation metadata of the source (such as EXIF metadata), if any. [EXIF]

    If the value is "none", no extra step is required.

  11. Let val be options's premultiplyAlpha and then run these steps:

    1. 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.

    2. 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.

    3. 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.

  12. Return output.

When the close() method is called, the user agent must run these steps:

  1. Set this ImageBitmap object's [[Detached]] internal slot value to true.

  2. Unset this ImageBitmap object's bitmap data.

The width attribute's getter must run these steps:

  1. If this ImageBitmap object's [[Detached]] internal slot's value is true, then return 0.

  2. Return this ImageBitmap object's width, in CSS pixels.

The height attribute's getter must run these steps:

  1. If this ImageBitmap object's [[Detached]] internal slot's value is true, then return 0.

  2. Return this ImageBitmap object's height, 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);

8.9 Animation frames

Support: requestanimationframeChrome for Android 64+Chrome 24+iOS Safari 7.0+UC Browser for Android 11.8+Firefox 23+IE 10+Samsung Internet 4+Opera Mini NoneSafari 6.1+Edge 12+Android Browser 4.4+Opera 15+

Source: caniuse.com

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:

  1. Let document be this Window object's associated Document.

  2. Increment document's animation frame callback identifier by one.

  3. Append the method's argument to document's list of animation frame callbacks, associated with document's animation frame callback identifier's current value.

  4. Return document's animation frame callback identifier's current value.

When the cancelAnimationFrame() method is called, the user agent must run the following steps:

  1. Let document be this Window object's associated Document.

  2. Find the entry in document's list of animation frame callbacks that is associated with the value given by the method's argument.

  3. 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:

  1. 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.

  2. Set doc's list of animation frame callbacks to the empty list.

  3. 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]