HTML Canvas coordinate systems and rendering process

Question

I'm playing with drawing on html canvas and I'm little confused of how different coordinate systems actually works. What I have learned so far is that there are more coordinate systems:

• canvas coordinate system
• css coordinate system
• physical (display) coordinate system

So when I draw a line using CanvasRenderingContext2D

ctx.lineWidth = 1;
ctx.beginPath();
ctx.moveTo(3, 1);
ctx.lineTo(3, 5);
ctx.stroke();

before drawing pixels to the display, the path needs to be

1. scaled according to the ctx transformation matrix (if any)
2. scaled according to the ratio between css canvas element dimensions (canvas.style.width and canvas.style.height) and canvas drawing dimensions (canvas.width and canvas.height)
3. scaled according to the window.devicePixelRatio (hi-res displays)

Now when I want to draw a crisp line, I found that there are two things to fight with. The first one is that canvas uses antialiasing. So when I draw a line of thikness 1 at integer coordinates, it will be blurred.

To fix this, it needs to be shifted by 0.5 pixels

ctx.moveTo(3.5, 1);
ctx.lineTo(3.5, 5);

The second thing to consider is window.devicePixelRatio. It is used to map logical css pixels to physical pixels. The snadard way how to adapt canvas to hi-res devices is to scale to the ratio

const ratio = window.devicePixelRatio || 1;
const clientBoundingRectangle = canvas.getBoundingClientRect();
  
canvas.width = clientBoundingRectangle.width * ratio;
canvas.height = clientBoundingRectangle.height * ratio;

const ctx = canvas.getContext('2d');
ctx.scale(ratio, ratio);

My question is, how is the solution of the antialiasing problem related to the scaling for the hi-res displays?

Let's say my display is hi-res and window.devicePixelRatio is 2.0. When I apply context scaling to adapt canvas to the hi-res display and want to draw the line with thickness of 1, can I just ignore the context scale and draw

ctx.moveTo(3.5, 1);
ctx.lineTo(3.5, 5);

which is in this case effectively

ctx.moveTo(7, 2);
ctx.lineTo(7, 10);

or do I have to consider the scaling ratio and use something like

ctx.moveTo(3.75, 1);
ctx.lineTo(3.75, 5);

to get the crisp line?

Answer 1

Preventing anti-aliasing requires that the pixels of the canvas, which is a raster image, are aligned with the pixels of the screen, which can be done by multiplying the canvas size by the devicePixelRatio, while using the CSS size to hold the canvas to its original size:

canvas.width = pixelSize * window.devicePixelRatio;
canvas.height = pixelSize * window.devicePixelRatio;
canvas.style.width = pixelSize + 'px';
canvas.style.height = pixelSize + 'px';

You can then use scale on the context, so that the drawn images won't be shrunk by higher devicePixelRatios. Here I am rounding so that lines can be crisp on ratios that are not whole numbers:

let roundedScale = Math.round(window.devicePixelRatio);
context.scale(roundedScale, roundedScale);

The example then draws a vertical line from the center top of one pixel to the center top of another:

context.moveTo(100.5, 10);
context.lineTo(100.5, 190);

One thing to keep in mind is zooming. If you zoom in on the example, it will become anti-aliased as the browser scales up the raster image. If you then click run on the example again, it will become crisp again (on most browsers). This is because most browsers update the devicePixelRatio to include any zooming. If you are rendering in an animation loop while they are zooming, the rounding could cause some flickering.

Answer 2

Antialiasing can occur both in the rendering on the canvas bitmap buffer, at the time you draw to it, and at the time it's displayed on the monitor, by CSS.

The 0.5px offset for straight lines works only for line widths that are odd integers. As you hinted to, it's so that the stroke, that can only be aligned to the center of the path, and thus will spread inside and outside of the actual path by half the line width, falls on full pixel coordinates. For a comprehensive explanation, see this previous answer of mine.

Scaling the canvas buffer to the monitor's pixel ratio works because on high-res devices, multiple physical dots will be used to cover a single px area. This allows to have more details e.g in texts, or other vector graphics. However, for bitmaps this means the browser has to "pretend" it was bigger in the first place. For instance a 100x100 image, rendered on a 2x monitor will have to be rendered as if it was a 200x200 image to have the same size as on a 1x monitor. During that scaling, the browser may yet again use antialiasing, or another scaling algorithm to "create" the missing pixels.
By directly scaling up the canvas by the pixel ratio, and scaling it down through CSS, we end up with an original bitmap that's the size it will be rendered, and there is no need for CSS to scale anything anymore.

But now, your canvas context is scaled by this pixel ratio too, and if we go back to our straight lines, still assuming a 2x monitor, the 0.5px offset now actually becomes a 1px offset, which is useless. A lineWidth of 1 will actually generate a 2px stroke, which doesn't need any offset.

So no, don't ignore the scaling when offsetting your context for straight lines.

But the best is probably to not use that offset trick at all, and instead use rect() calls and fill() if you want your lines to fit perfectly on pixels.

const canvas = document.querySelector("canvas");
// devicePixelRatio may not be accurate, see below
setCanvasSize(canvas);

function draw() {
  const dPR = devicePixelRatio;
  const ctx = canvas.getContext("2d");
  // scale() with weird zoom levels may produce antialiasing
  // So one might prefer to do the scaling of all coords manually:
  const lineWidth = Math.round(1 * dPR);
  const cellSize  = Math.round(10 * dPR);
  for (let x = cellSize; x < canvas.width; x += cellSize) {
    ctx.rect(x, 0, lineWidth, canvas.height);
  }
  for (let y = cellSize; y < canvas.height; y += cellSize) {
    ctx.rect(0, y, canvas.width, lineWidth);
  }
  ctx.fill();
}

function setCanvasSize(canvas) {
// We resize the canvas bitmap based on the size of the viewport
// while respecting the actual dPR
// Thanks to gman for the reminder of how to suppport all early impl.
// https://stackoverflow.com/a/65435847/3702797
  const observer = new ResizeObserver(([entry]) => {
    let width;
    let height;
    const dPR = devicePixelRatio;
    if (entry.devicePixelContentBoxSize) {
      width  = entry.devicePixelContentBoxSize[0].inlineSize;
      height = entry.devicePixelContentBoxSize[0].blockSize;
    } else if (entry.contentBoxSize) {
      if ( entry.contentBoxSize[0]) {
        width  = entry.contentBoxSize[0].inlineSize * dPR;
        height = entry.contentBoxSize[0].blockSize  * dPR;
      } else {
        width  = entry.contentBoxSize.inlineSize * dPR;
        height = entry.contentBoxSize.blockSize  * dPR;
      }
    } else {
      width  = entry.contentRect.width  * dPR;
      height = entry.contentRect.height * dPR;
    }
    canvas.width  = width;
    canvas.height = height;
    canvas.style.width  = (width  / dPR) + 'px';
    canvas.style.height = (height / dPR) + 'px';
    // we need to redraw
    draw();
  });
  // observe the scrollbox size changes
  try {
    observer.observe(canvas, { box: 'device-pixel-content-box' });
  }
  catch(err) {
    observer.observe(canvas, { box: 'content-box' });
  }
}

canvas { width: 300px; height: 150px; }

<canvas></canvas>