1. 8.10 画像
    2. 8.11 アニメーションフレーム

8.10 画像

ImageBitmap

Firefox42+SafariNoChrome50+
Opera37+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android42+Safari iOSNoChrome Android50+WebView Android50+Samsung Internet5.0+Opera Android37+
[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 { "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";
};

ImageBitmapオブジェクトは過度の待ち時間なしのキャンバスに塗装できるビットマップ画像を表す。

この過度の待ち時間は何かの正確な判断は実装者に委ねるが、一般にビットマップを活用することは、ネットワークI/O、あるいはローカルディスクI/Oを必要とする場合、その後待ち時間はおそらく過度である。一方それが唯一のGPUやシステムRAMからのブロッキングの読み出しを必要とする場合、待ち時間はおそらく許容できる。

promise = self.createImageBitmap(image [, options ])

createImageBitmap

Firefox42+SafariNoChrome50+
OperaYesEdge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox AndroidYesSafari iOSNoChrome Android50+WebView Android50+Samsung Internet5.0+Opera AndroidYes
promise = self.createImageBitmap(image, sx, sy, sw, sh [, options ])

画像、これはimg要素、SVG image要素、video要素、canvas要素、Blobオブジェクト、ImageDataオブジェクト、または別のImageBitmapオブジェクトである、を取得し、新しいImageBitmapが作成されたときに解決されるpromiseを返す。

ImageBitmapオブジェクトを構築することが全くできない場合、たとえば、与えられたimage データが実際の画像ではないので、代わりにpromiseが却下される。

sxsysw、およびsh引数が指定される場合、ソース画像は与えられたピクセルに切り取られ、元のピクセルに欠けているピクセルは透明な黒に置き換えられる。これらの座標は、CSSピクセルではなく、ソース画像のピクセル座標空間にある。

optionsが指定される場合、ImageBitmapオブジェクトのビットマップデータはoptionsに従って変更される。For example, if the premultiplyAlpha option is set to "premultiply", the bitmap data's color channels are premultiplied by its alpha channel.

ソース画像が有効な状態にない場合、"InvalidStateError" DOMExceptionを拒否する(たとえば、正常に読み込まれなかったimg要素、[[Detached]]内部スロット値がtrueのImageBitmapオブジェクト、data属性値の[[ViewedArrayBuffer]]内部スロットが切り離されているImageDataオブジェクト、データがビットマップイメージとして解釈できないBlobなど)。

スクリプトがソース画像の画像データへのアクセスを許可されていない場合、"SecurityError" DOMExceptionでpromiseを拒否する(たとえば、生成元をまたぐCORSであるvideo、別の生成元からのワーカーのスクリプトで描画されたcanvasなど)。

imageBitmap.close()

ImageBitmap/close

Firefox46+SafariNoChrome52+
Opera37+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android46+Safari iOSNoChrome Android52+WebView Android52+Samsung Internet6.0+Opera Android37+

imageBitmapの基礎となるビットマップデータを解放する。

imageBitmap.width

ImageBitmap/width

Firefox42+SafariNoChrome50+
Opera37+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android42+Safari iOSNoChrome Android50+WebView Android50+Samsung Internet5.0+Opera Android37+

画像の内在幅CSSピクセルで返す。

imageBitmap.height

ImageBitmap/height

Firefox42+SafariNoChrome50+
Opera37+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android42+Safari iOSNoChrome Android50+WebView Android50+Samsung Internet5.0+Opera Android37+

画像の内在高さCSSピクセルで返す。

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. If value's origin-clean flag is not set, then throw a "DataCloneError" DOMException.

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

Their deserialization steps, given serialized and value, are:

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

Their transfer steps, given value and dataHolder, are:

  1. If value's origin-clean flag is not set, then throw a "DataCloneError" DOMException.

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

  3. Unset value's bitmap data.

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

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

  1. Let p be a new promise.

  2. If either sw or sh is given and is 0, then return p rejected with a RangeError.

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

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

  5. Let imageBitmap be a new ImageBitmap object.

  6. Switch on image:

    img
    SVG image
    1. If image's media data has no intrinsic 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 return p rejected with an "InvalidStateError" DOMException.

    2. If image's media data has no intrinsic 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.

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

    4. If image is not origin-clean, then set the origin-clean flag of imageBitmap's bitmap to false.

    5. Run this step in parallel:

      1. Resolve p with imageBitmap.

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

    2. Set imageBitmap's bitmap data to a copy of the frame at the current playback position, at the media resource's intrinsic width and intrinsic height (i.e., after any aspect-ratio correction has been applied), cropped to the source rectangle with formatting.

    3. If image is not origin-clean, then set the origin-clean flag of imageBitmap's bitmap to false.

    4. Run this step in parallel:

      1. Resolve p with imageBitmap.

    canvas
    1. Set imageBitmap's bitmap data to a copy of image's bitmap data, cropped to the source rectangle with formatting.

    2. Set the origin-clean flag of the imageBitmap's bitmap to the same value as the origin-clean flag of image's bitmap.

    3. Run this step in parallel:

      1. Resolve p with imageBitmap.

    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 (e.g., a vector graphic with no intrinsic size), then reject p with an "InvalidStateError" DOMException and abort these steps.

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

    5. Resolve p with imageBitmap.

    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. Set imageBitmap's bitmap data to image's image data, cropped to the source rectangle with formatting.

    4. Run this step in parallel:

      1. Resolve p with imageBitmap.

    ImageBitmap
    1. Set imageBitmap's bitmap data to a copy of image's bitmap data, cropped to the source rectangle with formatting.

    2. Set the origin-clean flag of imageBitmap's bitmap to the same value as the origin-clean flag of image's bitmap.

    3. Run this step in parallel:

      1. Resolve p with imageBitmap.

    VideoFrame
    1. Set imageBitmap's bitmap data to a copy of image's visible pixel data, cropped to the source rectangle with formatting.

    2. Run this step in parallel:

      1. Resolve p with imageBitmap.

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

  1. Let input be the bitmap data being transformed.

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

  3. Let outputWidth be determined as follows:

    If the resizeWidth member of options is specified
    the value of the resizeWidth member of options
    If the resizeWidth member of options is not specified, but the resizeHeight member is specified
    the width of sourceRectangle, times the value of the resizeHeight member of options, divided by the height of sourceRectangle, rounded up to the nearest integer
    If neither resizeWidth nor resizeHeight are specified
    the width of sourceRectangle
  4. Let outputHeight be determined as follows:

    If the resizeHeight member of options is specified
    the value of the resizeHeight member of options
    If the resizeHeight member of options is not specified, but the resizeWidth member is specified
    the height of sourceRectangle, times the value of the resizeWidth member of options, divided by the width of sourceRectangle, rounded up to the nearest integer
    If neither resizeWidth nor resizeHeight are specified
    the height of sourceRectangle
  5. Place 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.

  6. Let output be the rectangle on the plane denoted by sourceRectangle.

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

  8. 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 "none", no extra step is required.

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

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

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

  10. Let val be the value of premultiplyAlpha member of options, and then run these substeps:

    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.

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

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

このAPIを使用すると、スプライトシートは、プレカットと調製することができる:

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.11 アニメーションフレーム

一部のオブジェクトにはAnimationFrameProviderインターフェイスミックスインが含まれる。

callback FrameRequestCallback = undefined (DOMHighResTimeStamp time);

interface mixin AnimationFrameProvider {
  unsigned long requestAnimationFrame(FrameRequestCallback callback);
  undefined cancelAnimationFrame(unsigned long handle);
};
Window includes AnimationFrameProvider;
DedicatedWorkerGlobalScope includes AnimationFrameProvider;

AnimationFrameProviderオブジェクトはまた、プロバイダーの内部状態を格納するターゲットオブジェクトを持つ。これは次のように定義される:

AnimationFrameProviderWindowである場合
Window関連付けられたDocument
AnimationFrameProviderDedicatedWorkerGlobalScopeである場合
DedicatedWorkerGlobalScope

ターゲットオブジェクトは、アニメーションフレームコールバックのマップ、これは初期は空でなければならない順序付きマップである、およびアニメーションフレームコールバック識別子、これは初期は0でなければならない数、を持つ。

次のいずれかが当てはまる場合、AnimationFrameProviderプロバイダーサポートされるとみなされる:


Window/requestAnimationFrame

Support in all current engines.

Firefox23+Safari7+Chrome24+
Opera15+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android23+Safari iOS7+Chrome Android25+WebView Android37+Samsung Internet1.5+Opera Android14+

The requestAnimationFrame(callback) method must run the following steps:

  1. If this AnimationFrameProvider is not supported, then throw a "NotSupportedError" DOMException.

  2. Let target be this AnimationFrameProvider's target object.

  3. Increment target's animation frame callback identifier by one, and let handle be the result.

  4. Let callbacks be target's map of animation frame callbacks.

  5. Set callbacks[handle] to callback.

  6. Return handle.

Window/cancelAnimationFrame

Support in all current engines.

Firefox23+Safari7+Chrome24+
Opera15+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android23+Safari iOS7+Chrome Android25+WebView Android37+Samsung Internet1.5+Opera Android14+

The cancelAnimationFrame(handle) method must run the following steps:

  1. If this AnimationFrameProvider is not supported, then throw a "NotSupportedError" DOMException.

  2. Let callbacks be this AnimationFrameProvider's target object's map of animation frame callbacks.

  3. Remove callbacks[handle].

To run the animation frame callbacks for a target object target with a timestamp now:

  1. Let callbacks be target's map of animation frame callbacks.

  2. Let callbackHandles be the result of getting the keys of callbacks.

  3. For each handle in callbackHandles, if handle exists in callbacks:

    1. Let callback be callbacks[handle].

    2. Remove callbacks[handle].

    3. Invoke callback, passing now as the only argument, and if an exception is thrown, report the exception.

ワーカー内部では、canvas要素から転送されたOffscreenCanvasと一緒にrequestAnimationFrame()を使用することができる。まず、文書内で、ワーカーに制御を転送する:

const offscreenCanvas = document.getElementById("c").transferControlToOffscreen();
worker.postMessage(offscreenCanvas, [offscreenCanvas]);

次に、ワーカーにおいて、以下のコードで左から右に移動する矩形を描画する:

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();
};