CanvasRenderingContext2D.putImageData()
The CanvasRenderingContext2D
.putImageData()
method of the Canvas 2D API paints data from the given ImageData
object onto the bitmap. If a dirty rectangle is provided, only the pixels from that rectangle are painted.
Syntax
void <var>ctx.putImageData(imagedata, dx, dy);</var> void <var>ctx.putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);</var>
Parameters
imageData
An ImageData
object containing the array of pixel values.
dx
- Horizontal position (x-coordinate) of the upper-left corner of the image data rectangle in the target canvas context.
dy
- Vertical position (y-coordinate) of the upper-left corner of the image data rectangle in the target canvas context.
dirtyX
Optional- Horizontal position (x-coordinate) where to place the image on the canvas. Defaults to the top left of the whole image data.
dirtyY
Optional- Vertical position (y-coordinate) where to place the image on the canvas. Defaults to the top left of the whole image data.
dirtyWidth
Optional- Width of the rectangle to be painted, in the origin image data. Defaults to the width of the image data.
dirtyHeight
Optional- Height of the rectangle to be painted, in the origin image data. Defaults to the height of the image data.
Errors thrown
NotSupportedError
- Thrown if either of the arguments are infinite.
InvalidStateError
- Thrown if the
ImageData
object's data has been detached.
Examples
Understanding putImageData
To understand what this algorithm performs, here is an implementation on top of CanvasRenderingContext2D.fillRect()
. For more information, see Pixel manipulation with canvas and the ImageData
object.
HTML
<canvas id="canvas"></canvas>
JavaScript
var canvas = document.getElementById("canvas"); var ctx = canvas.getContext("2d"); function putImageData(ctx, imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight) { var data = imageData.data; var height = imageData.height; var width = imageData.width; dirtyX = dirtyX || 0; dirtyY = dirtyY || 0; dirtyWidth = dirtyWidth !== undefined? dirtyWidth: width; dirtyHeight = dirtyHeight !== undefined? dirtyHeight: height; var limitBottom = dirtyY + dirtyHeight; var limitRight = dirtyX + dirtyWidth; for (var y = dirtyY; y < limitBottom; y++) { for (var x = dirtyX; x < limitRight; x++) { var pos = y * width + x; ctx.fillStyle = 'rgba(' + data[pos*4+0] + ',' + data[pos*4+1] + ',' + data[pos*4+2] + ',' + (data[pos*4+3]/255) + ')'; ctx.fillRect(x + dx, y + dy, 1, 1); } } } // Draw content onto the canvas ctx.fillRect(0,0,100,100); // Create an ImageData object from it var imagedata = ctx.getImageData(0,0,100,100); // use the putImageData function that illustrates how putImageData works putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);
Edit the code below and see your changes update live in the canvas:
Playable code
<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> <div class="playable-buttons"> <input id="edit" type="button" value="Edit" /> <input id="reset" type="button" value="Reset" /> </div> <textarea id="code" class="playable-code"> ctx.fillRect(0,0,100,100); var imagedata = ctx.getImageData(0,0,100,100); putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);</textarea>
var canvas = document.getElementById("canvas"); var ctx = canvas.getContext("2d"); var textarea = document.getElementById("code"); var reset = document.getElementById("reset"); var edit = document.getElementById("edit"); var code = textarea.value; function drawCanvas() { ctx.clearRect(0, 0, canvas.width, canvas.height); eval(textarea.value); } reset.addEventListener("click", function() { textarea.value = code; drawCanvas(); }); edit.addEventListener("click", function() { textarea.focus(); }) textarea.addEventListener("input", drawCanvas); window.addEventListener("load", drawCanvas); function putImageData(ctx, imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight) { var data = imageData.data; var height = imageData.height; var width = imageData.width; dirtyX = dirtyX || 0; dirtyY = dirtyY || 0; dirtyWidth = dirtyWidth !== undefined? dirtyWidth: width; dirtyHeight = dirtyHeight !== undefined? dirtyHeight: height; var limitBottom = dirtyY + dirtyHeight; var limitRight = dirtyX + dirtyWidth; for (var y = dirtyY; y < limitBottom; y++) { for (var x = dirtyX; x < limitRight; x++) { var pos = y * width + x; ctx.fillStyle = 'rgba(' + data[pos*4+0] + ',' + data[pos*4+1] + ',' + data[pos*4+2] + ',' + (data[pos*4+3]/255) + ')'; ctx.fillRect(x + dx, y + dy, 1, 1); } } }
Specifications
Specification | Status | Comment |
---|---|---|
WHATWG HTML Living Standard The definition of 'CanvasRenderingContext2D.putImageData' in that specification. |
Living Standard |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
Compatibility notes
- Starting in Gecko 10.0 (Firefox 10.0 / Thunderbird 10.0 / SeaMonkey 2.7), non-finite values to any of these parameters cause the call to
putImageData()
to be silently ignored, rather than throwing an exception. - To comply with the specification, starting with Gecko 16.0 (Firefox 16.0 / Thunderbird 16.0 / SeaMonkey 2.13), a call with an invalid number of arguments (only 3 or 7 arguments are valid), will now throw an error (bug 762657).
See also
- The interface defining it,
CanvasRenderingContext2D
. ImageData
- Pixel manipulation with canvas
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/canvasrenderingcontext2d/putimagedata