Window-to-viewport mapping and coordinate systems

A chart’s data runs from x = −2 to 2 and y = −1 to 1, and it has to fill a box of 400 by 200 pixels whose rows are counted downwards from the top. Choosing the pixel for each point is the window-to-viewport mapping, and the same few lines decide whether a circle stays round when the box turns square, whether a wheel’s rim follows its car, and whether the drawing is sharp on a phone that packs two or three device pixels into every CSS pixel.

You will map one window onto three viewports and follow a point through the viewing pipeline, keep shapes true by letterboxing or cropping, move points between nested frames and back, follow WebGPU’s own viewport from normalized device coordinates to pixels, and size a canvas bitmap for the screen. Every number comes from a program that runs on this page.

A window and a viewport: one scale and one shift per axis

The windowwindow: The rectangle of the world, in world units, that a view shows. Points inside it are mapped to the viewport; the parts of shapes outside it are clipped. is the rectangle of the world that a view shows, here x from −2 to 2 and y from −1 to 1, in the world’s own units. The viewportviewport: The rectangle of the screen or framebuffer, in pixels, that a view is drawn into. The window-to-viewport map takes the window onto it. is the rectangle of the screen it is drawn into, here 400 by 200 pixels with its origin at the top left. Mapping one onto the other takes a scale and a shift on each axis:

In words: measure how far the point is from the window’s left edge, turn that distance into pixels, and start from the viewport’s left edge; for y, measure down from the window’s top edge, because screen rows are counted downwards. Here both scales are 400 ÷ 4 = 200 ÷ 2 = 100 pixels a unit, so the point (1, 0.5), 3 units from the left edge and 0.5 below the top, lands at pixel (300, 50):

That map is the end of the 2D viewing pipelineviewing pipeline: The stages that take a point from its own shape's coordinates to a pixel: modelling coordinates, world coordinates, the window, normalised coordinates and the viewport., which takes a point from the shape it belongs to all the way to a pixel. Step through it with the same point:

The program maps the window onto three viewports. Its first lines check the corners and the point:

// Window-to-viewport mapping: a window of the world (y up) onto a viewport of pixels
// (y down, origin at the top left). Each axis gets one scale and one shift:
//   x_v = vx + (x - wxmin) * sx                sx = width / (wxmax - wxmin)
//   y_v = vy + (wymax - y) * sy                sy = height / (wymax - wymin)
// "stretch" uses both scales as they are; "letterbox" and "crop" use one scale for both
// axes, the smaller or the larger, and centre the window in the viewport.

function windowToViewport(win, vp, fit = 'stretch') {
  let sx = vp.width / (win.xmax - win.xmin);
  let sy = vp.height / (win.ymax - win.ymin);
  if (fit === 'letterbox') sx = sy = Math.min(sx, sy);
  if (fit === 'crop') sx = sy = Math.max(sx, sy);
  const cx = (win.xmin + win.xmax) / 2; // the window's centre goes to the viewport's centre
  const cy = (win.ymin + win.ymax) / 2;
  const vcx = vp.x + vp.width / 2;
  const vcy = vp.y + vp.height / 2;
  return { sx, sy, map: ([x, y]) => [vcx + (x - cx) * sx, vcy - (y - cy) * sy] };
}

const num = (v) => {
  const r = Number(v.toFixed(3));
  return Object.is(r, -0) ? '0' : String(r);
};
const point = ([x, y]) => `(${num(x)}, ${num(y)})`;

const WINDOW = { xmin: -2, xmax: 2, ymin: -1, ymax: 1 }; // 4 by 2 units: twice as wide as tall
const VIEWPORTS = [
  { x: 0, y: 0, width: 400, height: 200 },
  { x: 0, y: 0, width: 300, height: 300 },
  { x: 0, y: 0, width: 640, height: 360 },
];
const P = [1, 0.5];

console.log('window x from -2 to 2, y from -1 to 1');
const stretch = windowToViewport(WINDOW, VIEWPORTS[0]);
console.log(`viewport 400 x 200: sx = ${num(stretch.sx)}, sy = ${num(stretch.sy)} pixels per unit`);
for (const [label, p] of [["(-2, 1), the window's top left", [-2, 1]], ['(2, -1), its bottom right', [2, -1]], ['(1, 0.5), a point inside it', P]]) {
  console.log(`  ${label.padEnd(32)}-> ${point(stretch.map(p))}`);
}

for (const vp of VIEWPORTS.slice(1)) {
  console.log('');
  console.log(`viewport ${vp.width} x ${vp.height}`);
  for (const fit of ['stretch', 'letterbox', 'crop']) {
    const m = windowToViewport(WINDOW, vp, fit);
    // The unit circle drawn through this map: its width and height on screen.
    const w = 2 * m.sx;
    const h = 2 * m.sy;
    let what = `the unit circle is ${num(w)} x ${num(h)} pixels`;
    if (fit === 'letterbox') {
      const [x0, y0] = m.map([WINDOW.xmin, WINDOW.ymax]);
      const [x1, y1] = m.map([WINDOW.xmax, WINDOW.ymin]);
      what += `; the window fills ${num(x1 - x0)} x ${num(y1 - y0)}, bars of ${num(x0 - vp.x)} left and right, ${num(y0 - vp.y)} top and bottom`;
    }
    if (fit === 'crop') {
      const halfW = vp.width / 2 / m.sx;
      const halfH = vp.height / 2 / m.sy;
      what += `; it shows x from ${num(-halfW)} to ${num(halfW)} and y from ${num(-halfH)} to ${num(halfH)}`;
    }
    console.log(`  ${fit.padEnd(10)}sx = ${num(m.sx).padEnd(4)} sy = ${num(m.sy).padEnd(4)} ${what}`);
  }
}

window x from -2 to 2, y from -1 to 1
viewport 400 x 200: sx = 100, sy = 100 pixels per unit
  (-2, 1), the window's top left  -> (0, 0)
  (2, -1), its bottom right       -> (400, 200)
  (1, 0.5), a point inside it     -> (300, 50)

viewport 300 x 300
  stretch   sx = 75   sy = 150  the unit circle is 150 x 300 pixels
  letterbox sx = 75   sy = 75   the unit circle is 150 x 150 pixels; the window fills 300 x 150, bars of 0 left and right, 75 top and bottom
  crop      sx = 150  sy = 150  the unit circle is 300 x 300 pixels; it shows x from -1 to 1 and y from -1 to 1

viewport 640 x 360
  stretch   sx = 160  sy = 180  the unit circle is 320 x 360 pixels
  letterbox sx = 160  sy = 160  the unit circle is 320 x 320 pixels; the window fills 640 x 320, bars of 0 left and right, 20 top and bottom
  crop      sx = 180  sy = 180  the unit circle is 360 x 360 pixels; it shows x from -1.778 to 1.778 and y from -1 to 1

On the 400 × 200 viewport the window’s top left corner, (−2, 1), goes to pixel (0, 0) and its bottom right, (2, −1), to (400, 200). The map turns the window upside down so that it looks the right way up on a screen; that flip is the y_max − y in the second formula, and leaving it out is a common bug in this code.

Unequal scales distort shapes: letterbox or crop instead

Put the same window, 4 units by 2, onto a square viewport of 300 by 300 and the two scales part company: 75 pixels a unit across, 150 down. The unit circle comes out 150 pixels wide and 300 tall. Distortion appears whenever the window’s aspect ratioaspect ratio: Width divided by height. A window and a viewport with different aspect ratios cannot be matched with one scale without bars or a crop., its width over its height, differs from the viewport’s: here 2 against 1. Two fits keep shapes true, and both use one scale for both axes:

Letterboxingletterboxing: Fitting a picture into a viewport of another shape with one scale, the smaller of the two, so that all of it shows and the spare pixels become bars. takes the smaller scale, 75, so that the whole window fits and the spare pixels become bars: the window fills a band of 300 by 150 with 75 pixels above and below it. Cropping takes the larger scale, 150, so that the viewport is filled and the window’s ends are cut off: only x from −1 to 1 shows. The lower lines of the program give the numbers for the square viewport and for a 640 × 360 one, whose 16 : 9 shape is closer to the window’s 2 : 1:

The choice is about what may be lost. Letterboxing keeps every part of the window and spends pixels on bars; cropping spends none and loses the window’s edges. Canvases on a web page face the same choice one level up: the HTML standard fits a canvas’s bitmap into its CSS box with the object-fit property, whose initial value, fill, stretches it, while contain keeps the aspect ratio inside the box, a letterbox, and cover fills the box, a crop.

A frame’s matrix holds its axes and origin as columns

A car stands on a 30° slope, its wheel has turned, and a point on the wheel’s rim has to be drawn in the world. Each object has its own coordinate framecoordinate frame: An origin and a pair of axes, given in a parent frame's coordinates. Its matrix has the axes and the origin as columns and maps the frame's coordinates to the parent's., an origin and two axes measured in its parent’s frame, and the matrix of a frame has exactly those as its columns:

Here u is the frame’s x axis, v its y axis and o its origin, all in the parent’s coordinates. F times a point’s local coordinates (a, b, 1) is o + a u + b v: start at the frame’s origin, walk a along its x axis and b along its y axis. The car’s frame has u = (0.866, 0.5), v = (−0.5, 0.866) and o = (10, 2). The wheel’s frame sits inside the car’s, so a rim point goes through the wheel’s matrix first and the car’s after it, and coming back takes the inverses in the opposite order:

// Nested coordinate frames: a point on a wheel, a wheel on a car, a car in the world.
// A frame's matrix has the frame's x axis, y axis and origin, written in its parent's
// coordinates, as its three columns. It maps the frame's coordinates to the parent's;
// its inverse maps the parent's back.

const frame = (origin, degrees) => {
  const r = (degrees * Math.PI) / 180;
  const xAxis = [Math.cos(r), Math.sin(r)];
  const yAxis = [-Math.sin(r), Math.cos(r)];
  return [[xAxis[0], yAxis[0], origin[0]], [xAxis[1], yAxis[1], origin[1]], [0, 0, 1]];
};
function multiply(a, b) {
  const out = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
  for (let i = 0; i < 3; i++) for (let j = 0; j < 3; j++) for (let k = 0; k < 3; k++) out[i][j] += a[i][k] * b[k][j];
  return out;
}
// A frame is a turn and a move, so its inverse turns back by the transpose: [R^T, -R^T t].
function invertFrame(m) {
  const [a, c, tx] = m[0];
  const [b, d, ty] = m[1];
  return [[a, b, -(a * tx + b * ty)], [c, d, -(c * tx + d * ty)], [0, 0, 1]];
}
const apply = (m, [x, y]) => [m[0][0] * x + m[0][1] * y + m[0][2], m[1][0] * x + m[1][1] * y + m[1][2]];
const num = (v) => {
  const r = Number(v.toFixed(3));
  return Object.is(r, -0) ? '0' : String(r);
};
const point = ([x, y]) => `(${num(x)}, ${num(y)})`;

const car = frame([10, 2], 30); // the car sits at (10, 2) in the world, on a 30 degree slope
const wheel = frame([1.5, -0.5], 90); // the wheel's hub, in the car's frame; the wheel has turned 90 degrees
const rim = [0.4, 0]; // a point on the rim, in the wheel's own frame

console.log(`car frame in the world: x axis ${point([car[0][0], car[1][0]])}, y axis ${point([car[0][1], car[1][1]])}, origin ${point([car[0][2], car[1][2]])}`);
const inCar = apply(wheel, rim);
const inWorld = apply(car, inCar);
console.log(`the rim point ${point(rim)} in the wheel's frame`);
console.log(`  is ${point(inCar)} in the car's frame (wheel matrix)`);
console.log(`  is ${point(inWorld)} in the world (car matrix after it)`);
const wheelInWorld = multiply(car, wheel);
console.log(`one matrix, car times wheel, sends it straight to ${point(apply(wheelInWorld, rim))}`);
console.log(`its columns are the wheel's axes and hub in the world: ${point([wheelInWorld[0][0], wheelInWorld[1][0]])}, ${point([wheelInWorld[0][1], wheelInWorld[1][1]])}, ${point([wheelInWorld[0][2], wheelInWorld[1][2]])}`);

const back = apply(invertFrame(wheel), apply(invertFrame(car), inWorld));
console.log('');
console.log(`back again: world -> car -> wheel gives ${point(back)}`);
console.log(`round trip within 1e-12: ${Math.hypot(back[0] - rim[0], back[1] - rim[1]) < 1e-12 ? 'yes' : 'no'}`);
const wrong = apply(multiply(wheel, car), rim);
console.log(`the wrong order, wheel times car, puts the point at ${point(wrong)}`);

car frame in the world: x axis (0.866, 0.5), y axis (-0.5, 0.866), origin (10, 2)
the rim point (0.4, 0) in the wheel's frame
  is (1.5, -0.1) in the car's frame (wheel matrix)
  is (11.349, 2.663) in the world (car matrix after it)
one matrix, car times wheel, sends it straight to (11.349, 2.663)
its columns are the wheel's axes and hub in the world: (-0.5, 0.866), (-0.866, -0.5), (11.549, 2.317)

back again: world -> car -> wheel gives (0.4, 0)
round trip within 1e-12: yes
the wrong order, wheel times car, puts the point at (-0.7, 9.846)

The rim point (0.4, 0) is (1.5, −0.1) in the car’s frame and (11.349, 2.663) in the world, and one matrix, car times wheel, makes both steps at once; its columns are the wheel’s axes and hub written in the world. Each frame is a turn and a move, a rigid transformationrigid transformation: A rotation followed by a translation. It keeps every length and angle, and its inverse is the transposed rotation with a negated, rotated translation. More in “Matrices and homogeneous coordinates”, so its inverse subtracts the origin and turns back by the transpose, and the round trip returns (0.4, 0) within 1e-12. Multiplied the other way round, wheel times car, the same matrices put the point at (−0.7, 9.846), nowhere near the car.

WebGPU’s viewport maps normalized device coordinates to pixels

A GPU ends its pipeline with the same map and a fixed window. WebGPU divides each position the vertex shader returns by its w, giving normalized device coordinatesnormalized device coordinates (NDC): The coordinates a GPU reaches after dividing positions by w. In WebGPU, x and y run from −1 to 1 with y up and depth from 0 to 1; the viewport maps them to pixels., NDC, in which x and y run from −1 to 1 with y up and depth runs from 0 to 1. The viewport set with setViewport(x, y, width, height, minDepth, maxDepth) then maps them to framebuffer pixels, whose origin is the top left corner with y down. The specification writes the map as:

In words: shift NDC from −1…1 to 0…2, halve it, scale it to the viewport’s size, and flip y. Depth is mapped the same way, from 0…1 to minDepth…maxDepth. It is the window-to-viewport map of the first section, with the window fixed at −1 to 1 on both axes:

// WebGPU's viewport transform (WebGPU specification, section 23.2.5): normalized device
// coordinates (x and y from -1 to 1 with y up, z from 0 to 1) go to framebuffer pixels
// (origin at the top left, y down) and to a depth in [minDepth, maxDepth]:
//   x_fb = vp.x + 0.5 * (n.x + 1) * vp.width
//   y_fb = vp.y + 0.5 * (-n.y + 1) * vp.height
//   depth = vp.minDepth + n.z * (vp.maxDepth - vp.minDepth)

function framebufferCoords(n, vp) {
  return [vp.x + 0.5 * (n[0] + 1) * vp.width, vp.y + 0.5 * (-n[1] + 1) * vp.height, vp.minDepth + n[2] * (vp.maxDepth - vp.minDepth)];
}
const num = (v) => {
  const r = Number(v.toFixed(4));
  return Object.is(r, -0) ? '0' : String(r);
};
const show = (p) => `(${p.map(num).join(', ')})`;

const full = { x: 0, y: 0, width: 800, height: 600, minDepth: 0, maxDepth: 1 };
const corner = { x: 400, y: 0, width: 400, height: 300, minDepth: 0, maxDepth: 1 };
const nearHalf = { x: 0, y: 0, width: 800, height: 600, minDepth: 0.5, maxDepth: 1 };
const points = [
  ['(-1, 1), top left', [-1, 1, 0]],
  ['(1, -1), bottom right', [1, -1, 0]],
  ['(0, 0), the centre', [0, 0, 0]],
  ['(0.5, 0.5)', [0.5, 0.5, 0]],
];

console.log('setViewport(0, 0, 800, 600, 0, 1): the whole 800 x 600 target');
for (const [label, n] of points) console.log(`  NDC ${label.padEnd(22)}-> pixel ${show(framebufferCoords(n, full).slice(0, 2))}`);
console.log(`  one unit of NDC is ${num(full.width / 2)} pixels across and ${num(full.height / 2)} pixels down`);

console.log('');
console.log('setViewport(400, 0, 400, 300, 0, 1): the top right quarter');
for (const [label, n] of points.slice(0, 3)) console.log(`  NDC ${label.padEnd(22)}-> pixel ${show(framebufferCoords(n, corner).slice(0, 2))}`);

console.log('');
console.log('depth: NDC z = 0.25 is stored as');
console.log(`  ${num(framebufferCoords([0, 0, 0.25], full)[2])} with minDepth 0 and maxDepth 1`);
console.log(`  ${num(framebufferCoords([0, 0, 0.25], nearHalf)[2])} with minDepth 0.5 and maxDepth 1`);

// The pixel in the top left corner covers x and y from 0 to 1; its centre is (0.5, 0.5).
// Inverting the map tells where that centre lies in NDC.
const ndcOf = ([x, y], vp) => [((x - vp.x) / vp.width) * 2 - 1, 1 - ((y - vp.y) / vp.height) * 2];
console.log('');
console.log(`the centre of the top left pixel, (0.5, 0.5), is NDC ${show(ndcOf([0.5, 0.5], full))}`);

setViewport(0, 0, 800, 600, 0, 1): the whole 800 x 600 target
  NDC (-1, 1), top left     -> pixel (0, 0)
  NDC (1, -1), bottom right -> pixel (800, 600)
  NDC (0, 0), the centre    -> pixel (400, 300)
  NDC (0.5, 0.5)            -> pixel (600, 150)
  one unit of NDC is 400 pixels across and 300 pixels down

setViewport(400, 0, 400, 300, 0, 1): the top right quarter
  NDC (-1, 1), top left     -> pixel (400, 0)
  NDC (1, -1), bottom right -> pixel (800, 300)
  NDC (0, 0), the centre    -> pixel (600, 150)

depth: NDC z = 0.25 is stored as
  0.25 with minDepth 0 and maxDepth 1
  0.625 with minDepth 0.5 and maxDepth 1

the centre of the top left pixel, (0.5, 0.5), is NDC (-0.9988, 0.9983)

On the full 800 × 600 target NDC (−1, 1) is pixel (0, 0), the centre is (400, 300) and (0.5, 0.5) is (600, 150). Setting the viewport to the top right quarter, setViewport(400, 0, 400, 300, 0, 1), sends the same centre to (600, 150), which is how one canvas shows several views side by side. With minDepth 0.5 a depth of 0.25 is stored as 0.625. Pixels are sampled at their centres, and the centre of the top left pixel, (0.5, 0.5) in framebuffer coordinates, is NDC (−0.9988, 0.9983). One unit of NDC is 400 pixels across but 300 down, so a square in NDC is drawn as a rectangle: the stretch of the previous section, which the camera’s projection matrix will undo with the viewport’s aspect ratio in the cameras module.

Size the canvas bitmap in device pixels, or it blurs

A canvas has two sizes. Its width and height attributes set its bitmap, 300 by 150 when they are not given, and CSS sets the box it takes on the page, in CSS pixels; the HTML standard’s own example draws a 200 × 200 bitmap in a 100 × 100 box. A screen’s device pixel ratiodevice pixel ratio: The size of a CSS pixel divided by the size of a device pixel, window.devicePixelRatio. A canvas needs its CSS size times this ratio in bitmap pixels to look sharp., window.devicePixelRatio, is the size of a CSS pixel divided by the size of a device pixel. On a phone whose ratio is 2 or 3, a bitmap sized in CSS pixels is stretched across several device pixels for each of its own:

The fix is to give the bitmap one pixel per device pixel, canvas.width = Math.round(cssWidth * devicePixelRatio), and to keep drawing in CSS pixels with ctx.scale(devicePixelRatio, devicePixelRatio). How the browser fills in a stretched bitmap is its own choice, since CSS’s image-rendering starts as auto, but a stretched line is twice as thick at ratio 2 whatever it chooses. The program works out what the fix costs, and what a click means:

// A canvas has two sizes: its box on the page, in CSS pixels, and its bitmap, in canvas
// pixels (the width and height attributes). devicePixelRatio is how many device pixels
// one CSS pixel covers. For a sharp drawing the bitmap needs one pixel per device pixel:
//   canvas.width = Math.round(cssWidth * devicePixelRatio)
// With the default colour type, unorm8, each of a pixel's four components takes 8 bits:
// 4 bytes a pixel. The program works the numbers out; it runs no browser.

const num = (v) => {
  const r = Number(v.toFixed(3));
  return Object.is(r, -0) ? '0' : String(r);
};

const css = { width: 400, height: 200 }; // the canvas's box, set by CSS
console.log(`a canvas box of ${css.width} x ${css.height} CSS pixels`);
console.log('ratio  bitmap for a sharp drawing  memory (4 bytes a pixel)  device pixels per bitmap pixel if left at 400 x 200');
for (const dpr of [1, 1.25, 1.5, 2, 3]) {
  const w = Math.round(css.width * dpr);
  const h = Math.round(css.height * dpr);
  const bytes = w * h * 4;
  console.log(`${String(dpr).padEnd(7)}${`${w} x ${h}`.padEnd(30)}${`${num(bytes / 1e6)} MB`.padEnd(26)}${num(dpr * dpr)}`);
}

// A box whose CSS size times the ratio is not a whole number of pixels.
const odd = 333;
const exact = odd * 1.5;
const rounded = Math.round(exact);
console.log('');
console.log(`a box ${odd} CSS pixels wide at ratio 1.5 covers ${exact} device pixels; the bitmap gets ${rounded}`);
console.log(`so ${rounded} bitmap pixels are squeezed into ${exact} device pixels: ${num(rounded / exact)} per device pixel, a slight resampling`);

// A click arrives in CSS pixels, relative to the box. The drawing uses bitmap pixels,
// and the scene uses world units: window x from -2 to 2, y from -1 to 1 on the whole bitmap.
const dpr = 2;
const bitmap = { width: Math.round(css.width * dpr), height: Math.round(css.height * dpr) };
const win = { xmin: -2, xmax: 2, ymin: -1, ymax: 1 };
const click = [300, 50]; // offsetX and offsetY of a pointer event, in CSS pixels
const inBitmap = [click[0] * (bitmap.width / css.width), click[1] * (bitmap.height / css.height)];
const inWorld = [win.xmin + inBitmap[0] / (bitmap.width / (win.xmax - win.xmin)), win.ymax - inBitmap[1] / (bitmap.height / (win.ymax - win.ymin))];
console.log('');
console.log(`at ratio ${dpr} the bitmap is ${bitmap.width} x ${bitmap.height}`);
console.log(`a click at CSS (${click.join(', ')}) is bitmap pixel (${inBitmap.map(num).join(', ')}) and world point (${inWorld.map(num).join(', ')})`);
const wrong = [win.xmin + click[0] / (bitmap.width / (win.xmax - win.xmin)), win.ymax - click[1] / (bitmap.height / (win.ymax - win.ymin))];
console.log(`skipping the CSS-to-bitmap step reads it as world point (${wrong.map(num).join(', ')})`);

a canvas box of 400 x 200 CSS pixels
ratio  bitmap for a sharp drawing  memory (4 bytes a pixel)  device pixels per bitmap pixel if left at 400 x 200
1      400 x 200                     0.32 MB                   1
1.25   500 x 250                     0.5 MB                    1.563
1.5    600 x 300                     0.72 MB                   2.25
2      800 x 400                     1.28 MB                   4
3      1200 x 600                    2.88 MB                   9

a box 333 CSS pixels wide at ratio 1.5 covers 499.5 device pixels; the bitmap gets 500
so 500 bitmap pixels are squeezed into 499.5 device pixels: 1.001 per device pixel, a slight resampling

at ratio 2 the bitmap is 800 x 400
a click at CSS (300, 50) is bitmap pixel (600, 100) and world point (1, 0.5)
skipping the CSS-to-bitmap step reads it as world point (-0.5, 0.75)

A 400 × 200 box needs an 800 × 400 bitmap at ratio 2 and 1200 × 600 at ratio 3, which takes 2.88 MB at 4 bytes a pixel, the canvas’s default unorm8 colour type: nine times the memory of ratio 1. Left at 400 × 200 on a ratio-3 screen, each bitmap pixel covers 9 device pixels. Some boxes cannot match exactly: 333 CSS pixels at ratio 1.5 cover 499.5 device pixels, and the bitmap has to round to 500. Clicks travel the other way. They arrive in CSS pixels relative to the box, so multiply by the bitmap’s width over the box’s before applying the inverse of the window-to-viewport map: a click at (300, 50) is bitmap pixel (600, 100) and world point (1, 0.5), while skipping that step reads it as (−0.5, 0.75).

Practise: map, fit and change frames

Two exercises turn the lesson into code, and their sample tests run here in the page. The first maps a window onto a viewport with every fit, held to the lesson’s three viewports; the second moves points between nested frames and back, held to the car and wheel and to 200 seeded chains of frames:

/**
 * windowToViewport(win, vp, fit) returns the 3 x 3 matrix, as three rows, that maps the window
 * win = { xmin, xmax, ymin, ymax } of the world, where y points up, to the viewport
 * vp = { x, y, width, height } in pixels, where the origin is the top left corner and y points down.
 *   fit 'stretch':   each axis gets its own scale
 *   fit 'letterbox': both axes get the smaller scale, and the window is centred in the viewport
 *   fit 'crop':      both axes get the larger scale, and the window is centred in the viewport
 * Throw a RangeError when the window or the viewport has no width or no height.
 * This first version stretches every time and forgets that y points down on the screen.
 */
export function windowToViewport(win, vp, fit = 'stretch') {
  const sx = vp.width / (win.xmax - win.xmin);
  const sy = vp.height / (win.ymax - win.ymin);
  return [[sx, 0, vp.x - win.xmin * sx], [0, sy, vp.y - win.ymin * sy], [0, 0, 1]];
}

import { test, assert } from 'mysmartcopilot:test';
import { windowToViewport } from './viewport.mjs';

const apply = (m, [x, y]) => [m[0][0] * x + m[0][1] * y + m[0][2], m[1][0] * x + m[1][1] * y + m[1][2]];
const round = (v) => {
  const r = Math.round(v * 1000) / 1000;
  return Object.is(r, -0) ? 0 : r;
};
const at = (m, p) => apply(m, p).map(round);
const WINDOW = { xmin: -2, xmax: 2, ymin: -1, ymax: 1 };

test('the lesson window on a 400 x 200 viewport, y flipped', () => {
  const m = windowToViewport(WINDOW, { x: 0, y: 0, width: 400, height: 200 });
  assert.deepEqual(at(m, [-2, 1]), [0, 0], "the window's top left goes to the viewport's top left");
  assert.deepEqual(at(m, [2, -1]), [400, 200], 'its bottom right goes to the bottom right');
  assert.deepEqual(at(m, [1, 0.5]), [300, 50], 'the point (1, 0.5)');
  assert.deepEqual(m[2], [0, 0, 1], 'the bottom row stays (0, 0, 1)');
});

test('a viewport that does not start at the origin', () => {
  const m = windowToViewport(WINDOW, { x: 50, y: 20, width: 400, height: 200 });
  assert.deepEqual(at(m, [-2, 1]), [50, 20], 'top left');
  assert.deepEqual(at(m, [0, 0]), [250, 120], 'the centre');
});

test('stretch, letterbox and crop on a square viewport', () => {
  const vp = { x: 0, y: 0, width: 300, height: 300 };
  const s = windowToViewport(WINDOW, vp, 'stretch');
  assert.deepEqual(at(s, [1, 0]).concat(at(s, [0, 1])), [225, 150, 150, 0], 'stretch: 75 pixels a unit across, 150 down');
  const l = windowToViewport(WINDOW, vp, 'letterbox');
  assert.deepEqual(at(l, [-2, 1]), [0, 75], 'letterbox: a bar of 75 above the window');
  assert.deepEqual(at(l, [2, -1]), [300, 225], 'letterbox: and 75 below it');
  assert.deepEqual(at(l, [0, 0]), [150, 150], 'letterbox: the centres meet');
  const c = windowToViewport(WINDOW, vp, 'crop');
  assert.deepEqual(at(c, [-1, 1]), [0, 0], 'crop: x = -1 is the left edge');
  assert.deepEqual(at(c, [1, -1]), [300, 300], 'crop: x = 1 is the right edge');
});

test('a 16:9 viewport', () => {
  const vp = { x: 0, y: 0, width: 640, height: 360 };
  assert.deepEqual(at(windowToViewport(WINDOW, vp, 'letterbox'), [-2, 1]), [0, 20], 'letterbox: bars of 20');
  const c = windowToViewport(WINDOW, vp, 'crop');
  assert.deepEqual(at(c, [0, 1]), [320, 0], 'crop: y = 1 is the top edge');
  assert.equal(round(c[0][0]), 180, 'crop: 180 pixels a unit');
});

test('a window or viewport with no width or height is refused', () => {
  assert.throws(() => windowToViewport({ xmin: 1, xmax: 1, ymin: 0, ymax: 2 }, { x: 0, y: 0, width: 100, height: 100 }), 'a window of width 0');
  assert.throws(() => windowToViewport(WINDOW, { x: 0, y: 0, width: 0, height: 100 }), 'a viewport of width 0');
  assert.throws(() => windowToViewport(WINDOW, { x: 0, y: 0, width: 100, height: 0 }, 'letterbox'), 'a viewport of height 0');
});

/**
 * A frame is { origin: [x, y], degrees }: where its origin is and how far its x axis is turned,
 * both measured in its parent's coordinates.
 *   frameMatrix(frame)       the 3 x 3 matrix whose columns are the frame's x axis, y axis and origin
 *   toParent(frames, p)      p is given in the innermost frame of `frames`, which lists the frames from the
 *                            outermost inwards; return it in the outermost frame's parent (the world)
 *   toInnermost(frames, q)   the inverse: a point of the world, in the innermost frame
 * frameMatrix already works. toParent applies the frames in the wrong order, and toInnermost
 * transposes the whole matrix, which loses the translation.
 */
export function frameMatrix({ origin, degrees }) {
  const r = (degrees * Math.PI) / 180;
  const c = Math.cos(r);
  const s = Math.sin(r);
  return [[c, -s, origin[0]], [s, c, origin[1]], [0, 0, 1]];
}

const apply = (m, [x, y]) => [m[0][0] * x + m[0][1] * y + m[0][2], m[1][0] * x + m[1][1] * y + m[1][2]];
const transpose = (m) => m[0].map((_, j) => m.map((row) => row[j]));

export function toParent(frames, p) {
  let q = p;
  for (const f of frames) q = apply(frameMatrix(f), q);
  return q;
}

export function toInnermost(frames, q) {
  let p = q;
  for (let i = frames.length - 1; i >= 0; i--) p = apply(transpose(frameMatrix(frames[i])), p);
  return p;
}

import { test, assert } from 'mysmartcopilot:test';
import { frameMatrix, toParent, toInnermost } from './frames.mjs';

const close = (a, b, eps = 1e-9) => Math.abs(a[0] - b[0]) < eps && Math.abs(a[1] - b[1]) < eps;
const show = (p) => `(${p.map((v) => v.toFixed(4)).join(', ')})`;
const CAR = { origin: [10, 2], degrees: 30 };
const WHEEL = { origin: [1.5, -0.5], degrees: 90 };
const c30 = Math.cos(Math.PI / 6);

test("a frame's matrix holds its axes and its origin as columns", () => {
  const m = frameMatrix(CAR);
  assert.ok(close([m[0][0], m[1][0]], [c30, 0.5]), 'the x axis (0.866, 0.5)');
  assert.ok(close([m[0][1], m[1][1]], [-0.5, c30]), 'the y axis (-0.5, 0.866)');
  assert.ok(close([m[0][2], m[1][2]], [10, 2]), 'the origin (10, 2)');
});

test('the rim point of the lesson, out to the world and back', () => {
  const world = toParent([CAR, WHEEL], [0.4, 0]);
  const expected = [10 + 1.5 * c30 + 0.1 * 0.5, 2 + 1.5 * 0.5 - 0.1 * c30];
  assert.ok(close(world, expected), `world point ${show(world)}, expected ${show(expected)}`);
  assert.ok(close(toParent([WHEEL], [0.4, 0]), [1.5, -0.1]), 'in the car frame: (1.5, -0.1)');
  const back = toInnermost([CAR, WHEEL], world);
  assert.ok(close(back, [0.4, 0]), `back in the wheel frame: ${show(back)}`);
});

test('one frame: the origin and the axes', () => {
  assert.ok(close(toParent([CAR], [0, 0]), [10, 2]), "the frame's own origin is its origin in the parent");
  assert.ok(close(toInnermost([CAR], [10, 2]), [0, 0]), 'and back');
  assert.ok(close(toInnermost([{ origin: [3, 4], degrees: 0 }], [5, 5]), [2, 1]), 'a frame that is only moved');
});

test('200 seeded chains of frames go out and back', () => {
  let seed = 5; // mulberry32, so every run tests the same chains
  const random = () => {
    seed = (seed + 0x6d2b79f5) | 0;
    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
  for (let n = 0; n < 200; n++) {
    const frames = Array.from({ length: 1 + Math.floor(random() * 4) }, () => ({ origin: [random() * 40 - 20, random() * 40 - 20], degrees: random() * 360 - 180 }));
    const p = [random() * 10 - 5, random() * 10 - 5];
    const q = toParent(frames, p);
    // Applying the frames one at a time, innermost first, must agree with toParent.
    let r = p;
    for (let i = frames.length - 1; i >= 0; i--) {
      const m = frameMatrix(frames[i]);
      r = [m[0][0] * r[0] + m[0][1] * r[1] + m[0][2], m[1][0] * r[0] + m[1][1] * r[1] + m[1][2]];
    }
    assert.ok(close(q, r), `chain ${n + 1}: innermost frame first`);
    assert.ok(close(toInnermost(frames, q), p), `chain ${n + 1}: out and back`);
  }
});

Finish with the self-check on windows, fits, frames, NDC and canvas sizes. Its first questions come from whichever of them your answers show you know least, and a missed one is asked again:

Interview questions

Warm-up (fresher to 2-5 years): What does the window-to-viewport transformation do, and what is its formula?

It maps a rectangle of the world, the window, onto a rectangle of the screen, the viewport, with one scale and one shift per axis: x_v = v_x + (x − x_min) s_x, where s_x is the viewport’s width divided by the window’s, and the same for y, measured down from the window’s top edge when screen rows are counted downwards. For a window from (−2, −1) to (2, 1) on a 400 × 200 viewport both scales are 100 pixels a unit, and (1, 0.5) lands at (300, 50). When the two scales differ, shapes are stretched; using the smaller scale for both axes letterboxes the picture and the larger crops it. As a matrix the map is a scale and a translation, and a GPU’s viewport transform is the same map with the window fixed at −1 to 1.

Two questions of this module build on it, one about a canvas on a phone and one about a map view that resizes. Each row leads to the question’s first move and the follow-ups to expect:

Key takeaways

• The window-to-viewport map is one scale and one shift per axis, with y measured from the window’s top edge because screens count rows downwards: (1, 0.5) lands at (300, 50) on the 400 × 200 viewport.
• When the window and the viewport differ in shape, separate scales distort it; one scale for both axes keeps shapes true, the smaller with bars (letterbox) and the larger with cut-off edges (crop).
• A frame’s matrix has the frame’s axes and origin, in its parent’s coordinates, as columns; parent times child takes a point out to the world, and the inverses in the opposite order bring it back.
• WebGPU’s viewport maps NDC, from −1 to 1 with y up, to framebuffer pixels with y down, and depth from 0…1 into minDepth…maxDepth: the same map with a fixed window.
• A canvas bitmap needs one pixel per device pixel, its CSS size times devicePixelRatio, and clicks must be scaled from CSS pixels to bitmap pixels before the inverse map: a 400 × 200 box needs an 800 × 400 bitmap at ratio 2.