HTML Standard Tracker

Diff (omit for latest revision)
Filter

Short URL: http://html5.org/r/1197

File a bug

SVNBugCommentTime (UTC)
1197[Gecko] [Opera] [Webkit] Revamp of ImageData and related APIs.2008-02-03 09:43
Index: source
===================================================================
--- source	(revision 1196)
+++ source	(revision 1197)
@@ -13793,8 +13793,10 @@
   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,
@@ -15099,26 +15101,44 @@
 
   <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
@@ -15141,7 +15161,7 @@
   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
@@ -15152,64 +15172,134 @@
 
   <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>
+  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 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>
+  <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>
 
-  <ul>
+  <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>
 
-   <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 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 <code>ImageData</code> object's <code
-   title="dom-imagedata-width">width</code> is greater than
-   zero.</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-height">height</code> is greater than
-   zero.</li>
+  <ol>
 
-   <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>
+   <li>
 
-  </ul>
+    <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>
 
-  <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>
+    <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>
 
+   </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
@@ -15254,28 +15344,16 @@
 
    <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);
@@ -15314,13 +15392,18 @@
      // 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) {
@@ -15334,11 +15417,6 @@
      }
 
      // put the image data back after manipulation
-     var output = {
-       width: w,
-       height: h,
-       data: outputData
-     };
      context.putImageData(output, 0, 0);
    }
   &lt;/script>

|