Editorial: clarify that putImageData does not perform memcpy

Make it clearer that putImage will convert from the source ImageData's color space and pixel format to the output bitmap's color space and pixel format.

Also document the two separate putImageData methods as separate methods with a common algorithm, rather than a single method with optional parameters.

Author: ccameron-chromium

source

@@ -65869,10 +65869,10 @@ interface mixin <dfn interface>CanvasDrawImage</dfn> {
 interface mixin <dfn interface>CanvasImageData</dfn> {
   // <span>pixel manipulation</span>
   <span>ImageData</span> <span data-x="dom-context-2d-createImageData">createImageData</span>([EnforceRange] long sw, [EnforceRange] long sh, optional <span>ImageDataSettings</span> settings = {});
-  <span>ImageData</span> <span data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<span>ImageData</span> imagedata);
+  <span>ImageData</span> <span data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<span>ImageData</span> imageData);
   <span>ImageData</span> <span data-x="dom-context-2d-getImageData">getImageData</span>([EnforceRange] long sx, [EnforceRange] long sy, [EnforceRange] long sw, [EnforceRange] long sh, optional <span>ImageDataSettings</span> settings = {});
-  undefined <span data-x="dom-context-2d-putImageData">putImageData</span>(<span>ImageData</span> imagedata, [EnforceRange] long dx, [EnforceRange] long dy);
-  undefined <span data-x="dom-context-2d-putImageData">putImageData</span>(<span>ImageData</span> imagedata, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
+  undefined <span data-x="dom-context-2d-putImageData-short">putImageData</span>(<span>ImageData</span> imageData, [EnforceRange] long dx, [EnforceRange] long dy);
+  undefined <span data-x="dom-context-2d-putImageData">putImageData</span>(<span>ImageData</span> imageData, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
 };
 
 enum <dfn enum>CanvasLineCap</dfn> { "butt", "round", "square" };
@@ -70253,7 +70253,7 @@ try {
   <h6><dfn>Pixel manipulation</dfn></h6>
 
   <dl class="domintro">
-   <dt><code data-x=""><var>imagedata</var> = new <span subdfn data-x="dom-imagedata">ImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
+   <dt><code data-x=""><var>imageData</var> = new <span subdfn data-x="dom-imagedata">ImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
    <dd>
     <p>Returns an <code>ImageData</code> object with the given dimensions and the color space
     indicated by <var>settings</var>. All the pixels in the returned object are <span>transparent
@@ -70263,7 +70263,7 @@ try {
     the width or height arguments are zero.</p>
    </dd>
 
-   <dt><code data-x=""><var>imagedata</var> = new <span subdfn data-x="dom-imagedata-with-data">ImageData</span>(<var>data</var>, <var>sw</var> [, <var>sh</var> [, <var>settings</var> ] ])</code></dt>
+   <dt><code data-x=""><var>imageData</var> = new <span subdfn data-x="dom-imagedata-with-data">ImageData</span>(<var>data</var>, <var>sw</var> [, <var>sh</var> [, <var>settings</var> ] ])</code></dt>
    <dd>
     <p>Returns an <code>ImageData</code> object using the data provided in the <code
     data-x="idl-Uint8ClampedArray">Uint8ClampedArray</code> argument, interpreted using the given
@@ -70277,11 +70277,11 @@ try {
     data and dimensions can't be interpreted consistently, or if either dimension is zero.</p>
    </dd>
 
-   <dt><code data-x=""><var>imagedata</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<var>imagedata</var>)</code></dt>
+   <dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData-imagedata">createImageData</span>(<var>imageData</var>)</code></dt>
    <dd><p>Returns an <code>ImageData</code> object with the same dimensions and color space as the
    argument. All the pixels in the returned object are <span>transparent black</span>.</p></dd>
 
-   <dt><code data-x=""><var>imagedata</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData">createImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
+   <dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-createImageData">createImageData</span>(<var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
    <dd>
     <p>Returns an <code>ImageData</code> object with the given dimensions. The color space of the
     returned object is the <span data-x="concept-canvas-color-space">color space</span> of
@@ -70292,7 +70292,7 @@ try {
     the width or height arguments are zero.</p>
    </dd>
 
-   <dt><code data-x=""><var>imagedata</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-getImageData">getImageData</span>(<var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
+   <dt><code data-x=""><var>imageData</var> = <var>context</var>.<span subdfn data-x="dom-context-2d-getImageData">getImageData</span>(<var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>settings</var>])</code></dt>
    <dd>
     <p>Returns an <code>ImageData</code> object containing the image data for the given rectangle of
     the bitmap. The color space of the returned object is the <span
@@ -70303,19 +70303,19 @@ try {
     of the width or height arguments are zero.</p>
    </dd>
 
-   <dt><code data-x=""><var>imagedata</var>.<span subdfn data-x="dom-imagedata-width">width</span></code></dt>
-   <dt><code data-x=""><var>imagedata</var>.<span subdfn data-x="dom-imagedata-height">height</span></code></dt>
+   <dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-width">width</span></code></dt>
+   <dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-height">height</span></code></dt>
    <dd><p>Returns the actual dimensions of the data in the <code>ImageData</code> object, in
    pixels.</p></dd>
 
-   <dt><code data-x=""><var>imagedata</var>.<span subdfn data-x="dom-imagedata-data">data</span></code></dt>
+   <dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-data">data</span></code></dt>
    <dd><p>Returns the one-dimensional array containing the data in RGBA order, as integers in the
    range 0 to 255.</p></dd>
 
-   <dt><code data-x=""><var>imagedata</var>.<span subdfn data-x="dom-imagedata-colorSpace">colorSpace</span></code></dt>
+   <dt><code data-x=""><var>imageData</var>.<span subdfn data-x="dom-imagedata-colorSpace">colorSpace</span></code></dt>
    <dd><p>Returns the color space of the pixels.</p></dd>
 
-   <dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-putImageData">putImageData</span>(<var>imagedata</var>, <var>dx</var>, <var>dy</var> [, <var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, <var>dirtyHeight</var> ])</code></dt>
+   <dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-putImageData">putImageData</span>(<var>imageData</var>, <var>dx</var>, <var>dy</var> [, <var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, <var>dirtyHeight</var> ])</code></dt>
    <dd>
     <p>Paints the data from the given <code>ImageData</code> object onto the bitmap. If a dirty
     rectangle is provided, only the pixels from that rectangle are painted.</p>
@@ -70327,7 +70327,7 @@ try {
     blending, no shadows, etc.</p>
 
     <p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
-    <var>imagedata</var> object's <code data-x="dom-imagedata-data">data</code> attribute value's
+    <var>imageData</var> object's <code data-x="dom-imagedata-data">data</code> attribute value's
     [[ViewedArrayBuffer]] internal slot is detached.</p>
    </dd>
   </dl>
@@ -70412,18 +70412,18 @@ try {
   </ol>
 
   <p>The <dfn method for="CanvasImageData"><code
-  data-x="dom-context-2d-createimagedata-imagedata">createImageData(<var>imagedata</var>)</code></dfn>
+  data-x="dom-context-2d-createimagedata-imagedata">createImageData(<var>imageData</var>)</code></dfn>
   method steps are:</p>
 
   <ol>
    <li><p>Let <var>newImageData</var> be a <span>new</span> <code>ImageData</code> object.</p></li>
 
    <li><p><span data-x="Initialize an ImageData object">Initialize</span> <var>newImageData</var>
-   given the value of <var>imagedata</var>'s <code data-x="dom-imagedata-width">width</code>
-   attribute, the value of <var>imagedata</var>'s <code data-x="dom-imagedata-height">height</code>
+   given the value of <var>imageData</var>'s <code data-x="dom-imagedata-width">width</code>
+   attribute, the value of <var>imageData</var>'s <code data-x="dom-imagedata-height">height</code>
    attribute, and <i><span
    data-x="initialize-imagedata-defaultcolorspace">defaultColorSpace</span></i> set to the value of
-   <var>imagedata</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code> attribute.</p></li>
+   <var>imageData</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code> attribute.</p></li>
 
    <li><p>Initialize the image data of <var>newImageData</var> to <span>transparent
    black</span>.</p></li>
@@ -70567,19 +70567,32 @@ try {
   component.</p>
 
   <p>The <dfn method for="CanvasImageData"><code
-  data-x="dom-context-2d-putImageData">putImageData()</code></dfn> method writes data from
-  <code>ImageData</code> structures back to the rendering context's <span>output bitmap</span>. Its
-  arguments are: <var>imagedata</var>, <var>dx</var>, <var>dy</var>, <var>dirtyX</var>,
-  <var>dirtyY</var>, <var>dirtyWidth</var>, and <var>dirtyHeight</var>.</p>
+  data-x="dom-context-2d-putImageData-short">putImageData(<var>imageData</var>,
+  <var>dx</var>, <var>dy</var>)</code></dfn> method steps are to
+  <span data-x="dom-context2d-putImageData-common">put pixels from an
+  <code>ImageData</code> onto a bitmap</span>, given
+  <var>imageData</var>, <span>this</span>'s <span>output bitmap</span>,
+  <var>dx</var>, <var>dy</var>, 0, 0,
+  <var>imageData</var>'s <code data-x="dom-imagedata-width">width</code>, and
+  <var>imageData</var>'s <code data-x="dom-imagedata-height">height</code>.</p>
 
-  <p>When the last four arguments to this method are omitted, they must be assumed to have the
-  values 0, 0, the <code data-x="dom-imagedata-width">width</code> member of the <var>imagedata</var> structure, and the <code data-x="dom-imagedata-height">height</code>
-  member of the <var>imagedata</var> structure, respectively.</p>
-
-  <p>The method, when invoked, must act as follows:</p>
-
-  <ol>
-   <li><p>Let <var>buffer</var> be <var>imagedata</var>'s <code
+  <p>The <dfn method for="CanvasImageData"><code
+  data-x="dom-context-2d-putImageData">putImageData(<var>imageData</var>,
+  <var>dx</var>, <var>dy</var>, <var>dirtyX</var>, <var>dirtyY</var>,
+  <var>dirtyWidth</var>, <var>dirtyHeight</var>)</code></dfn> method steps are to
+  <span data-x="dom-context2d-putImageData-common">put pixels from an
+  <code>ImageData</code> onto a bitmap</span>, given
+  <var>imageData</var>, <span>this</span>'s <span>output bitmap</span>,
+  <var>dx</var>, <var>dy</var>, <var>dirtyX</var>, <var>dirtyY</var>,
+  <var>dirtyWidth</var>, and <var>dirtyHeight</var>.</p>
+
+  <p>To <dfn data-x="dom-context2d-putImageData-common">put pixels from an <code>ImageData</code>
+  onto a bitmap</dfn>, given an <code>ImageData</code> <var>imageData</var>,
+  an <span>output bitmap</span> <var>bitmap</var>, and numbers <var>dx</var>, <var>dy</var>,
+  <var>dirtyX</var>, <var>dirtyY</var>, <var>dirtyWidth</var>, and <var>dirtyHeight</var>:</p>
+
+  <ol>
+   <li><p>Let <var>buffer</var> be <var>imageData</var>'s <code
    data-x="dom-imagedata-data">data</code> attribute value's [[ViewedArrayBuffer]] internal
    slot.</p></li>
 
@@ -70606,12 +70619,12 @@ try {
 
    <li>
     <p>If <var>dirtyX</var>+<var>dirtyWidth</var> is greater than the <code
-    data-x="dom-imagedata-width">width</code> attribute of the <var>imagedata</var> argument, then
+    data-x="dom-imagedata-width">width</code> attribute of the <var>imageData</var> argument, then
     let <var>dirtyWidth</var> be the value of that <code data-x="dom-imagedata-width">width</code>
     attribute, minus the value of <var>dirtyX</var>.</p>
 
     <p>If <var>dirtyY</var>+<var>dirtyHeight</var> is greater than the <code
-    data-x="dom-imagedata-height">height</code> attribute of the <var>imagedata</var> argument, then
+    data-x="dom-imagedata-height">height</code> attribute of the <var>imageData</var> argument, then
     let <var>dirtyHeight</var> be the value of that <code
     data-x="dom-imagedata-height">height</code> attribute, minus the value of <var>dirtyY</var>.</p>
    </li>
@@ -70625,12 +70638,14 @@ try {
    data-x=""><var>dirtyX</var>&nbsp;&le;&nbsp;<var>x</var>&nbsp;&lt;&nbsp;<span
    data-x=""><var>dirtyX</var>+<var>dirtyWidth</var></span></span> and <span
    data-x=""><var>dirtyY</var>&nbsp;&le;&nbsp;<var>y</var>&nbsp;&lt;&nbsp;<span
-   data-x=""><var>dirtyY</var>+<var>dirtyHeight</var></span></span>, copy the
-   four channels of the pixel with coordinate (<var>x</var>, <var>y</var>) in
-   the <var>imagedata</var> data structure's <span>Canvas Pixel
-   <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span> to the pixel with coordinate (<span
-   data-x=""><var>dx</var>+<var>x</var></span>, <var>dy</var>+<var>y</var>)
-   in the rendering context's <span>output bitmap</span>.</p></li>
+   data-x=""><var>dirtyY</var>+<var>dirtyHeight</var></span></span>,
+   set the pixel with coordinate (<span data-x=""><var>dx</var>+<var>x</var></span>,
+   <var>dy</var>+<var>y</var>) in <var>bitmap</var> to the color of the pixel at coordinate
+   (<var>x</var>, <var>y</var>) in the <var>imageData</var> data structure's
+   <span>Canvas Pixel <code data-x="idl-ArrayBuffer">ArrayBuffer</code></span>,
+   converted from <var>imageData</var>'s <code data-x="dom-imagedata-colorSpace">colorSpace</code>
+   to the <span data-x="concept-canvas-color-space">color space</span> of <var>bitmap</var>
+   using <span>'relative-colorimetric'</span> rendering intent.</p></li>
   </ol>
 
   <p class="note">Due to the lossy nature of converting between color spaces and converting to and