[html5] r7589 - [giow] (0) Add a way to prepare sprites so you don't have to keep extracting the [...]
whatwg at whatwg.org
whatwg at whatwg.org
Mon Dec 17 15:44:22 PST 2012
Author: ianh
Date: 2012-12-17 15:44:21 -0800 (Mon, 17 Dec 2012)
New Revision: 7589
Modified:
complete.html
index
source
Log:
[giow] (0) Add a way to prepare sprites so you don't have to keep extracting the pixels from the original image, while still allowing the UA to do this cheaply on the backend.
Affected topics: Canvas
Modified: complete.html
===================================================================
--- complete.html 2012-12-17 22:01:22 UTC (rev 7588)
+++ complete.html 2012-12-17 23:44:21 UTC (rev 7589)
@@ -38845,8 +38845,7 @@
<p><img alt="The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle." height=356 src=http://images.whatwg.org/drawImage.png width=356></p>
<p>If the image has no image data, throws an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception. If the
- one of the source rectangle dimensions is zero, throws an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.
- If the image isn't yet fully decoded, then nothing is drawn.</p>
+ image isn't yet fully decoded, then nothing is drawn.</p>
</dd>
@@ -38887,8 +38886,8 @@
</li>
- <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, throw an
- <code><a href=#indexsizeerror>IndexSizeError</a></code> exception and abort these steps.</li>
+ <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, abort
+ these steps. Nothing is painted.</li>
<li>
@@ -75725,14 +75724,17 @@
callback <dfn id=imagebitmapcallback>ImageBitmapCallback</dfn> = void (<a href=#imagebitmap>ImageBitmap</a> image);
+typedef (<a href=#htmlimageelement>HTMLImageElement</a> or
+ <a href=#htmlvideoelement>HTMLVideoElement</a> or
+ <a href=#htmlcanvaselement>HTMLCanvasElement</a> or
+ <a href=#blob>Blob</a> or
+ <a href=#imagedata>ImageData</a> or
+ <a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a> or
+ <a href=#imagebitmap>ImageBitmap</a>) <dfn id=imagebitmapsource>ImageBitmapSource</dfn>;
+
[NoInterfaceObject]
interface <dfn id=imagebitmapfactories>ImageBitmapFactories</dfn> {
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlimageelement>HTMLImageElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlvideoelement>HTMLVideoElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlcanvaselement>HTMLCanvasElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#blob>Blob</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#imagedata>ImageData</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
+ void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#imagebitmapsource>ImageBitmapSource</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback, optional long sx, long sy, long sw, long sh);
};
<a href=#window>Window</a> implements <a href=#imagebitmapfactories>ImageBitmapFactories</a>;
<a href=#workerutils>WorkerUtils</a> implements <a href=#imagebitmapfactories>ImageBitmapFactories</a>;</pre>
@@ -75745,20 +75747,24 @@
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.</p>
- <dl class=domintro><dt><var title="">Window</var> . <code title=dom-createImageBitmap><a href=#dom-createimagebitmap>createImageBitmap</a></code>(<var title="">image</var>, <var title="">callback</var>)</dt>
+ <dl class=domintro><dt><var title="">Window</var> . <code title=dom-createImageBitmap><a href=#dom-createimagebitmap>createImageBitmap</a></code>(<var title="">image</var>, <var title="">callback</var> [, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var> ] )</dt>
<dd>
<p>Takes <var title="">image</var>, which can be an <code><a href=#the-img-element>img</a></code> element,
<code><a href=#the-video-element>video</a></code>, or <code><a href=#the-canvas-element>canvas</a></code> element, a <code><a href=#blob>Blob</a></code> object, an
- <code><a href=#imagedata>ImageData</a></code> object, or a <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object, and
- asynchronously calls <var title="">callback</var> with a new <code><a href=#imagebitmap>ImageBitmap</a></code> as its
- argument when it has created one.</p>
+ <code><a href=#imagedata>ImageData</a></code> object, a <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object, or another
+ <code><a href=#imagebitmap>ImageBitmap</a></code> object, and asynchronously calls <var title="">callback</var> with a
+ new <code><a href=#imagebitmap>ImageBitmap</a></code> as its argument when it has created one.</p>
<p>If no <code><a href=#imagebitmap>ImageBitmap</a></code> object can be constructed, for example because the provided
<var title="">image</var> data is not actually an image, then the <var title="">callback</var>
is invoked with null as the value instead.</p>
+ <p>If <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var title="">sh</var> 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, <em>not</em> in CSS pixels.</p>
+
<p>Throws an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception if the source image is not in a valid
state (e.g. an <code><a href=#the-img-element>img</a></code> element that hasn't finished loading, or a
<code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object whose bitmap data has zero length along one or both
@@ -75785,7 +75791,10 @@
<dd>
- <ol><li><p>If the <code><a href=#the-img-element>img</a></code> element is not <a href=#img-all title=img-all>completely
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#the-img-element>img</a></code> element is not <a href=#img-all title=img-all>completely
available</a>, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these
steps.</li>
@@ -75802,9 +75811,10 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the <code><a href=#the-img-element>img</a></code>
- element's media data. If this is an animated image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</li>
+ element's media data, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>. If this is an animated
+ image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75817,7 +75827,10 @@
<dd>
- <ol><li><p>If the <code><a href=#the-video-element>video</a></code> element's <code title=dom-media-networkState><a href=#dom-media-networkstate>networkState</a></code> attribute is <code title=dom-media-NETWORK_EMPTY><a href=#dom-media-network_empty>NETWORK_EMPTY</a></code>, then throw an
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#the-video-element>video</a></code> element's <code title=dom-media-networkState><a href=#dom-media-networkstate>networkState</a></code> attribute is <code title=dom-media-NETWORK_EMPTY><a href=#dom-media-network_empty>NETWORK_EMPTY</a></code>, then throw an
<code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--ADD-TOPIC:Security-->
@@ -75834,7 +75847,7 @@
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the frame at the
<a href=#current-playback-position>current playback position</a>, at the <a href=#media-resource>media resource</a>'s <a href=#concept-video-intrinsic-width title=concept-video-intrinsic-width>intrinsic width</a> and <a href=#concept-video-intrinsic-height title=concept-video-intrinsic-height>intrinsic height</a> (i.e. after any aspect-ratio
- correction has been applied).</p>
+ correction has been applied), <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>.</p>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75847,7 +75860,11 @@
<dd>
- <ol><!--ADD-TOPIC:Security--><li><p>If the <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data does not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw an
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+<!--ADD-TOPIC:Security-->
+ <li><p>If the <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data does not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw an
<code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--REMOVE-TOPIC:Security-->
@@ -75858,7 +75875,8 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the
- <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data.</li>
+ <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data, <a href=#cropped-to-the-source-rectangle>cropped to the source
+ rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75872,7 +75890,10 @@
<dd>
- <ol><li><p>If the <code><a href=#blob>Blob</a></code> object has been neutered through the <code title=dom-Blob-close>close</code> method, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code>
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#blob>Blob</a></code> object has been neutered through the <code title=dom-Blob-close>close</code> method, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code>
exception and abort these steps.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75893,9 +75914,10 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be the image data read from the
- <code><a href=#blob>Blob</a></code> object. If this is an animated image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</li>
+ <code><a href=#blob>Blob</a></code> object, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>. If this is an animated
+ image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</li>
<li><p><a href=#queue-a-task>Queue a task</a> to invoke <var title="">callback</var> with the new
<code><a href=#imagebitmap>ImageBitmap</a></code> object as its argument.</li>
@@ -75907,10 +75929,13 @@
<dd>
- <ol><li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+ <li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be the image data given by the
- <code><a href=#imagedata>ImageData</a></code> object.</li>
+ <code><a href=#imagedata>ImageData</a></code> object, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75923,7 +75948,11 @@
<dd>
- <ol><!--ADD-TOPIC:Security--><li><p>If the <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a> does
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+<!--ADD-TOPIC:Security-->
+ <li><p>If the <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a> does
not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw
an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--REMOVE-TOPIC:Security-->
@@ -75935,7 +75964,8 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the
- <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a>.</li>
+ <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a>, <a href=#cropped-to-the-source-rectangle>cropped to
+ the source rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75944,9 +75974,99 @@
</ol></dd>
- </dl></div>
+ <dt>If <var title="">image</var> is an <code><a href=#imagebitmap>ImageBitmap</a></code> object
+ <dd>
+
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+
+ <li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the <var title="">image</var> argument's bitmap data, <a href=#cropped-to-the-source-rectangle>cropped to the source
+ rectangle</a>.</li>
+
+ <li><p>Return, but continue running these steps asynchronously.</li>
+
+ <li><p><a href=#queue-a-task>Queue a task</a> to invoke <var title="">callback</var> with the new
+ <code><a href=#imagebitmap>ImageBitmap</a></code> object as its argument.</li>
+
+ </ol></dd>
+
+
+ </dl><p>When the steps above require that the user agent <dfn id=cropped-to-the-source-rectangle title="cropped to the source
+ rectangle">crop bitmap data to the source rectangle</dfn>, the user agent must run the following
+ steps:</p>
+
+ <ol><li><p>Let <var title="">input</var> be the image data being cropped.</li>
+
+ <li><p>If the <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var title="">sh</var> arguments are omitted, return <var title="">input</var>.</li>
+
+ <li><p>Place <var title="">input</var> on an infinite transparent black grid plane, positioned so
+ that it's top left corner is at the origin of the plane, with the <var title="">x</var>-coordinate increasing to the right, and the <var title="">y</var>-coordinate
+ increasing down, and with each pixel in the <var title="">input</var> image data occupying a cell
+ on the plane's grid.</li>
+
+ <li>
+
+ <p>Let <var title="">output</var> be the rectangle on the plane denoted by the rectangle whose
+ corners are the four points (<var title="">sx</var>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>), (<var title="">sx</var>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>).</p>
+
+ <p class=note>If either <var title="">sw</var> or <var title="">sh</var> are negative, then
+ the top-left corner of this rectangle will be to the right and/or above the (<var title="">sx</var>, <var title="">sy</var>) point. If any of the pixels on this rectangle are
+ outside the area where the <var title="">input</var> bitmap was placed, then they will be
+ transparent black in <var title="">output</var>.</p>
+
+ </li>
+
+ <li><p>Let <var title="">output</var>'s pixel density be <var title="">input</var>'s pixel
+ density.</li>
+
+ <li><p>Return <var title="">output</var>.</li>
+
+ </ol></div>
+
+ <div class=example>
+
+ <p>Using this API, a sprite sheet can be precut and prepared:</p>
+
+ <pre>var sprites = {};
+function loadMySprites(loadedCallback) {
+ var pending = 0;
+ function getSpriteAdder(name) {
+ pending += 1;
+ return function (image) {
+ sprites[name] = image;
+ pending -= 1;
+ if (!pending)
+ loadedCallback();
+ };
+ }
+ var image = new Image();
+ image.src = 'mysprites.png';
+ image.onload = function () {
+ createImageBitmap(image, getSpriteAdder('woman'), 0, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('man'), 40, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('tree'), 80, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('hut'), 0, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('apple'), 40, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('snake'), 80, 40, 40, 40);
+ };
+}
+
+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(runDemo);</pre>
+
+ </div>
+
+
<!--TOPIC:HTML-->
<h2 id=editing><span class=secno>8 </span><dfn>User interaction</dfn></h2>
Modified: index
===================================================================
--- index 2012-12-17 22:01:22 UTC (rev 7588)
+++ index 2012-12-17 23:44:21 UTC (rev 7589)
@@ -38845,8 +38845,7 @@
<p><img alt="The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle." height=356 src=http://images.whatwg.org/drawImage.png width=356></p>
<p>If the image has no image data, throws an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception. If the
- one of the source rectangle dimensions is zero, throws an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.
- If the image isn't yet fully decoded, then nothing is drawn.</p>
+ image isn't yet fully decoded, then nothing is drawn.</p>
</dd>
@@ -38887,8 +38886,8 @@
</li>
- <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, throw an
- <code><a href=#indexsizeerror>IndexSizeError</a></code> exception and abort these steps.</li>
+ <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, abort
+ these steps. Nothing is painted.</li>
<li>
@@ -75725,14 +75724,17 @@
callback <dfn id=imagebitmapcallback>ImageBitmapCallback</dfn> = void (<a href=#imagebitmap>ImageBitmap</a> image);
+typedef (<a href=#htmlimageelement>HTMLImageElement</a> or
+ <a href=#htmlvideoelement>HTMLVideoElement</a> or
+ <a href=#htmlcanvaselement>HTMLCanvasElement</a> or
+ <a href=#blob>Blob</a> or
+ <a href=#imagedata>ImageData</a> or
+ <a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a> or
+ <a href=#imagebitmap>ImageBitmap</a>) <dfn id=imagebitmapsource>ImageBitmapSource</dfn>;
+
[NoInterfaceObject]
interface <dfn id=imagebitmapfactories>ImageBitmapFactories</dfn> {
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlimageelement>HTMLImageElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlvideoelement>HTMLVideoElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#htmlcanvaselement>HTMLCanvasElement</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#blob>Blob</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#imagedata>ImageData</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
- void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback);
+ void <a href=#dom-createimagebitmap title=dom-createImageBitmap>createImageBitmap</a>(<a href=#imagebitmapsource>ImageBitmapSource</a> image, <a href=#imagebitmapcallback>ImageBitmapCallback</a> _callback, optional long sx, long sy, long sw, long sh);
};
<a href=#window>Window</a> implements <a href=#imagebitmapfactories>ImageBitmapFactories</a>;
<a href=#workerutils>WorkerUtils</a> implements <a href=#imagebitmapfactories>ImageBitmapFactories</a>;</pre>
@@ -75745,20 +75747,24 @@
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.</p>
- <dl class=domintro><dt><var title="">Window</var> . <code title=dom-createImageBitmap><a href=#dom-createimagebitmap>createImageBitmap</a></code>(<var title="">image</var>, <var title="">callback</var>)</dt>
+ <dl class=domintro><dt><var title="">Window</var> . <code title=dom-createImageBitmap><a href=#dom-createimagebitmap>createImageBitmap</a></code>(<var title="">image</var>, <var title="">callback</var> [, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var> ] )</dt>
<dd>
<p>Takes <var title="">image</var>, which can be an <code><a href=#the-img-element>img</a></code> element,
<code><a href=#the-video-element>video</a></code>, or <code><a href=#the-canvas-element>canvas</a></code> element, a <code><a href=#blob>Blob</a></code> object, an
- <code><a href=#imagedata>ImageData</a></code> object, or a <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object, and
- asynchronously calls <var title="">callback</var> with a new <code><a href=#imagebitmap>ImageBitmap</a></code> as its
- argument when it has created one.</p>
+ <code><a href=#imagedata>ImageData</a></code> object, a <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object, or another
+ <code><a href=#imagebitmap>ImageBitmap</a></code> object, and asynchronously calls <var title="">callback</var> with a
+ new <code><a href=#imagebitmap>ImageBitmap</a></code> as its argument when it has created one.</p>
<p>If no <code><a href=#imagebitmap>ImageBitmap</a></code> object can be constructed, for example because the provided
<var title="">image</var> data is not actually an image, then the <var title="">callback</var>
is invoked with null as the value instead.</p>
+ <p>If <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var title="">sh</var> 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, <em>not</em> in CSS pixels.</p>
+
<p>Throws an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception if the source image is not in a valid
state (e.g. an <code><a href=#the-img-element>img</a></code> element that hasn't finished loading, or a
<code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object whose bitmap data has zero length along one or both
@@ -75785,7 +75791,10 @@
<dd>
- <ol><li><p>If the <code><a href=#the-img-element>img</a></code> element is not <a href=#img-all title=img-all>completely
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#the-img-element>img</a></code> element is not <a href=#img-all title=img-all>completely
available</a>, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these
steps.</li>
@@ -75802,9 +75811,10 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the <code><a href=#the-img-element>img</a></code>
- element's media data. If this is an animated image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</li>
+ element's media data, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>. If this is an animated
+ image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75817,7 +75827,10 @@
<dd>
- <ol><li><p>If the <code><a href=#the-video-element>video</a></code> element's <code title=dom-media-networkState><a href=#dom-media-networkstate>networkState</a></code> attribute is <code title=dom-media-NETWORK_EMPTY><a href=#dom-media-network_empty>NETWORK_EMPTY</a></code>, then throw an
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#the-video-element>video</a></code> element's <code title=dom-media-networkState><a href=#dom-media-networkstate>networkState</a></code> attribute is <code title=dom-media-NETWORK_EMPTY><a href=#dom-media-network_empty>NETWORK_EMPTY</a></code>, then throw an
<code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--ADD-TOPIC:Security-->
@@ -75834,7 +75847,7 @@
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the frame at the
<a href=#current-playback-position>current playback position</a>, at the <a href=#media-resource>media resource</a>'s <a href=#concept-video-intrinsic-width title=concept-video-intrinsic-width>intrinsic width</a> and <a href=#concept-video-intrinsic-height title=concept-video-intrinsic-height>intrinsic height</a> (i.e. after any aspect-ratio
- correction has been applied).</p>
+ correction has been applied), <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>.</p>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75847,7 +75860,11 @@
<dd>
- <ol><!--ADD-TOPIC:Security--><li><p>If the <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data does not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw an
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+<!--ADD-TOPIC:Security-->
+ <li><p>If the <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data does not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw an
<code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--REMOVE-TOPIC:Security-->
@@ -75858,7 +75875,8 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the
- <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data.</li>
+ <code><a href=#the-canvas-element>canvas</a></code> element's bitmap data, <a href=#cropped-to-the-source-rectangle>cropped to the source
+ rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75872,7 +75890,10 @@
<dd>
- <ol><li><p>If the <code><a href=#blob>Blob</a></code> object has been neutered through the <code title=dom-Blob-close>close</code> method, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code>
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>If the <code><a href=#blob>Blob</a></code> object has been neutered through the <code title=dom-Blob-close>close</code> method, then throw an <code><a href=#invalidstateerror>InvalidStateError</a></code>
exception and abort these steps.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75893,9 +75914,10 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be the image data read from the
- <code><a href=#blob>Blob</a></code> object. If this is an animated image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</li>
+ <code><a href=#blob>Blob</a></code> object, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>. If this is an animated
+ image, the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</li>
<li><p><a href=#queue-a-task>Queue a task</a> to invoke <var title="">callback</var> with the new
<code><a href=#imagebitmap>ImageBitmap</a></code> object as its argument.</li>
@@ -75907,10 +75929,13 @@
<dd>
- <ol><li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+ <li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be the image data given by the
- <code><a href=#imagedata>ImageData</a></code> object.</li>
+ <code><a href=#imagedata>ImageData</a></code> object, <a href=#cropped-to-the-source-rectangle>cropped to the source rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75923,7 +75948,11 @@
<dd>
- <ol><!--ADD-TOPIC:Security--><li><p>If the <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a> does
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+<!--ADD-TOPIC:Security-->
+ <li><p>If the <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a> does
not have its <a href=#concept-canvas-origin-clean title=concept-canvas-origin-clean>origin-clean</a> flag set, then throw
an <code><a href=#invalidstateerror>InvalidStateError</a></code> exception and abort these steps.</li>
<!--REMOVE-TOPIC:Security-->
@@ -75935,7 +75964,8 @@
<li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
<li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the
- <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a>.</li>
+ <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object's <a href=#scratch-bitmap>scratch bitmap</a>, <a href=#cropped-to-the-source-rectangle>cropped to
+ the source rectangle</a>.</li>
<li><p>Return, but continue running these steps asynchronously.</li>
@@ -75944,9 +75974,99 @@
</ol></dd>
- </dl></div>
+ <dt>If <var title="">image</var> is an <code><a href=#imagebitmap>ImageBitmap</a></code> object
+ <dd>
+
+ <ol><li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception.</li>
+
+ <li><p>Create a new <code><a href=#imagebitmap>ImageBitmap</a></code> object.</li>
+
+ <li><p>Let the <code><a href=#imagebitmap>ImageBitmap</a></code> object's bitmap data be a copy of the <var title="">image</var> argument's bitmap data, <a href=#cropped-to-the-source-rectangle>cropped to the source
+ rectangle</a>.</li>
+
+ <li><p>Return, but continue running these steps asynchronously.</li>
+
+ <li><p><a href=#queue-a-task>Queue a task</a> to invoke <var title="">callback</var> with the new
+ <code><a href=#imagebitmap>ImageBitmap</a></code> object as its argument.</li>
+
+ </ol></dd>
+
+
+ </dl><p>When the steps above require that the user agent <dfn id=cropped-to-the-source-rectangle title="cropped to the source
+ rectangle">crop bitmap data to the source rectangle</dfn>, the user agent must run the following
+ steps:</p>
+
+ <ol><li><p>Let <var title="">input</var> be the image data being cropped.</li>
+
+ <li><p>If the <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var title="">sh</var> arguments are omitted, return <var title="">input</var>.</li>
+
+ <li><p>Place <var title="">input</var> on an infinite transparent black grid plane, positioned so
+ that it's top left corner is at the origin of the plane, with the <var title="">x</var>-coordinate increasing to the right, and the <var title="">y</var>-coordinate
+ increasing down, and with each pixel in the <var title="">input</var> image data occupying a cell
+ on the plane's grid.</li>
+
+ <li>
+
+ <p>Let <var title="">output</var> be the rectangle on the plane denoted by the rectangle whose
+ corners are the four points (<var title="">sx</var>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <var title="">sy</var>), (<span title=""><var title="">sx</var>+<var title="">sw</var></span>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>), (<var title="">sx</var>, <span title=""><var title="">sy</var>+<var title="">sh</var></span>).</p>
+
+ <p class=note>If either <var title="">sw</var> or <var title="">sh</var> are negative, then
+ the top-left corner of this rectangle will be to the right and/or above the (<var title="">sx</var>, <var title="">sy</var>) point. If any of the pixels on this rectangle are
+ outside the area where the <var title="">input</var> bitmap was placed, then they will be
+ transparent black in <var title="">output</var>.</p>
+
+ </li>
+
+ <li><p>Let <var title="">output</var>'s pixel density be <var title="">input</var>'s pixel
+ density.</li>
+
+ <li><p>Return <var title="">output</var>.</li>
+
+ </ol></div>
+
+ <div class=example>
+
+ <p>Using this API, a sprite sheet can be precut and prepared:</p>
+
+ <pre>var sprites = {};
+function loadMySprites(loadedCallback) {
+ var pending = 0;
+ function getSpriteAdder(name) {
+ pending += 1;
+ return function (image) {
+ sprites[name] = image;
+ pending -= 1;
+ if (!pending)
+ loadedCallback();
+ };
+ }
+ var image = new Image();
+ image.src = 'mysprites.png';
+ image.onload = function () {
+ createImageBitmap(image, getSpriteAdder('woman'), 0, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('man'), 40, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('tree'), 80, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('hut'), 0, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('apple'), 40, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('snake'), 80, 40, 40, 40);
+ };
+}
+
+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(runDemo);</pre>
+
+ </div>
+
+
<!--TOPIC:HTML-->
<h2 id=editing><span class=secno>8 </span><dfn>User interaction</dfn></h2>
Modified: source
===================================================================
--- source 2012-12-17 22:01:22 UTC (rev 7588)
+++ source 2012-12-17 23:44:21 UTC (rev 7589)
@@ -45384,8 +45384,7 @@
<p><img src="images/drawImage.png" width="356" height="356" alt="The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle."></p>
<p>If the image has no image data, throws an <code>InvalidStateError</code> exception. If the
- one of the source rectangle dimensions is zero, throws an <code>IndexSizeError</code> exception.
- If the image isn't yet fully decoded, then nothing is drawn.</p>
+ image isn't yet fully decoded, then nothing is drawn.</p>
</dd>
@@ -45440,8 +45439,8 @@
</li>
- <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, throw an
- <code>IndexSizeError</code> exception and abort these steps.</p></li>
+ <li><p>If one of the <var title="">sw</var> or <var title="">sh</var> arguments is zero, abort
+ these steps. Nothing is painted.</p></li>
<li>
@@ -88489,14 +88488,17 @@
callback <dfn>ImageBitmapCallback</dfn> = void (<span>ImageBitmap</span> image);
+typedef (<span>HTMLImageElement</span> or
+ <span>HTMLVideoElement</span> or
+ <span>HTMLCanvasElement</span> or
+ <span>Blob</span> or
+ <span>ImageData</span> or
+ <span>CanvasRenderingContext2D</span> or
+ <span>ImageBitmap</span>) <dfn>ImageBitmapSource</dfn>;
+
[NoInterfaceObject]
interface <dfn>ImageBitmapFactories</dfn> {
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>HTMLImageElement</span> image, <span>ImageBitmapCallback</span> _callback);
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>HTMLVideoElement</span> image, <span>ImageBitmapCallback</span> _callback);
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>HTMLCanvasElement</span> image, <span>ImageBitmapCallback</span> _callback);
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>Blob</span> image, <span>ImageBitmapCallback</span> _callback);
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>ImageData</span> image, <span>ImageBitmapCallback</span> _callback);
- void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>CanvasRenderingContext2D</span> image, <span>ImageBitmapCallback</span> _callback);
+ void <span title="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, <span>ImageBitmapCallback</span> _callback, optional long sx, long sy, long sw, long sh);
};
<span>Window</span> implements <span>ImageBitmapFactories</span>;
<span>WorkerUtils</span> implements <span>ImageBitmapFactories</span>;</pre>
@@ -88511,20 +88513,25 @@
<dl class="domintro">
- <dt><var title="">Window</var> . <code title="dom-createImageBitmap">createImageBitmap</code>(<var title="">image</var>, <var title="">callback</var>)</dt>
+ <dt><var title="">Window</var> . <code title="dom-createImageBitmap">createImageBitmap</code>(<var title="">image</var>, <var title="">callback</var> [, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var> ] )</dt>
<dd>
<p>Takes <var title="">image</var>, which can be an <code>img</code> element,
<code>video</code>, or <code>canvas</code> element, a <code>Blob</code> object, an
- <code>ImageData</code> object, or a <code>CanvasRenderingContext2D</code> object, and
- asynchronously calls <var title="">callback</var> with a new <code>ImageBitmap</code> as its
- argument when it has created one.</p>
+ <code>ImageData</code> object, a <code>CanvasRenderingContext2D</code> object, or another
+ <code>ImageBitmap</code> object, and asynchronously calls <var title="">callback</var> with a
+ new <code>ImageBitmap</code> as its argument when it has created one.</p>
<p>If no <code>ImageBitmap</code> object can be constructed, for example because the provided
<var title="">image</var> data is not actually an image, then the <var title="">callback</var>
is invoked with null as the value instead.</p>
+ <p>If <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var
+ title="">sh</var> 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, <em>not</em> in CSS pixels.</p>
+
<p>Throws an <code>InvalidStateError</code> exception if the source image is not in a valid
state (e.g. an <code>img</code> element that hasn't finished loading, or a
<code>CanvasRenderingContext2D</code> object whose bitmap data has zero length along one or both
@@ -88558,6 +88565,9 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<li><p>If the <code>img</code> element is not <span title="img-all">completely
available</span>, then throw an <code>InvalidStateError</code> exception and abort these
steps.</p></li>
@@ -88575,9 +88585,10 @@
<li><p>Create a new <code>ImageBitmap</code> object.</p></li>
<li><p>Let the <code>ImageBitmap</code> object's bitmap data be a copy of the <code>img</code>
- element's media data. If this is an animated image, the <code>ImageBitmap</code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</p></li>
+ element's media data, <span>cropped to the source rectangle</span>. If this is an animated
+ image, the <code>ImageBitmap</code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</p></li>
<li><p>Return, but continue running these steps asynchronously.</p></li>
@@ -88594,6 +88605,9 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<li><p>If the <code>video</code> element's <code
title="dom-media-networkState">networkState</code> attribute is <code
title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</code>, then throw an
@@ -88616,7 +88630,7 @@
<span>current playback position</span>, at the <span>media resource</span>'s <span
title="concept-video-intrinsic-width">intrinsic width</span> and <span
title="concept-video-intrinsic-height">intrinsic height</span> (i.e. after any aspect-ratio
- correction has been applied).</p>
+ correction has been applied), <span>cropped to the source rectangle</span>.</p>
<li><p>Return, but continue running these steps asynchronously.</p></li>
@@ -88633,6 +88647,9 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<!--ADD-TOPIC:Security-->
<li><p>If the <code>canvas</code> element's bitmap data does not have its <span
title="concept-canvas-origin-clean">origin-clean</span> flag set, then throw an
@@ -88646,7 +88663,8 @@
<li><p>Create a new <code>ImageBitmap</code> object.</p></li>
<li><p>Let the <code>ImageBitmap</code> object's bitmap data be a copy of the
- <code>canvas</code> element's bitmap data.</p></li>
+ <code>canvas</code> element's bitmap data, <span>cropped to the source
+ rectangle</span>.</p></li>
<li><p>Return, but continue running these steps asynchronously.</p></li>
@@ -88664,6 +88682,9 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<li><p>If the <code>Blob</code> object has been neutered through the <code
title="dom-Blob-close">close</code> method, then throw an <code>InvalidStateError</code>
exception and abort these steps.</p></li>
@@ -88687,9 +88708,10 @@
<li><p>Create a new <code>ImageBitmap</code> object.</p></li>
<li><p>Let the <code>ImageBitmap</code> object's bitmap data be the image data read from the
- <code>Blob</code> object. If this is an animated image, the <code>ImageBitmap</code> object's
- bitmap data must only consist of the animation's poster frame, or, if there is no poster frame,
- the first frame of the animation.</p></li>
+ <code>Blob</code> object, <span>cropped to the source rectangle</span>. If this is an animated
+ image, the <code>ImageBitmap</code> object's bitmap data must only be taken from the
+ animation's poster frame, or, if there is no poster frame, the first frame of the
+ animation.</p></li>
<li><p><span>Queue a task</span> to invoke <var title="">callback</var> with the new
<code>ImageBitmap</code> object as its argument.</p></li>
@@ -88705,10 +88727,13 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<li><p>Create a new <code>ImageBitmap</code> object.</p></li>
<li><p>Let the <code>ImageBitmap</code> object's bitmap data be the image data given by the
- <code>ImageData</code> object.</p></li>
+ <code>ImageData</code> object, <span>cropped to the source rectangle</span>.</p></li>
<li><p>Return, but continue running these steps asynchronously.</p></li>
@@ -88725,6 +88750,9 @@
<ol>
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
<!--ADD-TOPIC:Security-->
<li><p>If the <code>CanvasRenderingContext2D</code> object's <span>scratch bitmap</span> does
not have its <span title="concept-canvas-origin-clean">origin-clean</span> flag set, then throw
@@ -88738,7 +88766,8 @@
<li><p>Create a new <code>ImageBitmap</code> object.</p></li>
<li><p>Let the <code>ImageBitmap</code> object's bitmap data be a copy of the
- <code>CanvasRenderingContext2D</code> object's <span>scratch bitmap</span>.</p></li>
+ <code>CanvasRenderingContext2D</code> object's <span>scratch bitmap</span>, <span>cropped to
+ the source rectangle</span>.</p></li>
<li><p>Return, but continue running these steps asynchronously.</p></li>
@@ -88749,11 +88778,117 @@
</dd>
+
+ <dt>If <var title="">image</var> is an <code>ImageBitmap</code> object
+
+ <dd>
+
+ <ol>
+
+ <li><p>If either the <var title="">sw</var> or <var title="">sh</var> arguments are specified
+ but zero, throw an <code>IndexSizeError</code> exception.</p></li>
+
+ <li><p>Create a new <code>ImageBitmap</code> object.</p></li>
+
+ <li><p>Let the <code>ImageBitmap</code> object's bitmap data be a copy of the <var
+ title="">image</var> argument's bitmap data, <span>cropped to the source
+ rectangle</span>.</p></li>
+
+ <li><p>Return, but continue running these steps asynchronously.</p></li>
+
+ <li><p><span>Queue a task</span> to invoke <var title="">callback</var> with the new
+ <code>ImageBitmap</code> object as its argument.</p></li>
+
+ </ol>
+
+ </dd>
+
+
</dl>
+ <p>When the steps above require that the user agent <dfn title="cropped to the source
+ rectangle">crop bitmap data to the source rectangle</dfn>, the user agent must run the following
+ steps:</p>
+
+ <ol>
+
+ <li><p>Let <var title="">input</var> be the image data being cropped.</p></li>
+
+ <li><p>If the <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, and <var
+ title="">sh</var> arguments are omitted, return <var title="">input</var>.</p></li>
+
+ <li><p>Place <var title="">input</var> on an infinite transparent black grid plane, positioned so
+ that it's top left corner is at the origin of the plane, with the <var
+ title="">x</var>-coordinate increasing to the right, and the <var title="">y</var>-coordinate
+ increasing down, and with each pixel in the <var title="">input</var> image data occupying a cell
+ on the plane's grid.</p></li>
+
+ <li>
+
+ <p>Let <var title="">output</var> be the rectangle on the plane denoted by the rectangle whose
+ corners are the four points (<var title="">sx</var>, <var title="">sy</var>), (<span
+ title=""><var title="">sx</var>+<var title="">sw</var></span>, <var title="">sy</var>), (<span
+ title=""><var title="">sx</var>+<var title="">sw</var></span>, <span title=""><var
+ title="">sy</var>+<var title="">sh</var></span>), (<var title="">sx</var>, <span title=""><var
+ title="">sy</var>+<var title="">sh</var></span>).</p>
+
+ <p class="note">If either <var title="">sw</var> or <var title="">sh</var> are negative, then
+ the top-left corner of this rectangle will be to the right and/or above the (<var
+ title="">sx</var>, <var title="">sy</var>) point. If any of the pixels on this rectangle are
+ outside the area where the <var title="">input</var> bitmap was placed, then they will be
+ transparent black in <var title="">output</var>.</p>
+
+ </li>
+
+ <li><p>Let <var title="">output</var>'s pixel density be <var title="">input</var>'s pixel
+ density.</p></li>
+
+ <li><p>Return <var title="">output</var>.</p></li>
+
+ </ol>
+
</div>
+ <div class="example">
+ <p>Using this API, a sprite sheet can be precut and prepared:</p>
+
+ <pre>var sprites = {};
+function loadMySprites(loadedCallback) {
+ var pending = 0;
+ function getSpriteAdder(name) {
+ pending += 1;
+ return function (image) {
+ sprites[name] = image;
+ pending -= 1;
+ if (!pending)
+ loadedCallback();
+ };
+ }
+ var image = new Image();
+ image.src = 'mysprites.png';
+ image.onload = function () {
+ createImageBitmap(image, getSpriteAdder('woman'), 0, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('man'), 40, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('tree'), 80, 0, 40, 40);
+ createImageBitmap(image, getSpriteAdder('hut'), 0, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('apple'), 40, 40, 40, 40);
+ createImageBitmap(image, getSpriteAdder('snake'), 80, 40, 40, 40);
+ };
+}
+
+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(runDemo);</pre>
+
+ </div>
+
+
<!--TOPIC:HTML-->
<h2 id="editing"><dfn>User interaction</dfn></h2>
More information about the Commit-Watchers
mailing list