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.

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>