drawImage method
Draws a specified image onto a canvas.
![]() ![]() |
Syntax
object.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.
| Exception | Condition |
|---|---|
|
The image parameter is not an img object, canvas element, or video element. Versions earlier than Internet Explorer 10 use TYPE_MISMATCH_ERR. |
|
The image parameter does not contain image data. Versions earlier than Internet Explorer 10 use INVALID_STATE_ERR. |
|
The numeric arguments are not valid (for example, the destination is a 0x0 rectangle). Versions earlier than Internet Explorer 10 use INDEX_SIZE_ERR. |
|
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
- HTML Canvas 2D Context, Section 12
Remarks
The ICanvasRenderingContext2D::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.
See also

