Canvas drawImage: Projecting Pixels onto a Canvas

Why it exists

The Canvas API needs a way to render existing pixel data—from images, videos, or even other canvases—onto the drawing surface. Instead of multiple specialized methods, drawImage provides a single, powerful interface for positioning, scaling, and clipping any image source.

The mental model

Think of drawImage as a digital projector and the canvas as your screen. The 'image' argument is your slide. The simplest call projects the whole slide onto the screen. More complex calls let you resize the projection or even zoom in on a specific part of the slide before projecting it. This is perfect for sprite sheets, where one image contains many smaller graphics.

How it works

The drawImage method has three main forms, or overloads, for different levels of control. First, drawImage(image, dx, dy) simply draws the entire source 'image' at its original size onto the canvas at coordinates (dx, dy). Second, drawImage(image, dx, dy, dWidth, dHeight) draws the entire 'image' but scales it to fit the specified destination width and height. Third, drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) is the most powerful. It extracts a rectangular slice from the source image (defined by the 's' arguments) and draws that slice into a destination rectangle on the canvas (defined by the 'd' arguments), scaling it in the process.

When to use it

Use drawImage whenever you need to render an existing image-like object onto a canvas. It is essential for 2D game development for rendering characters and tiles from sprite sheets, for video effects by painting individual frames to a canvas, and for building image editors that composite multiple layers.

When not to use it

Do not use drawImage for creating primitive shapes like rectangles, lines, or circles from scratch. The canvas context has dedicated, more efficient methods for that, such as fillRect(), stroke(), and arc(). Use drawImage for rendering existing pixel data, not for generating new vector graphics.

One canonical example

A common use case is drawing a character sprite from a sprite sheet. Imagine a 128x32px sheet with four 32x32px animation frames in a row. To draw the second frame onto the canvas at position (50, 50), you would use the 9-argument version: ctx.drawImage(spriteSheet, 32, 0, 32, 32, 50, 50, 32, 32). Here, the source rectangle starts at x=32, y=0 with a size of 32x32, capturing just the second frame.