Add willReadFrequently option for CanvasRenderingContext2D

Closes #5614.

source

@@ -60604,6 +60604,7 @@ dictionary <dfn dictionary>CanvasRenderingContext2DSettings</dfn> {
   boolean <span data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</span> = true;
   boolean <span data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</span> = false;
   <span>PredefinedColorSpace</span> <span data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</span> = "<span data-x="dom-PredefinedColorSpace-srgb">srgb</span>";
+  boolean <span data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</span> = false;
 };
 
 enum <dfn enum>ImageSmoothingQuality</dfn> { "<span data-x="dom-context-2d-imageSmoothingQuality-low">low</span>", "<span data-x="dom-context-2d-imageSmoothingQuality-medium">medium</span>", "<span data-x="dom-context-2d-imageSmoothingQuality-high">high</span>" };
@@ -60873,7 +60874,7 @@ interface <dfn interface>Path2D</dfn> {
   objects.</p>
 
   <dl class="domintro">
-   <dt><var>context</var> = <var>canvas</var> . <code data-x="dom-canvas-getContext">getContext</code>('2d' [, { [ <code data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</code>: true ] [, <code data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code>: false ] [, <code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code>: 'srgb'] } ] )</dt>
+   <dt><var>context</var> = <var>canvas</var> . <code data-x="dom-canvas-getContext">getContext</code>('2d' [, { [ <code data-x="dom-CanvasRenderingContext2DSettings-alpha">alpha</code>: true ] [, <code data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code>: false ] [, <code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code>: 'srgb'] [, <code data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>: false ]} ] )</dt>
    <dd>
     <p>Returns a <code>CanvasRenderingContext2D</code> object that is permanently bound to a
     particular <code>canvas</code> element.</p>
@@ -60889,6 +60890,11 @@ interface <dfn interface>Path2D</dfn> {
     <p>The <code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code> member
     specifies the <span data-x="concept-canvas-color-space">color space</span> of the rendering
     context.</p>
+
+    <p>If the <code
+    data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>
+    member is true, then the context is marked for <span
+    data-x="concept-canvas-will-read-frequently">readback optimization</span>.</p>
    </dd>
 
    <dt><var>context</var> . <code subdfn data-x="dom-context-2d-canvas">canvas</code></dt>
@@ -60911,6 +60917,11 @@ interface <dfn interface>Path2D</dfn> {
      <li><code data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code> member is
      a string indicating the context's <span data-x="concept-canvas-color-space">color
      space</span>.</li>
+
+     <li><code
+     data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>
+     member is true if the context is marked for <span
+     data-x="concept-canvas-will-read-frequently">readback optimization</span>.</li>
     </ul>
    </dd>
   </dl>
@@ -60967,6 +60978,23 @@ interface <dfn interface>Path2D</dfn> {
   can be useful when implementing certain kinds of applications, such as drawing applications,
   where the latency between input and rasterization is critical.</p>
 
+  <p>The <code>CanvasRenderingContext2D</code> object also has a <dfn
+  data-x="concept-canvas-will-read-frequently">will read frequently</dfn> boolean. When a
+  <code>CanvasRenderingContext2D</code> object's <span
+  data-x="concept-canvas-will-read-frequently">will read frequently</span> is true, the user agent
+  may optimize the canvas for readback operations.</p>
+
+  <p class="note">On most devices the user agent needs to decide whether to store the canvas's
+  <span>output bitmap</span> on the GPU (this is also called "hardware accelerated"), or on the CPU
+  (also called "software"). Most rendering operations are more performant for accelerated canvases,
+  with the major exception being readback with <code
+  data-x="dom-context-2d-getImageData">getImageData()</code>, <code
+  data-x="dom-canvas-toDataURL">toDataURL()</code>, or <code
+  data-x="dom-canvas-toBlob">toBlob()</code>. <code>CanvasRenderingContext2D</code> objects with
+  <span data-x="concept-canvas-will-read-frequently">will read frequently</span> equal to true tell
+  the user agent that the webpage is likely to perform many readback operations and that it is
+  advantageous to use a software canvas.</p>
+
   <p>The <code>CanvasRenderingContext2D</code> object also has a <dfn
   data-x="concept-canvas-color-space">color space</dfn> setting of type
   <code>PredefinedColorSpace</code>. The <code>CanvasRenderingContext2D</code> object's <span
@@ -60980,7 +61008,10 @@ interface <dfn interface>Path2D</dfn> {
   data-x="dom-CanvasRenderingContext2DSettings-desynchronized">desynchronized</code>" →
   <span>this</span>'s <span data-x="concept-canvas-desynchronized">desynchronized</span>, "<code
   data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code>" → <span>this</span>'s
-  <span data-x="concept-canvas-color-space">color space</span> ]».</p>
+  <span data-x="concept-canvas-color-space">color space</span>, "<code
+  data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code>" →
+  <span>this</span>'s <span data-x="concept-canvas-will-read-frequently">will read frequently</span>
+  ]».</p>
 
   <hr>
 
@@ -61049,6 +61080,11 @@ interface <dfn interface>Path2D</dfn> {
    <var>settings</var>["<dfn dict-member for="CanvasRenderingContext2DSettings"><code
    data-x="dom-CanvasRenderingContext2DSettings-colorSpace">colorSpace</code></dfn>"].</p></li>
 
+   <li><p>Set <var>context</var>'s <span
+   data-x="concept-canvas-will-read-frequently">will read frequently</span> to
+   <var>settings</var>["<dfn dict-member for="CanvasRenderingContext2DSettings"><code
+   data-x="dom-CanvasRenderingContext2DSettings-willReadFrequently">willReadFrequently</code></dfn>"].</p></li>
+
    <li><p>Return <var>context</var>.</p></li>
   </ol>