Skip to content
Permalink
Browse files

[giow] (0) Attempt to define canvas.toBlob().

git-svn-id: http://svn.whatwg.org/webapps@6134 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
Hixie committed May 12, 2011
1 parent 853d182 commit 7a17888620bf27c84b10ec5cf87bda639208aeb3
Showing with 344 additions and 194 deletions.
  1. +107 −62 complete.html
  2. +107 −62 index
  3. +130 −70 source
attribute unsigned long <a href=#dom-canvas-width title=dom-canvas-width>width</a>;
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);<!--
v5:
void <span title="dom-canvas-toBlob">toBlob</span>(in <span>FileCallback</span>, in optional DOMString type, in any... args);-->
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>
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>

<!-- v5: toBlob -->
<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>

<!--
v5:
void <span title="dom-canvas-toBlob">toBlob</span>(in <span>FileCallback</span>, in optional DOMString type, in any... args);
-->
<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>

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

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

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

</div>
<!-- should we explicitly require the URL to be base64-encoded and
not have any parameters, to ensure the same exact URL is generated
in each browser? -->

</ol><p>The <dfn id=dom-canvas-toblob title=dom-canvas-toBlob><code>toBlob()</code></dfn> method
must run the following steps:</p>

<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>".)</p>
<ol><li><p>Let <var title="">callback</var> be the first
argument.</li>

<div class=impl>
<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>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>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.</p>

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

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

<!-- should we explicitly require the URL to be base64-encoded and
not have any parameters, to ensure the same exact URL is generated
in each browser? -->
probably define other parameters to be passed to these methods to
allow authors to more carefully control compression settings, image
metadata, etc.</p>

</div>

<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>
serializing the entire contents of the table in source order.</p>

<p>Authors are encouraged to use CSS to achieve these effects.</p>

<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>
character sets &mdash; 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=refsJSON>[JSON]</dt>
<dd><cite><a href=http://tools.ietf.org/html/rfc4627>The
application/json Media Type for JavaScript Object Notation
Krzysztof Maczy&#324;ski,
&#40658;&#28580;&#21083;&#24535; (Kurosawa Takeshi),
Kyle Hofmann<!-- Ozob -->,
Kyle Huey,
L&eacute;onard Bouchet,
Lachlan Hunt,
Larry Masinter,

0 comments on commit 7a17888

Please sign in to comment.