Skip to main content
putImageData method

Paints the data from a specified CanvasImageData object onto a canvas.

HTML Canvas 2D Context, Section 13 Internet Explorer 9

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:

ExceptionCondition
NotSupportedError

One of the parameters is infinite or not a number (NaN).

TypeMismatchError

The first parameter is not an CanvasImageData object.

SecurityError

The image is not of the same origin or domain as the destination.

Standards information

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

CanvasRenderingContext2D
getImageData
CanvasImageData