HTML Standard Tracker

Filter

File a bug

SVNBugCommentTime (UTC)
1197[Gecko] [Opera] [Webkit] Revamp of ImageData and related APIs.2008-02-03 09:43
@@ -13786,22 +13786,24 @@ The island of Shalott.&lt;/p></pre>
 
   // drawing images
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLImageElement</span> image, in float dx, in float dy);
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLImageElement</span> image, in float dx, in float dy, in float dw, in float dh);
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLImageElement</span> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLCanvasElement</span> image, in float dx, in float dy);
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLCanvasElement</span> image, in float dx, in float dy, in float dw, in float dh);
   void <span title="dom-context-2d-drawImage">drawImage</span>(in <span>HTMLCanvasElement</span> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);
 
   // pixel manipulation
+  <span>ImageData</span> <span title="dom-context-2d-createImageData">createImageData</span>(in float sw, in float sh);
   <span>ImageData</span> <span title="dom-context-2d-getImageData">getImageData</span>(in float sx, in float sy, in float sw, in float sh);
   void <span title="dom-context-2d-putImageData">putImageData</span>(in <span>ImageData</span> imagedata, in float dx, in float dy);
+  void <span title="dom-context-2d-putImageData">putImageData</span>(in <span>ImageData</span> imagedata, in float dx, in float dy, in float dirtyX, in float dirtyY, in float dirtyWidth, in float dirtyHeight);
 
   // drawing text is not supported in this version of the API
   // (there is no way to predict what metrics the fonts will have,
   // which makes fonts very hard to use for painting)
 
 };
 
 interface <dfn>CanvasGradient</dfn> {
   // opaque object
   void <span title="dom-canvasgradient-addColorStop">addColorStop</span>(in float offset, in DOMString color);
@@ -15092,40 +15094,58 @@ notes on what would need to be defined for dashed lines:
   operators</span>.</p>
 
   <!-- XXX should somehow say that the image used is the actual image
   of the target element, not the rendered image (e.g. height/width
   attributes don't affect it -->
 
 
 
   <h6><dfn>Pixel manipulation</dfn></h6>
 
+<!--
+  <span>ImageData</span> <span title="dom-context-2d-createImageData">createImageData</span>(in float sw, in float sh);
+  <span>ImageData</span> <span title="dom-context-2d-getImageData">getImageData</span>(in float sx, in float sy, in float sw, in float sh);
+  void <span title="dom-context-2d-putImageData">putImageData</span>(in <span>ImageData</span> imagedata, in float dx, in float dy);
+  void <span title="dom-context-2d-putImageData">putImageData</span>(in <span>ImageData</span> imagedata, in float dx, in float dy, in float dirtyX, in float dirtyY, in float dirtyWidth, in float dirtyHeight);
+-->
+
+  <p>The <dfn
+  title="dom-context-2d-createImageData"><code>createImageData(<var
+  title="">sw</var>, <var title="">sh</var>)</code></dfn> method must
+  return an <code>ImageData</code> object representing a rectangle
+  with a width in CSS pixels equal to the absolute magnitude of <var
+  title="">sw</var></span> and a height in CSS pixels equal to the
+  absolute magnitude of <var title="">sh</var></span>, filled with
+  transparent black.</p>
+
   <p>The <dfn
   title="dom-context-2d-getImageData"><code>getImageData(<var
   title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>,
   <var title="">sh</var>)</code></dfn> method must return an
   <code>ImageData</code> object representing the underlying pixel data
-  for the area of the canvas denoted by the rectangle whose corners
-  are the four points (<var title="">sx</var>, <var
+  for the area of the canvas denoted by the rectanglewhose corners are
+  the four points (<var title="">sx</var>, <var title="">sy</var>),
+  (<span><var title="">sx</var>+<var title="">sw</var></span>, <var
   title="">sy</var>), (<span><var title="">sx</var>+<var
-  title="">sw</var></span>, <var title="">sy</var>), (<span><var
-  title="">sx</var>+<var title="">sw</var></span>, <span><var
-  title="">sy</var>+<var title="">sh</var></span>), (<var
-  title="">sx</var>, <span><var title="">sy</var>+<var
-  title="">sh</var></span>). Pixels outside the canvas must be
-  returned as transparent black. Pixels must be returned as
-  non-premultiplied alpha values.</p>
+  title="">sw</var></span>, <span><var title="">sy</var>+<var
+  title="">sh</var></span>), (<var title="">sx</var>, <span><var
+  title="">sy</var>+<var title="">sh</var></span>), in canvas
+  coordinate space units. Pixels outside the canvas must be returned
+  as transparent black. Pixels must be returned as non-premultiplied
+  alpha values.</p>
 
   <p>If any of the arguments to <code
-  title="dom-context-2d-getImageData">getImageData()</code> are
-  infinite or NaN, the method must instead raise an
-  <code>INDEX_SIZE_ERR</code> exception.</p>
+  title="dom-context-2d-createImageData">createImageData()</code> or
+  <code title="dom-context-2d-getImageData">getImageData()</code> are
+  infinite or NaN, or if either the <var title="">sw</var> or <var
+  title="">sh</var> arguments are zero, the method must instead raise
+  an <code>INDEX_SIZE_ERR</code> exception.</p>
 
   <p><code>ImageData</code> objects must be initialised so that their
   <dfn title="dom-imagedata-width"><code>width</code></dfn> attribute
   is set to <var title="">w</var>, the number of physical device
   pixels per row in the image data, their <dfn
   title="dom-imagedata-height"><code>height</code></dfn> attribute is
   set to <var title="">h</var>, the number of rows in the image data,
   and the <dfn title="dom-imagedata-data"><code>data</code></dfn>
   attribute is initialised to an array of <var
   title="">h</var>&times;<var title="">w</var>&times;4 integers. The
@@ -15134,88 +15154,158 @@ notes on what would need to be defined for dashed lines:
   blue, and alpha components being given in that order. Each component
   of each device pixel represented in this array must be in the range
   0..255, representing the 8 bit value for that component. At least
   one pixel must be returned.</p>
 
   <p>The values of the <code title="dom-imagedata-data">data</code>
   array may be changed (the length of the array, and the other
   attributes in <code>ImageData</code> objects, are all read-only). On
   setting, JS <code>undefined</code> values must be converted to zero.
   Other values must first be converted to numbers using JavaScript's
-  ToNumber algorithm, and if the result is not a number, a
+  ToNumber algorithm, and if the result is a NaN value, a
   <code>TYPE_MISMATCH_ERR</code> exception must be raised. If the
   result is less than 0, it must be clamped to zero. If the result is
   more than 255, it must be clamped to 255. If the number is not an
   integer, it must be rounded to the nearest integer using the IEEE
   754r <i>roundTiesToEven</i> rounding mode.  <a
   href="#refsECMA262">[ECMA262]</a> <a
   href="#refsIEEE754r">[IEEE754R]</a></p>
 
   <p class="note">The width and height (<var title="">w</var> and <var
   title="">h</var>) might be different from the <var title="">sw</var>
-  and <var title="">sh</var> arguments to the function, e.g. if the
-  canvas is backed by a high-resolution bitmap, or if the <var
+  and <var title="">sh</var> arguments to the above methods, e.g. if
+  the canvas is backed by a high-resolution bitmap, or if the <var
   title="">sw</var> and <var title="">sh</var> arguments are
   negative.</p>
 
-  <p>If the <code
-  title="dom-context-2d-getImageData">getImageData()</code> method is
-  called with either the <var title="">sw</var> or <var
-  title="">sh</var> arguments set to zero, the method must raise an
-  <code>INDEX_SIZE_ERR</code> exception.</p>
-
   <p>The <dfn
   title="dom-context-2d-putImageData"><code>putImageData(<var
   title="">imagedata</var>, <var title="">dx</var>, <var
-  title="">dy</var>)</code></dfn> method must take the given
-  <code>ImageData</code> structure, and place it at the specified
-  location (<var title="">dx</var>, <var title="">dy</var>) in the
-  canvas coordinate space, mapping each pixel represented by the
-  <code>ImageData</code> structure into one device pixel.</p>
-
-  <p>If the first argument to the method is not an object whose
-  [[Class]] property is <code>ImageData</code>, but all of the
-  following conditions are true, then the method must treat the first
-  argument as if it was an <code>ImageData</code> object (and thus not
-  raise the <code>TYPE_MISMATCH_ERR</code> exception):</p>
+  title="">dy</var>, <var title="">dirtyX</var>, <var
+  title="">dirtyY</var>, <var title="">dirtyWidth</var>, <var
+  title="">dirtyHeight</var>)</code></dfn> method writes data from
+  <code>ImageData</code> structures back to the canvas.</p>
+
+  <p>If the first argment to the method is null or not an
+  <code>ImageData</code> object that was returned by <code
+  title="dom-context-2d-createImageData">createImageData()</code> or
+  <code title="dom-context-2d-getImageData">getImageData()</code> then
+  the <code title="dom-context-2d-putImageData">putImageData()</code>
+  method must raise a <code>TYPE_MISMATCH_ERR</code> exception.</p>
+
+  <p>If any of the arguments to the method are infinite or NaN, the
+  method must raise an <code>INDEX_SIZE_ERR</code> exception.</p>
 
-  <ul>
+  <p>When the last four arguments are omitted, they must be assumed to
+  have the values 0, 0, the <code
+  title="dom-imagedata-width">width</code> member of the <var
+  title="">imagedata</var> structure, and the <code
+  title="dom-imagedata-height">height</code>member of the <var
+  title="">imagedata</var> structure, respectively.</p>
 
-   <li>The method's first argument is an object with <code
-   title="dom-imagedata-width">width</code> and <code
-   title="dom-imagedata-height">height</code> attributes with integer
-   values and a <code title="dom-imagedata-data">data</code> attribute
-   whose value is an enumerable list of values that are either JS
-   Numbers or the JS value <code>undefined</code>.</li>
+  <p>When invoked with arguments that do not, per the last few
+  paragraphs, cause an exception to be raised, the <code
+  title="dom-context-2d-putImageData">putImageData()</code> method
+  must act as follows:</p>
 
-   <li>The <code>ImageData</code> object's <code
-   title="dom-imagedata-width">width</code> is greater than
-   zero.</li>
+  <ol>
 
-   <li>The <code>ImageData</code> object's <code
-   title="dom-imagedata-height">height</code> is greater than
-   zero.</li>
+   <li>
 
-   <li>The <code>ImageData</code> object's <code
-   title="dom-imagedata-width">width</code> multiplied by its <code
-   title="dom-imagedata-height">height</code> multiplied by 4 is equal
-   to the number of entries in the <code>ImageData</code> object's
-   <code title="dom-imagedata-data">data</code> property.</li>
+    <p>Let <var title="">dx<sub>device</sub></var> be the x-coordinate
+    of the device pixel in the underlying pixel data of the canvas
+    corresponding to the <var title="">dx</var> coordinate in the
+    canvas coordinate space.</p>
 
-  </ul>
+    <p>Let <var title="">dy<sub>device</sub></var> be the y-coordinate
+    of the device pixel in the underlying pixel data of the canvas
+    corresponding to the <var title="">dy</var> coordinate in the
+    canvas coordinate space.</p>
 
-  <p>In the <code title="dom-imagedata-data">data</code> property,
-  undefined values must be treated as zero, any numbers below zero
-  must be clamped to zero, any numbers above 255 must be clamped to
-  255, and any numbers that are not integers must be rounded to the
-  nearest integer using the IEEE 754r <i>roundTiesToEven</i> rounding
-  mode. <a href="#refsIEEE754r">[IEEE754R]</a></p>
+   </li>
+
+   <li>
+
+    <p>If <var title="">dirtyWidth</var> is negative, let <var
+    title="">dirtyX</var> be <span><var title="">dirtyX</var>+<var
+    title="">dirtyWidth</var></span>, and let <var
+    title="">dirtyWidth</var> be equal to the absolute magnitude of
+    <var title="">dirtyWidth</var>.</p>
+
+    <p>If <var title="">dirtyHeight</var> is negative, let <var
+    title="">dirtyY</var> be <span><var title="">dirtyY</var>+<var
+    title="">dirtyHeight</var></span>, and let <var
+    title="">dirtyHeight</var> be equal to the absolute magnitude of
+    <var title="">dirtyHeight</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p>If <var title="">dirtyX</var> is negative, let <var
+    title="">dirtyWidth</var> be <span><var
+    title="">dirtyWidth</var>+<var title="">dirtyX</var></span>, and
+    let <var title="">dirtyX</var> be zero.</p>
+
+    <p>If <var title="">dirtyY</var> is negative, let <var
+    title="">dirtyHeight</var> be <span><var
+    title="">dirtyHeight</var>+<var title="">dirtyY</var></span>, and
+    let <var title="">dirtyY</var> be zero.</p>
+
+   </li>
+
+   <li>
+
+    <p>If <span><var title="">dirtyX</var>+<var
+    title="">dirtyWidth</var></span> is greater than the <code
+    title="dom-imagedata-width">width</code> attribute of the <var
+    title="">imagedata</var> argument, let <var
+    title="">dirtyWidth</var> be the value of that <code
+    title="dom-imagedata-width">width</code> attribute, minus the
+    value of <var title="">dirtyX</var>.</p>
+
+    <p>If <span><var title="">dirtyY</var>+<var
+    title="">dirtyHeight</var></span> is greater than the <code
+    title="dom-imagedata-height">height</code> attribute of the <var
+    title="">imagedata</var> argument, let <var
+    title="">dirtyHeight</var> be the value of that <code
+    title="dom-imagedata-height">height</code> attribute, minus the
+    value of <var title="">dirtyY</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p>If, after those changes, either <var title="">dirtyWidth</var>
+    or <var title="">dirtyHeight</var> is negative or zero, stop these
+    steps without affecting the canvas.</p>
+
+   </li>
+
+   <li><p>Otherwise, for all values of <var title="">x</var> and <var
+   title="">y</var> where <span><var
+   title="">dirtyX</var>&nbsp;&le;&nbsp;<var
+   title="">x</var>&nbsp;&lt;&nbsp;<span><var
+   title="">dirtyX</var>+<var title="">dirtyWidth</var></span></span>
+   and <span><var title="">dirtyY</var>&nbsp;&le;&nbsp;<var
+   title="">y</var>&nbsp;&lt;&nbsp;<span><var
+   title="">dirtyY</var>+<var
+   title="">dirtyHeight</var></span></span>, copy the four channels of
+   thr pixel with coordinate (<var title="">x</var>, <var
+   title="">y</var>) in the <var title="">imagedata</var> data
+   structure to the pixel with coordinate (<span><var
+   title="">x<sub>device</sub></var>+<var title="">x</var></span>,
+   <span><var title="">y<sub>device</sub></var>+<var
+   title="">y</var></span>) in the underlying pixel data of the
+   canvas.</p></li>
+
+  </ol>
 
   <p>The handling of pixel rounding when the specified coordinates do
   not exactly map to the device coordinate space is not defined by
   this specification, except that the following must result in no
   visible changes to the rendering:</p>
 
   <pre>context.putImageData(context.getImageData(x, y, w, h), x, y);</pre>
 
   <p>...for any value of <var title="">x</var> and <var
   title="">y</var>. In other words, while user agents may round the
@@ -15247,42 +15337,30 @@ notes on what would need to be defined for dashed lines:
    <code>ImageData</code> object, one would not necessarily know what
    resolution the canvas expected (how many pixels the canvas wants to
    paint over one coordinate space unit pixel).</p>
 
    <p>In the following example, the script first obtains the size of
    the canvas backing store, and then generates a few new
    <code>ImageData</code> objects which can be used.</p>
 
    <pre>
   // canvas is a reference to a &lt;canvas> element
-  // (note: this example uses JavaScript 1.7 features)
   var context = canvas.getContext('2d');
-  var backingStore = context.getImageData(0, 0, canvas.width, canvas.height);
-  var actualWidth = backingStore.width;
-  var actualHeight = backingStore.height;
-
-  function CreateImageData(w, h) {
-    return {
-      height: h,
-      width: w,
-      data: [i for (i in function (n) { for (let i = 0; i &lt; n; i += 1) yield 0 }(w*h*4)) ]
-    };
-  }
 
   // create a blank slate
-  var data = CreateImageData(actualWidth, actualHeight);
+  var data = context.createImageData(canvas.width, canvas.height);
 
   // create some plasma
   FillPlasma(data, 'green'); // green plasma
 
   // add a cloud to the plasma
-  AddCloud(data, actualWidth/2, actualHeight/2); // put a cloud in the middle
+  AddCloud(data, data.width/2, data.height/2); // put a cloud in the middle
 
   // paint the plasma+cloud on the canvas
   context.putImageData(data, 0, 0);
 
   // support methods
   function FillPlasma(data, color) { ... }
   function AddCloud(data, x, y) { ... }
 </pre>
 
   </div>
@@ -15307,45 +15385,45 @@ notes on what would need to be defined for dashed lines:
    function demo() {
      var canvas = document.getElementsByTagName('canvas')[0];
      var context = canvas.getContext('2d');
 
      // draw the image onto the canvas
      context.drawImage(image, 0, 0);
 
      // get the image data to manipulate
      var input = context.getImageData(0, 0, canvas.width, canvas.height);
 
-     // edge detection
+     // get an empty slate to put the data into
+     var output = context.crateImageData(canvas.width, canvas.height);
+
+     // alias some variables for convenience
      // notice that we are using input.width and input.height here
      // as they might not be the same as canvas.width and canvas.height
      // (in particular, they might be different on high-res displays)
      var w = input.width, h = input.height;
      var inputData = input.data;
-     var outputData = new Array(w*h*4);
+     var outputData = output.data;
+
+     // edge detection
      for (var y = 1; y &lt; h-1; y += 1) {
        for (var x = 1; x &lt; w-1; x += 1) {
          for (var c = 0; c &lt; 3; c += 1) {
            var i = (y*w + x)*4 + c;
            outputData[i] = 127 + -inputData[i - w*4 - 4] -   inputData[i - w*4] - inputData[i - w*4 + 4] +
                                  -inputData[i - 4]       + 8*inputData[i]       - inputData[i + 4] +
                                  -inputData[i + w*4 - 4] -   inputData[i + w*4] - inputData[i + w*4 + 4];
          }
          outputData[(y*w + x)*4 + 3] = 255; // alpha
        }
      }
 
      // put the image data back after manipulation
-     var output = {
-       width: w,
-       height: h,
-       data: outputData
-     };
      context.putImageData(output, 0, 0);
    }
   &lt;/script>
  &lt;/head>
  &lt;body onload="init()">
   &lt;canvas>&lt;/canvas>
  &lt;/body>
 &lt;/html></pre>
 
   </div>

|