Chapter 2: Intro to CanvasRenderingContext2D

Canvas setup

Chapter 1 left off with starter code and a simple fillRect draw call. Remove the blue rectangle and what is left is the necessary code that must precede all of the other examples in this chapter.

Hello, world!

To begin, draw text with fillText.

Notice that fillText takes only a string and position as arguments, yet the text renders with a font and color. Those come from state that is set on ctx at the moment it runs--here, "32px sans-serif" and "deepskyblue".

Context2D relies on shared mutable state

Yes, shared mutable state 😱

Any property you set on the context (fillStyle, lineWidth, font, for example) stays set until something changes it. Here, fillRect inherits the same fillStyle that colored the text blue.

The coordinate system

The two numbers after "Hello, world!" are the x and y coordinates, measured in pixels from the left edge and pixels from the top. y increases downward, unlike the coordinates you learned in school.

The z axis

Paint operations run in order, so whatever was drawn last sits on top.

High-DPI displays

If you're following along and your canvas looks blurry, your screen can handle more pixels than the canvas has at its default pixel density. A display with a devicePixelRatio of 2 has four physical pixels for every CSS pixel. But by default the canvas doesn't automatically scale itself for high-density displays, resulting in a stretched, blurry image instead.

The fix is the following standard boilerplate, which we'll cover in depth at the end of the chapter.

fillRect

As you saw above, use it to draw rectangles.

strokeRect

Draw borders around rectangles. The stroke is centered along the edge of the rectangle, so adjust sizing according to lineWidth as needed.

Dashed lines

Use ctx.setLineDash([length, gap]). Change the dash phase offset like ctx.lineDashOffset = 4 or animate it for a marching ants effect. To reset, pass an empty array: ctx.setLineDash([]). More examples on MDN.

Circles

A circle is just an arc that extends 2π radians. So if you arc from 0 to Math.PI * 2 with some radius, you'll get a circle.

ctx.arc(x, y, radius, startAngle, endAngle)

function circle(ctx, x, y, radius) {
  ctx.beginPath();
  ctx.arc(x, y, radius, 0, Math.PI * 2);
  ctx.fill();
}

Paths

The circle example above introduced a new concept: paths!

You can draw your own shapes with the following methods:

ctx.beginPath(); // start drawing a path
ctx.moveTo(x, y); // jumps to a new position
ctx.lineTo(x, y); // draw a line to a coordinate
ctx.closePath(); // line straight back to path origin
ctx.stroke(); // outline the path
ctx.fill(); // fill the path
// shapes
ctx.rect(x, y, w, h); // add rectangle to path
ctx.roundRect(x, y, w, h, radii); // rounded rectangle
ctx.ellipse(x, y, rx, ry, rotation, startAngle, endAngle);
// curved lines
ctx.arc(x, y, radius, startAngle, endAngle);
ctx.arcTo(x1, y1, x2, y2, radius);
ctx.quadraticCurveTo(controlX, controlY, x, y);
ctx.bezierCurveTo(x1, y1, x2, y2, x, y);

Line joins for rounded corners

By default corners are sharp (lineJoin="miter") but you can round them with lineJoin="round" or bevel them with lineJoin="bevel".

Line caps

Line caps are used for the ends of a line that are visible when you don't close a path.

Arcs

Can be useful for progress indicators.

ctx.arc(x, y, radius, startAngle, endAngle)

Text rendering deep dive

Let's return to our hello world example.

Stroke text

Like many of the other fill* APIs, there's a stroke equivalent for text.

Measuring text

Typography enthusiasts should be excited to learn that you can read many font metrics directly with ctx.measureText("..."). Unfortunately, some metrics such as emHeightAscent cannot currently be used due to poor browser support [caniuse].

Text alignment

By default text is expected to be aligned to the bottom-left. However, you can see that the descenders of the comma and letter g are clipped. Using the right vertical alignment can fix this.

Vertical alignment

Use textBaseline for vertical alignment.

Horizontal alignment

Use textAlign for horizontal alignment. Possible values are left/right/center/start/end. The default is start, which maps to left in left-to-right locales and maps to right in right-to-left locales.

Font weights, italics, families

You can specify these properties (and others [MDN]) in the ctx.font as well.

Custom fonts

You have a few options:

1. Download a font and use @font-face in CSS [MDN], allowing the browser to decide when it loads and whether to show a fallback during loading.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Game</title>
    <style>
      @font-face {
        font-family: "Doto";
        font-style: normal;
        font-weight: 100 900; /* range of weights */
        font-display: swap;
        src: url(/fonts/doto.ttf) format("truetype");
      }
      p {
        color: transparent;
        font-family: "Doto";
      }
      canvas {
        position: fixed;
        inset: 0;
      }
    </style>
  </head>
  <body>
    <p>Hidden text to trick the browser into downloading the font asap</p>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

2. Use a service that does (1) for you, like Google Fonts. (Don't do this.)

3. For precise control over the timing of the loading of your font, download it and load with JavaScript. This is typically the best choice for games, so it's our pick in this guide.

To load a custom font in JavaScript, you'll first need to download a font file (typically .ttf, .otf, or .woff2) from a source like Google Fonts or itch.io. If you have a choice, woff2 is usually preferred for its smaller file sizes.

You'll then asynchronously load the font. See MDN for explanations of the global FontFace constructor and document.fonts.add.

Async font loading

Although the previous code works, you'll probably see a flash of unstyled text (FOUT) in a fallback font while the custom font initially loads.

One option is to simply render nothing until the font has loaded. You can decide for your project whether a fallback font or no text at all while it loads feels better.

Opacity using colors with alpha

fillStyle and strokeStyle accept a wide variety of color formats. Many of these support an Alpha channel, which you can use to control the opacity of whatever you are painting.

Opacity using globalAlpha

Often, simply using colors with an alpha channel for opacity won't be sufficient.

Fading in and out an image asset is one case where that approach breaks down.

Coordinating translucency changes across many different shapes, especially during a fade animation, is another example where the previous technique would be a pain.

For these and many other uses, we have globalAlpha.

Save and restore stack

You can save the full state of the Context2D at any time with ctx.save(), then restore it with ctx.restore().

drawImage

ctx.drawImage(image, x, y) [MDN] paints an image with its top-left corner at (x, y) drawn at its intrinsic size.

async function loadImage(src: string) {
  const image = new Image();
  image.src = src;
  await image.decode();
  return image;
}

drawImage with destination rectangle

The same drawImage method has another form that accepts a destination width and height. The entire image is mapped onto the rectangle defined by (x, y, width, height), so the original aspect ratio is ignored.

ctx.drawImage(image, x, y, width, height);

drawImage with source crop and scale

The third, final form that drawImage supports uses nine arguments to crop according to a source rectangle then scale and draw according to a destination rectangle. This is super useful for spritesheets.

Nine-argument function calls are a lot to look at, so the key is to think of the two rectangles separately:

• The source rectangle (sx, sy, sw, sh) (in image pixels) defines which parts of the source image to use.
• The destination rectangle (x, y, w, h) (on the canvas) defines where to paint the source image.

Image scaling option 1: contain

To contain the full image within the canvas (like object-fit: contain [MDN]), figure out whether the height or width will be the smaller factor, then scale uniformly according to that factor and center the image. Since we're drawing the entire source image, we only need the five-argument form of drawImage.

Image scaling option 2: cover

For object-fit: cover behavior, figure out which dimension needs the larger scale factor, then derive the crop dimensions. The source rect starts at (0, 0), so extra pixels are chopped off the right or bottom edges.

This requires the nine-argument drawImage function signature.

import imageUrl from "./assets/example.png";
const canvas = document.createElement("canvas");
const ctx = canvas.getContext("2d")!;
const image = new Image();
image.src = imageUrl;

const bounds = canvas.getBoundingClientRect();
const { width, height } = bounds;
const nw = image.naturalWidth;
const nh = image.naturalHeight;
const scale = Math.max(width / nw, height / nh);
const sw = width / scale;
const sh = height / scale;
const sx = (nw - sw) / 2;
const sy = (nh - sh) / 2;
const source = { x: sx, y: sy, w: sw, h: sh };
const dest = { x: 0, y: 0, w: width, h: height };
ctx.drawImage(
  image, // source bitmap
  source.x,
  source.y,
  source.w,
  source.h,
  dest.x,
  dest.y,
  dest.w,
  dest.h,
);

Crisp pixels for pixel art

The pixel art in the previous demo looks bad! To scale images up sharply, you'll also need to set ctx.imageSmoothingEnabled = false to disable antialiasing.

Blur

Applies a Gaussian blur to all following paints. This will get your fans humming if done within a game loop!

Brightness

Contrast

Grayscale

Hue-rotate

Invert

Fun fact: invert(50%) always creates middle gray.

Opacity

Included here for completeness, but please never do this. Use globalAlpha or semitransparent colors instead.

Saturate

Sepia

Multiple filters

You can combine as many filters as you'd like.

Intro to gradients

fillStyle and strokeStyle can be used for more than just colors. Gradients also work!

We'll start with linear gradients. You'll pick a starting coordinate and ending coordinate, then add color stops some % along that line.

It's important to note that the gradient exists in global canvas pixels. This demo shows how it's not scaled to the shape you're applying it to.

Horizontal gradients

Same deal as vertical gradients, just change the coordinates of the line for the gradient. You can follow the same approach for angled linear gradients.

Radial gradients

For radial gradients, instead of defining a line you define two circles: createRadialGradient(x1, y1, r1, x2, y2, r2)

The first circle is usually a point in the middle and the second circle is the full size of the glow you want to create.

Radial gradient lighting effect

If you misalign the inner and outer circles, you can create a downlight effect.

Conic gradients

Useful for color wheels.

Multiply

Hue

Color

Similar to hue but also applies saturation.

Overlay

Overlay with texture

destination-out (text subtraction)

destination-out subtracts everything from the background that overlaps with the drawn shape.

destination-in (text mask)

destination-in subtracts everything from the background outside of the drawn shape.

destination-in (gradient mask)

Useful for weapon scopes, flashlights, and fog-of-war effects when you need feathered or complex edges. Otherwise, clip() is often simpler.

destination-in (decals)

Circular clip on an image

Build a circle on the path, call clip(), then drawImage. Remember to save() and restore() to release the clipping mask.

Multiple Path2D clips (intersection)

You can also pass a Path2D [MDN] to clip(path) without touching the context's current path. Calling clip() again with another path intersects the new region with the previous clip.

Bonus: Clipped blur

Combined with a filter you can create a glassmorphic effect.

translate

ctx.translate(x, y) shifts the origin of the coordinate system. After translating, all drawing operations are offset by that amount. Here we draw the character at (0, 0) but it appears at (80, 30) because the origin has moved.

Transforms are cumulative

Each translate shifts the origin from its current position, not from (0, 0). Two translate(100, 0) calls are the same as one translate(200, 0).

The same is true of rotate and scale.

scale

ctx.scale(x, y) multiplies all coordinates and sizes. This also affects positions, not just dimensions!

Negative scale to flip

ctx.scale(-1, 1) mirrors the x-axis, flipping your drawing horizontally. Because the axis reverses, you need to translate first so the result stays in view. Similarly, ctx.scale(1, -1) mirrors the y-axis.

rotate

ctx.rotate(angle) rotates the coordinate system clockwise by angle radians. Rotation happens around the current origin (0, 0) by default--which is usually not what you want.

Rotate around a point

To rotate around a specific point, translate to that point first, then rotate. When you draw, you'll also need to offset the x and y by half the object's width and height.

setTransform

ctx.setTransform(a, b, c, d, e, f) and ctx.resetTransform() replace the current transform matrix entirely rather than multiplying onto it like translate/scale/rotate do.

You'll mainly use it to:

1. Perform advanced transformations
2. Handle DPI scaling

As a general tool for transforms

setTransform can apply any of the above transformations without accumulating its effect with repeat calls. The arguments a–f map cleanly to each of the other transforms.

DPI scaling in-depth

The key insight is that we're dealing with three distinct "pixel" concepts:

1. Physical pixels -- the actual hardware pixels on the screen. A 2019 MacBook Pro has 2560×1600 of these on its "retina" display.
2. CSS pixels -- the abstract unit browsers use for layout. That same MacBook runs its browser at 1280×800 CSS pixels. These are device-independent and can be affected by browser zoom. When you write width: 100px in CSS, you mean 100 CSS pixels.
3. Canvas buffer pixels -- the internal resolution of the canvas element, set by canvas.width and canvas.height. This is completely independent of the canvas's size on the page.

Suppose we're working with a canvas 800px wide on that 2019 MacBook Pro. Its devicePixelRatio is 2, so there are 1,600 physical pixels spanning the width of the canvas. Our internal canvas buffer still only has 800 slots on the x axis for pixels, though. So our first task is to remedy that by setting canvas.width = width * dpr.

This creates two new problems:

1. Within the canvas, we're operating on a much larger area. If you call fillText("Hello", 20, 100) you meant 20 CSS pixels from the left, but now 20 buffer pixels is a tiny fraction of the way across. Everything would draw in the wrong place at the wrong size.
2. The canvas itself now occupies twice as much space in the layout.

ctx.setTransform(dpr, 0, 0, dpr, 0, 0) fixes the first problem. It scales the x and y axes within the canvas so that fillText("Hello", 20, 100) actually lands at (40, 200) but visually appears 20 CSS pixels from the left. It's just like ctx.scale(dpr, dpr) but without the cumulative effects. scale compounds with previous transforms, setTransform does not.

canvas.style.width = width + "px" addresses the second problem. Explicitly setting the number of CSS pixels occupied in the layout by the canvas ensures the canvas only takes up its original CSS size.