Exploring the many method parameters of drawImage with HTML5 Canvas

In this post I look at the different method parameters that can be used with drawImage and what they are useful for.

Whats the use for different parameters of drawImage

The context drawImage function allows for creating more complex canvas scenes by allowing you to draw different images at various positions or sizes.

These can either be drawing images from another canvas, loaded image files, or one of the various other supported elements. The basic drawImage function call allows adding the drawn image to the canvas at a specific location. the other more advanced forms allow setting the width and only selecting a part of the source image.

Simple Drawing – drawImage(image, x, y)

The simplest way of drawing an image is using three parameters.

drawImage(image, x, y)

• image – allows setting of the image/canvas that you want to draw from. This will be the image that will be drawn by your context.
• x – is the x position that that context will start drawing from
• y – is the y position that that context will start drawing from

This allows drawing a specific image with the context at a specific point. When using this method the full image will be drawn by the context. The image width and height will be preserved.

Drawing specifying width and height – drawImage(image, x, y, width, height)

By adding two more parameters to drawImage you can specify the width and height of the image drawn onto the canvas.

drawImage(image, x, y, width, height)

• image – allows setting of the image/canvas that you want to draw from. This will be the image that will be drawn by your context.
• x – is the x position that that context will start drawing from
• y – is the y position that that context will start drawing from
• width – allows customization of the width of the image drawn by the context. Setting anything but the origins default width will involve scaling the image to fit the new width.
• height – allows customization of the height of the image drawn by the context. Setting anything but the origins default height will involve scaling the image to fit the new height.

Using width and height allows custom scaling of the image before it is drawn to the canvas. Setting the width and height to the width and height of the passed in image will have this function work as if you have called it without the width and height parameters.

Using this with the width and height will allow you to scale your assets as required.

Drawing specifying all dimensions – drawImage(image, sourceX, sourceY, sourceWidth, sourceHeight, x, y, width, height)

The third and most expressive set of parameters allows customizing the section of the image you sample from your source.

drawImage(image, sourceX, sourceY, sourceWidth, sourceHeight, x, y, width, height)

• image – allows setting of the image/canvas that you want to draw from. This will be the image that will be drawn by your context.
• sourceX – The x position of the source element to start sampling from
• sourceY – The y position of the source element to start sampling from
• sourceWidth – The width from the x position to sample from
• sourceHeight – The height from the y position to sample from
• x – is the x position that that context will start drawing from
• y – is the y position that that context will start drawing from
• width – allows customization of the width of the image drawn by the context. Setting anything but the origins default width will involve scaling the image to fit the new width.
• height – allows customization of the height of the image drawn by the context. Setting anything but the origins default height will involve scaling the image to fit the new height.

Here we are able to define precisely what part of the source image we want to draw to the canvas. Again if you set the source x and y to be 0, and the source height and width to be the height and width of the source image,  it will operate the same as the above parameter set.

One use of this extended set of parameters is to easily allow for sprite sheets. These are image files storing multiple images designed to be cut apart in your program. Here you will always want to select a specific part of the source canvas.

Summary

We have three different ways that we can draw images to the canvas using the drawImage function. Depending on your use case all three may be used in different parts of your program. Each giving another level of expressiveness when layering the images onto a canvas.

Even with the most expressive parameter set we can set the parameters to draw as if it were the most basic. In the background when this function is called with less parameters the others are calculated and filled in.