Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[gow] (2) Revamp of ImageData and related APIs.
git-svn-id: http://svn.whatwg.org/webapps@1197 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
Hixie committed Feb 3, 2008
1 parent b382946 commit 96bc525
Show file tree
Hide file tree
Showing 2 changed files with 297 additions and 158 deletions.
221 changes: 141 additions & 80 deletions index
Expand Up @@ -16244,8 +16244,10 @@ The island of Shalott.&lt;/p></pre>
void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> 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
<a href="#imagedata">ImageData</a> <a href="#createimagedata" title=dom-context-2d-createImageData>createImageData</a>(in float sw, in float sh);
<a href="#imagedata">ImageData</a> <a href="#getimagedata" title=dom-context-2d-getImageData>getImageData</a>(in float sx, in float sy, in float sw, in float sh);
void <a href="#putimagedata" title=dom-context-2d-putImageData>putImageData</a>(in <a href="#imagedata">ImageData</a> imagedata, in float dx, in float dy);
void <a href="#putimagedata" title=dom-context-2d-putImageData>putImageData</a>(in <a href="#imagedata">ImageData</a> 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,
Expand Down Expand Up @@ -17505,25 +17507,44 @@ notes on what would need to be defined for dashed lines:

<h6 id=pixel><span class=secno>3.14.11.1.10. </span><dfn id=pixel0>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 id=createimagedata
title=dom-context-2d-createImageData><code>createImageData(<var
title="">sw</var>, <var title="">sh</var>)</code></dfn> method must return
an <code><a href="#imagedata">ImageData</a></code> object representing a
rectangle with a width in CSS pixels equal to the absolute magnitude of
<var title="">sw</var> and a height in CSS pixels equal to the absolute
magnitude of <var title="">sh</var>, filled with transparent black.

<p>The <dfn id=getimagedata
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><a
href="#imagedata">ImageData</a></code> object representing the underlying
pixel data for the area of the canvas denoted by the rectangle whose
pixel data 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>, <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.
<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>If any of the arguments to <code title=dom-context-2d-getImageData><a
href="#getimagedata">getImageData()</a></code> are infinite or NaN, the
method must instead raise an <code>INDEX_SIZE_ERR</code> exception.
<p>If any of the arguments to <code title=dom-context-2d-createImageData><a
href="#createimagedata">createImageData()</a></code> or <code
title=dom-context-2d-getImageData><a
href="#getimagedata">getImageData()</a></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><code><a href="#imagedata">ImageData</a></code> objects must be
initialised so that their <dfn id=width2
Expand All @@ -17547,7 +17568,7 @@ notes on what would need to be defined for dashed lines:
href="#imagedata">ImageData</a></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
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
Expand All @@ -17557,62 +17578,114 @@ notes on what would need to be defined for dashed lines:

<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 title="">sw</var> and
<var title="">sh</var> arguments are negative.

<p>If the <code title=dom-context-2d-getImageData><a
href="#getimagedata">getImageData()</a></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.
<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>The <dfn id=putimagedata
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><a
href="#imagedata">ImageData</a></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><a
href="#imagedata">ImageData</a></code> structure into one device pixel.

<p>If the first argument to the method is not an object whose [[Class]]
property is <code><a href="#imagedata">ImageData</a></code>, but all of
the following conditions are true, then the method must treat the first
argument as if it was an <code><a href="#imagedata">ImageData</a></code>
object (and thus not raise the <code>TYPE_MISMATCH_ERR</code> exception):
title="">imagedata</var>, <var title="">dx</var>, <var 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><a href="#imagedata">ImageData</a></code>
structures back to the canvas.

<p>If the first argment to the method is null or not an <code><a
href="#imagedata">ImageData</a></code> object that was returned by <code
title=dom-context-2d-createImageData><a
href="#createimagedata">createImageData()</a></code> or <code
title=dom-context-2d-getImageData><a
href="#getimagedata">getImageData()</a></code> then the <code
title=dom-context-2d-putImageData><a
href="#putimagedata">putImageData()</a></code> method must raise a
<code>TYPE_MISMATCH_ERR</code> exception.

<ul>
<li>The method's first argument is an object with <code
title=dom-imagedata-width><a href="#width2">width</a></code> and <code
title=dom-imagedata-height><a href="#height2">height</a></code>
attributes with integer values and a <code title=dom-imagedata-data><a
href="#data1">data</a></code> attribute whose value is an enumerable list
of values that are either JS Numbers or the JS value
<code>undefined</code>.

<li>The <code><a href="#imagedata">ImageData</a></code> object's <code
title=dom-imagedata-width><a href="#width2">width</a></code> is greater
than zero.

<li>The <code><a href="#imagedata">ImageData</a></code> object's <code
title=dom-imagedata-height><a href="#height2">height</a></code> is
greater than zero.

<li>The <code><a href="#imagedata">ImageData</a></code> object's <code
title=dom-imagedata-width><a href="#width2">width</a></code> multiplied
by its <code title=dom-imagedata-height><a
href="#height2">height</a></code> multiplied by 4 is equal to the number
of entries in the <code><a href="#imagedata">ImageData</a></code>
object's <code title=dom-imagedata-data><a href="#data1">data</a></code>
property.
</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>In the <code title=dom-imagedata-data><a href="#data1">data</a></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>When the last four arguments are omitted, they must be assumed to have
the values 0, 0, the <code title=dom-imagedata-width><a
href="#width2">width</a></code> member of the <var
title="">imagedata</var> structure, and the <code
title=dom-imagedata-height><a href="#height2">height</a></code>member of
the <var title="">imagedata</var> structure, respectively.

<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><a
href="#putimagedata">putImageData()</a></code> method must act as follows:

<ol>
<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>

<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>
<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>
<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>
<p>If <span><var title="">dirtyX</var>+<var
title="">dirtyWidth</var></span> is greater than the <code
title=dom-imagedata-width><a href="#width2">width</a></code> attribute
of the <var title="">imagedata</var> argument, let <var
title="">dirtyWidth</var> be the value of that <code
title=dom-imagedata-width><a href="#width2">width</a></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><a href="#height2">height</a></code>
attribute of the <var title="">imagedata</var> argument, let <var
title="">dirtyHeight</var> be the value of that <code
title=dom-imagedata-height><a href="#height2">height</a></code>
attribute, minus the value of <var title="">dirtyY</var>.</p>

<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>
<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.
</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
Expand Down Expand Up @@ -17659,28 +17732,16 @@ notes on what would need to be defined for dashed lines:

<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);
Expand Down Expand Up @@ -17718,13 +17779,18 @@ notes on what would need to be defined for dashed lines:
// 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) {
Expand All @@ -17738,11 +17804,6 @@ notes on what would need to be defined for dashed lines:
}

// put the image data back after manipulation
var output = {
width: w,
height: h,
data: outputData
};
context.putImageData(output, 0, 0);
}
&lt;/script>
Expand Down

0 comments on commit 96bc525

Please sign in to comment.