Permalink
Browse files

Add <img decoding>

The decoding attribute indicates a decoding hint to the user agent. This hint aids the user agent in deciding how to process and decode the image before rasterizing it. Possible values are as follows:

* "sync": prefer to decode the image synchronously for atomic presentation with other content
* "async": prefer to decode the image asynchronously to reduce delay in presenting other content
* "auto": default mode, which indicates no preference for the decoding mode.

Fixes #1920.
  • Loading branch information...
vmpstr authored and annevk committed Dec 5, 2017
1 parent 7567c80 commit 05525c88994bf7748eed4e175f2f51f6a01105bc
Showing with 95 additions and 9 deletions.
  1. +95 −9 source
View
104 source
@@ -25403,6 +25403,7 @@ interface <dfn>HTMLSourceElement</dfn> : <span>HTMLElement</span> {
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dd><code data-x="attr-img-referrerpolicy">referrerpolicy</code></dd>
<dd><code data-x="attr-img-decoding">decoding</code></dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre class="idl">[Exposed=Window,
@@ -25423,6 +25424,7 @@ interface <dfn>HTMLImageElement</dfn> : <span>HTMLElement</span> {
readonly attribute boolean <span data-x="dom-img-complete">complete</span>;
readonly attribute USVString <span data-x="dom-img-currentSrc">currentSrc</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-referrerPolicy">referrerPolicy</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-img-decoding">decoding</span>;
Promise&lt;void&gt; <span data-x="dom-img-decode">decode</span>();
};</pre>
@@ -25492,6 +25494,12 @@ interface <dfn>HTMLImageElement</dfn> : <span>HTMLElement</span> {
<span>referrer policy attribute</span>. Its purpose is to set the <span>referrer policy</span>
used when <span data-x="concept-fetch">fetching</span> the image. <ref spec=REFERRERPOLICY></p>
<p>The <dfn data-x="attr-img-decoding"><code>decoding</code></dfn> attribute indicates the
preferred method to <span data-x="img-decoding-process">decode</span> this image. The attribute,
if present, must be an <span>image decoding hint</span>. This attribute's <i data-x="missing value
default">missing value default</i> and <i data-x="invalid value default">invalid value
default</i> are both the <span data-x="attr-img-decoding-auto-state">auto</span> state.</p>
<hr>
<p>The <code>img</code> element must not be used as a layout tool. In particular, <code>img</code>
@@ -25676,6 +25684,10 @@ interface <dfn>HTMLImageElement</dfn> : <span>HTMLElement</span> {
<span>reflect</span> the <code data-x="attr-img-referrerpolicy">referrerpolicy</code>
content attribute, <span>limited to only known values</span>.</p>
<p>The <dfn><code data-x="dom-img-decoding">decoding</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-img-decoding">decoding</code> content
attribute, <span>limited to only known values</span>.
</div>
<dl class="domintro">
@@ -25723,17 +25735,20 @@ interface <dfn>HTMLImageElement</dfn> : <span>HTMLElement</span> {
</dd>
<dt><var>image</var> . <code subdfn data-x="dom-img-decode">decode</code>()</dt>
<dt><var>image</var> . <code subdfn data-x="dom-img-decoding">decoding</code></dt>
<dd>
<p>Images usually exist in some encoded form; user agents need to decode them into raw pixels
before displaying them. This process can be relatively expensive.</p>
<p>Returns the <span>image decoding hint</span> set for this image.</p>
</dd>
<dt><var>image</var> . <code subdfn data-x="dom-img-decode">decode</code>()</dt>
<p>This method causes the user agent to decode the image <span>in parallel</span>, returning a
promise that fulfills when decoding is complete. The decoded image data will then be readily
available for at least one frame after the fulfillment, ensuring that attempting to display the
image will complete without decoding delay.</p>
<dd>
<p>This method causes the user agent to <span data-x="img-decoding-process">decode</span> the
image <span>in parallel</span>, returning a promise that fulfills when decoding is complete.</p>
<p>The promise will be rejected with an <span>"<code>EncodingError</code>"</span>
<code>DOMException</code> if the image cannot be decoded.</p>
@@ -25869,8 +25884,7 @@ img.decode();</pre>
available</span></dt>
<dd>
<p>Decode the image's media data entirely into its bitmap form, suitable for rapid painting
to the screen.</p>
<p><span data-x="img-decoding-process">Decode</span> the image.</p>
<p>If decoding does not need to be performed for this image (for example because it is a
vector graphic), resolve <var>promise</var> with undefined.</p>
@@ -27021,6 +27035,70 @@ was an English &lt;a href="/wiki/Music_hall">music hall&lt;/a> singer, ...</pre>
images</span> but could keep the image data separately, and use that if the server responds with a
<code data-x="">304 Not Modified</code> status.</p>
<h6>Decoding images</h6>
<p>Image data is usually encoded in order to reduce file size. This means that in order for the
user agent to present the image to the screen, the data needs to be decoded.
<dfn data-x="img-decoding-process">Decoding</dfn> is the process which converts an image's media
data into a bitmap form, suitable for presentation to the screen. Note that this process can be
slow relative to other processes involved in presenting content. Thus, the user agent can choose
when to perform decoding, in order to create the best user experience.</p>
<p>Image decoding is said to be synchronous if it prevents presentation of other content until it
is finished. Typically, this has an effect of atomically presenting the image and any other
content at the same time. However, this presentation is delayed by the amount of time it takes to
perform the decode.</p>
<p>Image decoding is said to be asynchronous if it does not prevent presentation of other content.
This has an effect of presenting non-image content faster. However, the image content is missing
on screen until the decode finishes. Once the decode is finished, the screen is updated with the
image.</p>
<p>In both synchronous and asynchronous decoding modes, the final content is presented to screen
after the same amount of time has elapsed. The main difference is whether the user agent presents
non-image content ahead of presenting the final content.</p>
<p>In order to aid the user agent in deciding whether to perform synchronous or asynchronous
decode, the <code data-x="attr-img-decoding">decoding</code> attribute can be set on
<code>img</code> elements. The possible values of of the <code
data-x="attr-img-decoding">decoding</code> attribute are the following <dfn>image decoding
hint</dfn> keywords:</p>
<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Description
<tbody>
<tr>
<td><dfn><code data-x="attr-img-decoding-sync">sync</code></dfn>
<td><dfn data-x="attr-img-decoding-sync-state">Sync</dfn>
<td>Indicates a preference to <span data-x="img-decoding-process">decode</span> this image
synchronously for atomic presentation with other content.
<tr>
<td><dfn><code data-x="attr-img-decoding-async">async</code></dfn>
<td><dfn data-x="attr-img-decoding-async-state">Async</dfn>
<td>Indicates a preference to <span data-x="img-decoding-process">decode</span> this image
asynchronously to avoid delaying presentation of other content.
<tr>
<td><dfn><code data-x="attr-img-decoding-auto">auto</code></dfn>
<td><dfn data-x="attr-img-decoding-auto-state">Auto</dfn>
<td>Indicates no preference in decoding mode (the default).
</table>
<p>When <span data-x="img-decoding-process">decoding</span> an image, the user agent should
respect the preference indicated by the <code data-x="attr-img-decoding">decoding</code>
attribute's state. If the state indicated is <span
data-x="attr-img-decoding-auto-state">auto</span>, then the user agent is free to choose any
decoding behavior.</p>
<p class="note">It is also possible to control the decoding behavior using the <code
data-x="dom-img-decode">decode()</code> method. Since the <code
data-x="dom-img-decode">decode()</code> method performs <span
data-x="img-decoding-process">decoding</span> independently from the process responsible for
presenting content to screen, it is unaffected by the <code
data-x="attr-img-decoding">decoding</code> attribute.</p>
<h6>Updating the image data</h6>
@@ -115915,6 +115993,7 @@ interface <dfn>External</dfn> {
<code data-x="attr-img-ismap">ismap</code>;
<code data-x="attr-dim-width">width</code>;
<code data-x="attr-dim-height">height</code>;
<code data-x="attr-img-decoding">decoding</code>;
<code data-x="attr-img-referrerpolicy">referrerpolicy</code></td>
<td><code>HTMLImageElement</code></td>
</tr>
@@ -117469,6 +117548,13 @@ interface <dfn>External</dfn> {
<span>valid week string</span>,
<span>valid non-negative integer</span>, or
<span>valid duration string</span>
<tr>
<th> <code data-x="">decoding</code>
<td> <code data-x="attr-img-decoding">img</code>
<td> Decoding hint to use when processing this image for presentation
<td> "<code data-x="attr-img-decoding-sync">sync</code>";
"<code data-x="attr-img-decoding-async">async</code>";
"<code data-x="attr-img-decoding-auto">auto</code>"
<tr>
<th> <code data-x="">default</code>
<td> <code data-x="attr-track-default">track</code>

0 comments on commit 05525c8

Please sign in to comment.