CanvasRenderingContext2D.drawImage()
The CanvasRenderingContext2D
.drawImage()
method of the Canvas 2D API provides different ways to draw an image onto the canvas.
Syntax
JavaScript
Copy Code
void <var>ctx.drawImage(image, dx, dy);</var> void <var>ctx.drawImage(image, dx, dy, dWidth, dHeight);</var> void <var>ctx.drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);</var>
Parameters
image
- An element to draw into the context. The specification permits any canvas image source (
CanvasImageSource
), such as anHTMLImageElement
, anHTMLVideoElement
, anHTMLCanvasElement
or anImageBitmap
. dx
- The X coordinate in the destination canvas at which to place the top-left corner of the source
image
. dy
- The Y coordinate in the destination canvas at which to place the top-left corner of the source
image
. dWidth
- The width to draw the
image
in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn. dHeight
- The height to draw the
image
in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn. sx
- The X coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
sy
- The Y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
sWidth
- The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by
sx
andsy
to the bottom-right corner of the image is used. sHeight
- The height of the sub-rectangle of the source image to draw into the destination context.
Exceptions thrown
INDEX_SIZE_ERR
- If the canvas or source rectangle width or height is zero.
INVALID_STATE_ERR
- The image has no image data.
TYPE_MISMATCH_ERR
- The specified source element isn't supported.
Examples
Using the drawImage
method
This is just a simple code snippet which uses the drawImage
method.
HTML
HTML
Copy Code
<canvas id="canvas"></canvas> <div style="display:none;"> <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227"> </div>
JavaScript
JavaScript
Copy Code
var canvas = document.getElementById("canvas"); var ctx = canvas.getContext("2d"); var image = document.getElementById("source"); ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);
Edit the code below and see your changes update live in the canvas:
Playable code
HTML
Copy Code
<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> <div style="display:none;"> <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227"> </div> <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.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);</textarea>
JavaScript
Copy Code
var canvas = document.getElementById("canvas"); var ctx = canvas.getContext("2d"); var image = document.getElementById('source'); 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);
Specifications
Specification | Status | Comment |
---|---|---|
WHATWG HTML Living Standard The definition of 'CanvasRenderingContext2D.drawImage' in that specification. |
Living Standard |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
ImageBitmap as source image |
? | 42 (42) | ? | ? | ? |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
ImageBitmap as source image |
? | ? | 42.0 (42) | ? | ? | ? |
Compatibility notes
- Support for flipping the image by using negative values for
sw
andsh
was added in Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2). - Starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2)
drawImage()
handles negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis. - Specifying a
null
orundefined
image when calling ordrawImage()
correctly throws aTYPE_MISMATCH_ERR
exception starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2). - Prior to Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4), Firefox threw an exception if any of the coordinate values was non-finite or zero. As per the specification, this no longer happens.
- Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) now correctly supports CORS for drawing images across domains without tainting the canvas.
- Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) now allows SVG-as-an-image to be drawn into a canvas without tainting the canvas.
Notes
- drawImage() only works correctly on an
HTMLVideoElement
when itsHTMLMediaElement.readyState
is greater than 1 (i.e, seek event fired after setting the currentTime property)
See also
- The interface defining it,
CanvasRenderingContext2D
.
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/drawimage