Export (0) Print
Expand All

drawImage method

Draws a specified image onto a canvas.

HTML Canvas 2D Context, Section 12Internet Explorer 9

Syntax

CanvasRenderingContext2D.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh);

Parameters

image [in]

Type: object

An img, canvas, or video element of the pattern to use.

sx [in, optional]

Type: number

The horizontal starting value (x), in CSS pixels, relative to the source image.

sy [in, optional]

Type: number

The vertical starting value (y), in CSS pixels, relative to the source image.

sw [in, optional]

Type: number

The width of the source image, in CSS pixels, to draw onto the canvas.

sh [in, optional]

Type: number

The height of the source image, in CSS pixels, to draw onto the canvas.

dx [in]

Type: number

The horizontal (x) value, in CSS pixels, where to place the image on the canvas.

dy [in]

Type: number

The vertical (y) value, in CSS pixels, where to place the image on the canvas.

dw [in, optional]

Type: number

The destination width value, in CSS pixels, to use when drawing the image to the canvas.

dh [in, optional]

Type: number

The destination height value, in CSS pixels, to use when drawing the image to the canvas.

Return value

This method does not return a value.

Exceptions

The following exceptions can be thrown.

ExceptionCondition
TypeMismatchError

The image parameter is not an img object, canvas element, or video element. Versions earlier than Internet Explorer 10 use TYPE_MISMATCH_ERR.

InvalidStateError

The image parameter does not contain image data. Versions earlier than Internet Explorer 10 use INVALID_STATE_ERR.

IndexSizeError

The numeric arguments are not valid (for example, the destination is a 0x0 rectangle). Versions earlier than Internet Explorer 10 use INDEX_SIZE_ERR.

SecurityError

The img or video element is not of the same origin or domain as the document that owns the canvas element. Versions earlier than Internet Explorer 10 use SECURITY_ERR.

Standards information

Remarks

The drawImage method provides three ways to draw an image onto a canvas, depending on how you use the optional parameters:

  • drawImage(image,dx,dy) copies an image exactly to the canvas at the location that the dx and dy parameters specify.
  • drawImage(image,dx,dy,dw,dh) copies an image to the canvas by using the dw and dh parameters to stretch or reduce the image. This option is similar to the size attributes on an img tag.
  • drawImage(image,sx,sy,sw,sh,dx,dy,dw,dh) copies all or part of a source image to the canvas. You can place and size the destination image by using the destination parameters.

If you do not specify the dw and dh parameters, they equal the values of sw and sh. One CSS pixel in the image is treated as one unit in the canvas coordinate space.

Note  If you're specifying an image, be sure the image content has loaded fully if you're calculating the width and height of the img tag.

Examples

The following code example draws an image on the canvas by using all three methods. See the example online.


<!DOCTYPE html>
<html>
<head>
<title>Drawimage example</title>

 
</head>
<body>
 <h1>DrawImage Example</h1>
  <h3>The image will be displayed full size, broken into four pieces, and twice the size.</h3>
 <div><canvas id="MyCanvas" width="600" height="500">This browser or document mode doesn't support canvas</canvas></div>
<img id="pix" src="http://go.microsoft.com/fwlink/?LinkID=199028" />
  <script>
    var canvas = document.getElementById("MyCanvas");
    if (canvas.getContext) {
      var image = document.getElementById("pix");
      //  Do this once image loads
      image.addEventListener("load", function () {
          var ctx = canvas.getContext("2d");                // Get the context.
          ctx.clearRect(0, 0, canvas.width, canvas.height);    // Clear the last image, if it exists.

          // Straight draw. 
          ctx.drawImage(image, 1, 1);
          ctx.fillStyle = "black";
          ctx.fillText("Original", 5, 115); // label the original
          // Stretch the image a bit.
          ctx.drawImage(image, 125, 125, 200, 200);
          // Draw it in pieces.
          ctx.drawImage(image, 1, 1, image.width / 2, image.height / 2, 50, 125, 50, 50);
          ctx.drawImage(image, 1, image.height / 2, image.width / 2, image.height / 2, 50, 275, 50, 50);
          ctx.drawImage(image, image.width / 2, 1, image.width / 2, image.height / 2, 350, 125, 50, 50);
          ctx.drawImage(image, image.width / 2, image.height / 2, image.width / 2, image.height / 2, 350, 275, 50, 50);
          image.style.display = "none"; // remove original image
      },false);
    }
  </script>
</body>
</html> 


See also

CanvasRenderingContext2D
See the example online

 

 

Show:
© 2014 Microsoft