putImageData method
Paints the data from a specified CanvasImageData object onto a canvas.
![]() ![]() |
Syntax
CanvasRenderingContext2D.putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);Parameters
- imagedata [in]
-
Type: ICanvasImageData
A CanvasImageData object with an image's pixel data.
- dx [in]
-
Type: number
The x-coordinate, in pixels, of the upper-left corner of the rectangle in relation to the coordinates of the canvas.
- dy [in]
-
Type: number
The y-coordinate, in pixels, of the upper-left corner of the rectangle in relation to the coordinates of the canvas.
- dirtyX [in, optional]
-
Type: number
The horizontal (x) value, in CSS pixels, where to place the image on the canvas.
- dirtyY [in, optional]
-
Type: number
The vertical (y) value, in CSS pixels, where to place the image on the canvas.
- dirtyWidth [in, optional]
-
Type: number
The destination width value, in CSS pixels, to use to draw the image to the canvas.
- dirtyHeight [in, optional]
-
Type: number
The destination height value, in CSS pixels to use to draw the image to the canvas.
Return value
This method does not return a value.
Exceptions
The following exceptions can be thrown:
| Exception | Condition |
|---|---|
|
One of the parameters is infinite or not a number (NaN). |
|
The first parameter is not an CanvasImageData object. |
|
The image is not of the same origin or domain as the destination. |
Standards information
- HTML Canvas 2D Context, Section 13
Remarks
You can specify an optional rectangle to show only those pixels. This "dirty" rectangle refers to a section of pixels to paint. You can use this option to specify areas on an image that might change without repainting the complete image.
Examples
The following code example creates a graphic, gets the image, and then uses putImageData to create a copy. See the example in action.
<!DOCTYPE html> <html> <head> <title>Get and Put image data sample</title> <style type="text/css"> #MyCanvas { border:1px solid red; } #YourCanvas { border:1px solid blue; } </style> </head> <body> Click the image to copy canvas to the other canvas <div> <canvas id="MyCanvas" width="400" height="400" >This browser or document mode doesn't support canvas</canvas> <canvas id="YourCanvas" width="400" height="400">This browser or document mode doesn't support canvas</canvas> </div> <script> // get first canvas and draw image var canvas = document.getElementById("MyCanvas"); if (canvas.getContext) { var ctx = canvas.getContext("2d"); ctx.beginPath(); ctx.rect(5, 5, 300, 250); ctx.stroke(); ctx.arc(150, 150, 100, 0, Math.PI, false); ctx.stroke(); } canvas.addEventListener("click", function (){ // get both canvases, and copy image var canvas2 = document.getElementById("YourCanvas"); if (canvas.getContext) { var ctx = canvas.getContext("2d"); // Get the context on the first canvas. var imageStuff = ctx.getImageData(0, 0, canvas.width, canvas.height); // Get image data from the first canvas. } if (canvas2.getContext) { var ctx2 = canvas2.getContext("2d"); // Get the context on the second canvas. ctx2.putImageData(imageStuff, 0, 0); // Put image data on the second canvas. } },false); </script> </body> </html>
See also

