Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add <img> decoding="" attribute #3221

Merged
merged 4 commits into from
Dec 5, 2017
Merged

Add <img> decoding="" attribute #3221

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
da51fd2
add decodingmode img attr
vmpstr Nov 10, 2017
d66f6ce
Added image decoding section.
vmpstr Nov 13, 2017
a7dc0f8
Minor tweaks
domenic Nov 16, 2017
3f6a0fe
Update element index with new attribute
domenic Nov 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 95 additions & 9 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25414,6 +25414,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,
Expand All @@ -25434,6 +25435,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>
Expand Down Expand Up @@ -25503,6 +25505,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>
Expand Down Expand Up @@ -25687,6 +25695,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">
Expand Down Expand Up @@ -25734,17 +25746,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>
Expand Down Expand Up @@ -25877,8 +25892,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>
Expand Down Expand Up @@ -27026,6 +27040,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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we spell these out as "Synchronous" and "Asynchronous"? We typically don't abbreviate states I think.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the whole states vs. keywords distinction already a bit hard to deal with, so I try for new stuff to keep them as close as possible. But I don't have a principled suggestion going forward, so happy to change it if you prefer.

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

Expand Down Expand Up @@ -115885,6 +115963,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>;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this should come after referrerpolicy if we want to retain the order we started in the img element section.

<code data-x="attr-img-referrerpolicy">referrerpolicy</code></td>
<td><code>HTMLImageElement</code></td>
</tr>
Expand Down Expand Up @@ -117442,6 +117521,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>
Expand Down