- From: poot <cvsmail@w3.org>
- Date: Thu, 12 May 2011 16:43:59 -0400
- To: public-html-diffs@w3.org
hixie: Attempt to define canvas.toBlob(). (whatwg r6134) http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.4933&r2=1.4934&f=h http://html5.org/tools/web-apps-tracker?from=6133&to=6134 =================================================================== RCS file: /sources/public/html5/spec/Overview.html,v retrieving revision 1.4933 retrieving revision 1.4934 diff -u -d -r1.4933 -r1.4934 --- Overview.html 12 May 2011 19:10:24 -0000 1.4933 +++ Overview.html 12 May 2011 20:40:49 -0000 1.4934 @@ -27035,6 +27035,8 @@ attribute unsigned long <a href="#dom-canvas-height" title="dom-canvas-height">height</a>; DOMString <a href="#dom-canvas-todataurl" title="dom-canvas-toDataURL">toDataURL</a>(in optional DOMString type, in any... args); + void <a href="#dom-canvas-toblob" title="dom-canvas-toBlob">toBlob</a>(in <span>FileCallback</span>, in optional DOMString type, in any... args); + object <a href="#dom-canvas-getcontext" title="dom-canvas-getContext">getContext</a>(in DOMString contextId, in any... args); };</pre> </dd> @@ -27237,70 +27239,117 @@ type, and control the way that the image is generated, as given in the table below.</p> + <p>When trying to use types other than "<code>image/png</code>", + authors can check if the image was really returned in the + requested format by checking to see if the returned string starts + with one of the exact strings "<code title="">data:image/png,</code>" or "<code title="">data:image/png;</code>". If it does, the image is PNG, + and thus the requested type was not supported. (The one exception + to this is if the canvas has either no height or no width, in + which case the result might simply be "<code title="">data:,</code>".)</p> + </dd> - + <dt><var title="">canvas</var> . <code title="dom-canvas-toBlob"><a href="#dom-canvas-toblob">toBlob</a></code>(<var title="">callback</var> [, <var title="">type</var>, ... ])</dt> + + <dd> + + <p>Creates a <code><a href="#blob">Blob</a></code> object representing a file + containing the image in the canvas, and invokes a callback with a + handle to that object.</p> + + <p>The second argument, if provided, controls the type of the + image to be returned (e.g. PNG or JPEG). The default is <code title="">image/png</code>; that type is also used if the given + type isn't supported. The other arguments are specific to the + type, and control the way that the image is generated, as given in + the table below.</p> + + </dd> </dl><div class="impl"> <p>The <dfn id="dom-canvas-todataurl" title="dom-canvas-toDataURL"><code>toDataURL()</code></dfn> method - must, when called with no arguments, return a <a href="#data-protocol" title="data - protocol"><code title="">data:</code> URL</a> containing a - representation of the image as a PNG file. <a href="#refsPNG">[PNG]</a> <a href="#refsRFC2397">[RFC2397]</a></p> + must run the following steps:</p> + <ol><li><p>If the canvas has no pixels (i.e. either its horizontal + dimension or its vertical dimension is zero) then return the string + "<code title="">data:,</code>" and abort these steps. (This is the + shortest <a href="#data-protocol" title="data protocol"><code title="">data:</code> + URL</a>; it represents the empty string in a <code title="">text/plain</code> resource.)</li> - <p>If the canvas has no pixels (i.e. either its horizontal dimension - or its vertical dimension is zero) then the method must return the - string "<code title="">data:,</code>". (This is the shortest <a href="#data-protocol" title="data protocol"><code title="">data:</code> URL</a>; it - represents the empty string in a <code title="">text/plain</code> - resource.)</p> + <li><p>Let <var title="">file</var> be <a href="#a-serialization-of-the-image-as-a-file">a serialization of the + image as a file</a>, using the method's arguments (if any) as + the <var title="">arguments</var>.</li> - <p>When the <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL(<var title="">type</var>)</a></code> method is called with one <em>or - more</em> arguments, it must return a <a href="#data-protocol" title="data - protocol"><code title="">data:</code> URL</a> containing a - representation of the image in the format given by <var title="">type</var>. The possible values are <a href="#mime-type" title="MIME - type">MIME types</a> with no parameters, for example - <code>image/png</code>, <code>image/jpeg</code>, or even maybe - <code>image/svg+xml</code> if the implementation actually keeps - enough information to reliably render an SVG image from the - canvas.</p> + <li><p>Return a <a href="#data-protocol" title="data protocol"><code title="">data:</code> URL</a> representing <var title="">file</var>. <a href="#refsRFC2397">[RFC2397]</a></p> - <p>For image types that do not support an alpha channel, the image - must be composited onto a solid black background using the - source-over operator, and the resulting image must be the one used - to create the <a href="#data-protocol" title="data protocol"><code title="">data:</code> URL</a>.</p> + + </ol><p>The <dfn id="dom-canvas-toblob" title="dom-canvas-toBlob"><code>toBlob()</code></dfn> method + must run the following steps:</p> - <p>Only support for <code>image/png</code> is required. User agents - may support other types. If the user agent does not support the - requested type, it must return the image using the PNG format.</p> + <ol><li><p>Let <var title="">callback</var> be the first + argument.</li> + + <li><p>Let <var title="">arguments</var> be the second and + subsequent arguments to the method, if any.</li> + + <li><p>Let <var title="">file</var> be <a href="#a-serialization-of-the-image-as-a-file">a serialization of the + image as a file</a>, using <var title="">arguments</var>.</li> + + <li><p>Return, but continue running these steps + asynchronously.</li> + + <li><p>If <var title="">callback</var> is null, abort these + steps.</li> + + <li><p><a href="#queue-a-task">Queue a task</a> to invoke the + <code>FileCallback</code> <var title="">callback</var> with a + <code><a href="#blob">Blob</a></code> object representing <var title="">file</var> as + its argument. The <a href="#task-source">task source</a> for this task is the + <dfn id="canvas-blob-serialization-task-source">canvas blob serialization task source</dfn>. <a href="#refsFILESYSTEMAPI">[FILESYSTEMAPI]</a> <a href="#refsFILEAPI">[FILEAPI]</a> </li> + + </ol><p>When a user agent is to create <dfn id="a-serialization-of-the-image-as-a-file">a serialization of the image + as a file</dfn>, optionally with some given <var title="">arguments</var>, it must create an image file in the format + given by the first value of <var title="">arguments</var>, or, if + there are no <var title="">arguments</var>, in the PNG format. <a href="#refsPNG">[PNG]</a></p> + + <p>If <var title="">arguments</var> is not empty, the first value + must be interpreted as a <a href="#mime-type" title="MIME type">MIME type</a> + giving the format to use. If the type has any parameters, it must be + treated as not supported.</p> + + <p class="example">For example, the value "<code>image/png</code>" would + mean to generate a PNG image, the value "<code>image/jpeg</code>" + would mean to generate a JPEG image, and the value + "<code>image/svg+xml</code>" would mean to generate an SVG image + (which would probably require that the implementation actually keep + enough information to reliably render an SVG image from the canvas).</p> + + <p>User agents must support PNG ("<code>image/png</code>"). User + agents may support other types. If the user agent does not support + the requested type, it must create the file using the PNG format. <a href="#refsPNG">[PNG]</a></p> <p>User agents must <a href="#converted-to-ascii-lowercase" title="converted to ASCII lowercase">convert the provided type to ASCII lowercase</a> - before establishing if they support that type and before creating - the <a href="#data-protocol" title="data protocol"><code title="">data:</code> - URL</a>.</p> + before establishing if they support that type.</p> - </div><p class="note">When trying to use types other than - <code>image/png</code>, authors can check if the image was really - returned in the requested format by checking to see if the returned - string starts with one of the exact strings "<code title="">data:image/png,</code>" or "<code title="">data:image/png;</code>". If it does, the image is PNG, and - thus the requested type was not supported. (The one exception to - this is if the canvas has either no height or no width, in which - case the result might simply be "<code title="">data:,</code>".)<div class="impl"> + <p>For image types that do not support an alpha channel, the + serialized image must be the canvas image composited onto a solid + black background using the source-over operator.</p> - <p>If the method is invoked with the first argument giving a type - corresponding to one of the types given in the first column of the - following table, and the user agent supports that type, then the + <p>If the first argument in <var title="">arguments</var> gives a + type corresponding to one of the types given in the first column of + the following table, and the user agent supports that type, then the subsequent arguments, if any, must be treated as described in the second cell of that row.</p> - </div><table><thead><tr><th> Type <th> Other arguments - <tbody><tr><td> image/jpeg + </div><table><thead><tr><th> Type <th> Other arguments <th> Reference + <tbody><tr><td> <code>image/jpeg</code> <td> The second argument<span class="impl">, if it</span> is a number in the range 0.0 to 1.0 inclusive<span class="impl">, must be</span> treated as the desired quality level. <span class="impl">If it is not a number or is outside that range, the user agent must use its default value, as if the argument had been omitted.</span> + <td> <a href="#refsJPEG">[JPEG]</a> </table><div class="impl"> <p>For the purposes of these rules, an argument is considered to be @@ -27310,11 +27359,10 @@ <p>Other arguments must be ignored and must not cause the user agent to raise an exception. A future version of this specification will - probably define other parameters to be passed to <code title="dom-canvas-toDataURL"><a href="#dom-canvas-todataurl">toDataURL()</a></code> to allow authors to - more carefully control compression settings, image metadata, - etc.</p> + probably define other parameters to be passed to these methods to + allow authors to more carefully control compression settings, image + metadata, etc.</p> - </div><div class="impl"> <h5 id="color-spaces-and-color-correction"><span class="secno">4.8.11.1 </span>Color spaces and color correction</h5> @@ -28651,7 +28699,7 @@ tables is a common default.)<p>In speech media, table cells can be distinguished by reporting the corresponding headers before reading the cell's contents, and by allowing users to navigate the table in a grid fashion, rather than - serialising the entire contents of the table in source order.<p>Authors are encouraged to use CSS to achieve these effects.<div class="impl"> + serializing the entire contents of the table in source order.<p>Authors are encouraged to use CSS to achieve these effects.<div class="impl"> <p>User agents are encouraged to render tables using these techniques whenever the page does not use CSS and the table is not classified as a layout table.</p> @@ -71001,6 +71049,10 @@ <dd><cite><a href="http://dev.w3.org/2006/webapi/FileUpload/publish/FileAPI.html">File API</a></cite>, A. Ranganathan. W3C.</dd> + <dt id="refsFILESYSTEMAPI">[FILESYSTEMAPI]</dt> + <dd><cite><a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">File + API: Directories and System</a></cite>, E. Uhrhane. W3C.</dd> + <dt id="refsGBK">[GBK]</dt> <dd><cite>Chinese Internal Code Specification</cite>. Chinese IT Standardization Technical Committee.</dd> @@ -71048,6 +71100,9 @@ character sets — Part 11: Latin/Thai alphabet</a></cite>. ISO.</dd> + <dt id="refsJPEG">[JPEG]</dt> + <dd><cite><a href="http://www.w3.org/Graphics/JPEG/jfif3.pdf">JPEG File Interchange Format</a></cite>, E. Hamilton.</dd> + <dt id="refsJSURL">[JSURL]</dt> <dd><cite><a href="http://tools.ietf.org/html/draft-hoehrmann-javascript-scheme">The 'javascript' resource identifier scheme</a></cite>, @@ -71726,6 +71781,7 @@ Krzysztof Maczyński, 黒澤剛志 (Kurosawa Takeshi), Kyle Hofmann, + Kyle Huey, Léonard Bouchet, Lachlan Hunt, Larry Masinter,
Received on Thursday, 12 May 2011 20:44:01 UTC