Skip to content

Commit 7d25c4c

Browse files
authored
Make quality an explicit argument for canvas image conversion
Fixes whatwg#452, by making canvas's toDataURL and toBlob explicitly accept a quality argument. This replaces the generic argument-passing infrastructure that was in place previously, but was only used for JPEG quality. While there: - Allowed the quality argument to be used by any format that has variable quality, such as WebP, since (according to https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) Chrome supports it alongside a type of "image/webp" - Removed the now-unused "native flag" from this section
1 parent e1158b8 commit 7d25c4c

File tree

1 file changed

+45
-77
lines changed

1 file changed

+45
-77
lines changed

source

Lines changed: 45 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -59033,8 +59033,8 @@ interface <dfn>HTMLCanvasElement</dfn> : <span>HTMLElement</span> {
5903359033

5903459034
<span>RenderingContext</span>? <span data-x="dom-canvas-getContext">getContext</span>(DOMString contextId, any... arguments);
5903559035

59036-
USVString <span data-x="dom-canvas-toDataURL">toDataURL</span>(optional DOMString type, any... arguments);
59037-
void <span data-x="dom-canvas-toBlob">toBlob</span>(<span>BlobCallback</span> _callback, optional DOMString type, any... arguments);
59036+
USVString <span data-x="dom-canvas-toDataURL">toDataURL</span>(optional DOMString type, optional any quality);
59037+
void <span data-x="dom-canvas-toBlob">toBlob</span>(<span>BlobCallback</span> _callback, optional DOMString type, optional any quality);
5903859038
};
5903959039

5904059040
callback <dfn>BlobCallback</dfn> = void (<span>Blob</span>? blob);</pre>
@@ -59300,18 +59300,18 @@ callback <dfn>BlobCallback</dfn> = void (<span>Blob</span>? blob);</pre>
5930059300

5930159301
<dl class="domintro">
5930259302

59303-
<dt><var>url</var> = <var>canvas</var> . <code subdfn data-x="dom-canvas-toDataURL">toDataURL</code>( [ <var>type</var>, ... ] )</dt>
59303+
<dt><var>url</var> = <var>canvas</var> . <code subdfn data-x="dom-canvas-toDataURL">toDataURL</code>( [ <var>type</var> [, <var>quality</var> ] ] )</dt>
5930459304

5930559305
<dd>
5930659306

5930759307
<p>Returns a <span data-x="data protocol"><code>data:</code> URL</span> for the image in the
5930859308
canvas.</p>
5930959309

5931059310
<p>The first argument, if provided, controls the type of the image to be returned (e.g. PNG or
59311-
JPEG). The default is <code data-x="">image/png</code>; that type is also used if the given type
59312-
isn't supported. The other arguments are specific to the type, and control the way that the
59313-
image is generated, as given <a href="#canvas-serialisation-arguments">in the table
59314-
below</a>.</p>
59311+
JPEG). The default is "<code>image/png</code>"; that type is also used if the given type isn't
59312+
supported. The second argument applies if the type is an image format that supports variable
59313+
quality (such as "<code>image/jpeg</code>"), and is a number in the range 0.0 to 1.0 inclusive
59314+
indicating the desired quality level for the resulting image.</p>
5931559315

5931659316
<p>When trying to use types other than "<code>image/png</code>", authors can check if the image
5931759317
was really returned in the requested format by checking to see if the returned string starts
@@ -59322,45 +59322,45 @@ callback <dfn>BlobCallback</dfn> = void (<span>Blob</span>? blob);</pre>
5932259322

5932359323
</dd>
5932459324

59325-
<dt><var>canvas</var> . <code subdfn data-x="dom-canvas-toBlob">toBlob</code>(<var>callback</var> [, <var>type</var>, ... ] )</dt>
59325+
<dt><var>canvas</var> . <code subdfn data-x="dom-canvas-toBlob">toBlob</code>(<var>callback</var> [, <var>type</var> [, quality ] ] )</dt>
5932659326

5932759327
<dd>
5932859328

5932959329
<p>Creates a <code>Blob</code> object representing a file containing the image in the canvas,
5933059330
and invokes a callback with a handle to that object.</p>
5933159331

5933259332
<p>The second argument, if provided, controls the type of the image to be returned (e.g. PNG or
59333-
JPEG). The default is <code data-x="">image/png</code>; that type is also used if the given type
59334-
isn't supported. The other arguments are specific to the type, and control the way that the
59335-
image is generated, as given <a href="#canvas-serialisation-arguments">in the table
59336-
below</a>.</p>
59333+
JPEG). The default is "<code>image/png</code>"; that type is also used if the given type isn't
59334+
supported. The third argument applies if the type is an image format that supports variable
59335+
quality (such as "<code>image/jpeg</code>"), and is a number in the range 0.0 to 1.0 inclusive
59336+
indicating the desired quality level for the resulting image.</p>
5933759337

5933859338
</dd>
5933959339

5934059340
</dl>
5934159341

5934259342
<div w-nodev>
5934359343

59344-
<p>The <dfn><code data-x="dom-canvas-toDataURL">toDataURL()</code></dfn> method must run the
59345-
following steps:</p>
59344+
<p>The <dfn><code data-x="dom-canvas-toDataURL">toDataURL(<var>type</var>,
59345+
<var>quality</var>)</code></dfn> method, when invoked, must run the following steps:</p>
5934659346

5934759347
<ol>
5934859348

5934959349
<!--ADD-TOPIC:Security-->
59350-
<li><p>If the <code>canvas</code> element's bitmap's <span
59350+
<li><p>If this <code>canvas</code> element's bitmap's <span
5935159351
data-x="concept-canvas-origin-clean">origin-clean</span> flag is set to false, throw a
5935259352
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> and abort these steps.</p>
5935359353
<!--REMOVE-TOPIC:Security-->
5935459354

59355-
<li><p>If the <code>canvas</code> element's bitmap has no pixels (i.e. either its horizontal
59355+
<li><p>If this <code>canvas</code> element's bitmap has no pixels (i.e. either its horizontal
5935659356
dimension or its vertical dimension is zero) then return the string "<code
5935759357
data-x="">data:,</code>" and abort these steps. (This is the shortest <span data-x="data
5935859358
protocol"><code>data:</code> URL</span>; it represents the empty string in a <code
5935959359
data-x="">text/plain</code> resource.)</p></li>
5936059360

5936159361
<li><p>Let <var>file</var> be <span data-x="a serialisation of the bitmap as a file">a
59362-
serialisation of the <code>canvas</code> element's bitmap as a file</span>, using the method's
59363-
arguments (if any) as the <var>arguments</var>.</p></li>
59362+
serialisation of this <code>canvas</code> element's bitmap as a file</span>, passing
59363+
<var>type</var> and <var>quality</var> if they were given.</p></li>
5936459364

5936559365
<li><p>Return a <span data-x="data protocol"><code>data:</code> URL</span> representing
5936659366
<var>file</var>. <ref spec=RFC2397></p>
@@ -59370,8 +59370,8 @@ callback <dfn>BlobCallback</dfn> = void (<span>Blob</span>? blob);</pre>
5937059370

5937159371
</ol>
5937259372

59373-
<p>The <dfn><code data-x="dom-canvas-toBlob">toBlob()</code></dfn> method must run the following
59374-
steps:</p>
59373+
<p>The <dfn><code data-x="dom-canvas-toBlob">toBlob(<var>callback</var>, <var>type</var>,
59374+
<var>quality</var>)</code></dfn> method, when invoked, must run the following steps:</p>
5937559375

5937659376
<ol>
5937759377

@@ -59381,27 +59381,22 @@ callback <dfn>BlobCallback</dfn> = void (<span>Blob</span>? blob);</pre>
5938159381
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> and abort these steps.</p>
5938259382
<!--REMOVE-TOPIC:Security-->
5938359383

59384-
<li><p>Let <var>callback</var> be the first argument.</p></li>
59385-
59386-
<li><p>Let <var>arguments</var> be the second and subsequent arguments to the method, if
59387-
any.</p></li>
59388-
5938959384
<li>
59390-
5939159385
<p>If the <code>canvas</code> element's bitmap has no pixels (i.e. either its horizontal
5939259386
dimension or its vertical dimension is zero) then let <var>result</var> be null.</p>
5939359387

5939459388
<p>Otherwise, let <var>result</var> be a <code>Blob</code> object representing <span data-x="a
5939559389
serialisation of the bitmap as a file">a serialisation of the <code>canvas</code> element's
59396-
bitmap as a file</span>, using <var>arguments</var>. <ref spec=FILEAPI> </p>
59397-
59390+
bitmap as a file</span>, passing <var>type</var> and <var>quality</var> if they were given. <ref
59391+
spec=FILEAPI></p>
5939859392
</li>
5939959393

5940059394
<li><p>Return, but continue running these steps <span>in parallel</span>.</p></li>
5940159395

59402-
<li><p><span>Queue a task</span> to invoke the <code>BlobCallback</code> <var>callback</var> with
59403-
<var>result</var> as its argument. The <span>task source</span> for this task is the <dfn>canvas
59404-
blob serialisation task source</dfn>.</p></li>
59396+
<li><p><span>Queue a task</span> to <span data-x="es-invoking-callback-functions">invoke</span>
59397+
the <code>BlobCallback</code> <var>callback</var> with <var>result</var> as its argument. The
59398+
<span>task source</span> for this task is the <dfn>canvas blob serialisation task
59399+
source</dfn>.</p></li>
5940559400

5940659401
</ol>
5940759402

@@ -65567,25 +65562,17 @@ dictionary <dfn>ImageBitmapRenderingContextSettings</dfn> {
6556765562

6556865563
<div w-nodev>
6556965564

65570-
<p>When a user agent is to create <dfn>a serialisation of the bitmap as a file</dfn>, optionally
65571-
with some given <var>arguments</var>, and optionally with a <var>native</var> flag set, it must
65572-
create an image file in the format given by the first value of <var>arguments</var>, or, if there
65573-
are no <var>arguments</var>, in the PNG format. <ref spec=PNG></p>
65565+
<p>When a user agent is to create <dfn>a serialisation of the bitmap as a file</dfn>, given an
65566+
optional <var>type</var> and <var>quality</var>, it must create an image file in the format given
65567+
by <var>type</var>, or if <var>type</var> was not supplied, in the PNG format. <ref spec=PNG></p>
6557465568

65575-
<p>If the <var>native</var> flag is set, or if the bitmap has one pixel per coordinate space unit,
65576-
then the image file must have the same pixel data (before compression, if applicable) as the
65577-
bitmap, and if the file format used supports encoding resolution metadata, the resolution of that
65578-
bitmap (device pixels per coordinate space units being interpreted as image pixels per <span
65579-
data-x="'px'">CSS pixel</span>) must be given as well.</p>
65569+
<p>The image file's pixel data must be the bitmap's pixel data scaled to one image pixel per
65570+
coordinate space unit, and if the file format used supports encoding resolution metadata, the
65571+
resolution must be given as 96dpi (one image pixel per <span data-x="'px'">CSS pixel</span>).</p>
6558065572

65581-
<p>Otherwise, the image file's pixel data must be the bitmap's pixel data scaled to one image
65582-
pixel per coordinate space unit, and if the file format used supports encoding resolution
65583-
metadata, the resolution must be given as 96dpi (one image pixel per <span data-x="'px'">CSS
65584-
pixel</span>).</p>
65585-
65586-
<p>If <var>arguments</var> is not empty, the first value must be interpreted as a <span
65587-
data-x="MIME type">MIME type</span> giving the format to use. If the type has any parameters, it
65588-
must be treated as not supported.</p>
65573+
<p>If <var>type</var> is supplied, it must be interpreted as a <span data-x="MIME type">MIME
65574+
type</span> giving the format to use. If the type has any parameters, it must be treated as not
65575+
supported.</p>
6558965576

6559065577
<p class="example">For example, the value "<code>image/png</code>" would mean to generate a PNG
6559165578
image, the value "<code>image/jpeg</code>" would mean to generate a JPEG image, and the value
@@ -65603,36 +65590,16 @@ dictionary <dfn>ImageBitmapRenderingContextSettings</dfn> {
6560365590
<p>For image types that do not support an alpha channel, the serialised image must be the bitmap
6560465591
image composited onto a solid black background using the source-over operator.</p>
6560565592

65606-
<p>If the first argument in <var>arguments</var> gives a type corresponding to one of the
65607-
types given in the first column of the following table, and the user agent supports that type,
65608-
then the subsequent arguments, if any, must be treated as described in the second cell of that
65609-
row.</p>
65610-
65611-
</div>
65612-
65613-
<table id="canvas-serialisation-arguments">
65614-
<caption>Arguments for serialisation methods</caption>
65615-
<thead>
65616-
<tr> <th> Type <th> Other arguments <th> Reference
65617-
<tbody>
65618-
<tr>
65619-
<td> <code>image/jpeg</code>
65620-
<td> The second argument<span w-nodev>, if it</span> is a number in the range 0.0 to 1.0
65621-
inclusive<span w-nodev>, must be</span> treated as the desired quality level. <span
65622-
w-nodev>If it is not a number or is outside that range, the user agent must use its
65623-
default value, as if the argument had been omitted.</span>
65624-
<td> <ref spec=JPEG>
65625-
</table>
65626-
65627-
<div w-nodev>
65628-
65629-
<p>For the purposes of these rules, an argument is considered to be a number if it is converted to
65630-
an IDL double value by the rules for handling arguments of type <code data-x="">any</code> in the
65631-
Web IDL specification. <ref spec=WEBIDL></p>
65593+
<p>If <var>type</var> is an image format that supports variable quality (such as
65594+
"<code>image/jpeg</code>") and <var>quality</var> is given, then, if <span
65595+
data-x="js-Type">Type</span>(<var>quality</var>) is Number, and <var>quality</var> is in the range
65596+
0.0 to 1.0 inclusive, the user agent must treat <var>quality</var> as the desired quality level.
65597+
If <span data-x="js-Type">Type</span>(<var>quality</var>) is not Number, or if <var>quality</var>
65598+
is outside that range, the user agent must use its default quality value, as if the
65599+
<var>quality</var> argument had not been given.</p>
6563265600

65633-
<p>Other arguments must be ignored and must not cause the user agent to throw an exception. A
65634-
future version of this specification will probably define other parameters to be passed to these
65635-
methods to allow authors to more carefully control compression settings, image metadata, etc.</p>
65601+
<p class="note">The use of type-testing here, instead of simply declaring <var>quality</var> as
65602+
a Web IDL <code data-x="">double</code>, is a historical artifact.</p>
6563665603

6563765604
</div>
6563865605

@@ -119910,6 +119877,7 @@ INSERT INTERFACES HERE
119910119877
Philippe De Ryck,
119911119878
Pooja Sanklecha,
119912119879
Prashant Hiremath,
119880+
Prashanth Chandra,
119913119881
Prateek Rungta,
119914119882
Pravir Gupta,
119915119883
Prayag Verma,

0 commit comments

Comments
 (0)