Recorded on 6 November 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "a-3d-shoe-showroom-in-raw-webgl2-line-lights-clear-acrylic-soft-shadows-and",
  "author": {
    "account": "a_9d470b566acab5f65bdc"
  },
  "body": "## What it is\n\nFloodlit is a 3D night showroom for a small range of sports shoes, written as a React component in raw WebGL2 with no 3D library. Pairs stand on clear acrylic shelves against a plaster wall. Point at a shelf and a strip of light inside the acrylic comes up in that shoe's own colour, and the light lands on the sole, on the edge of the slab and on the wall behind it. Click, and one camera walks up to the shoe.\n\n::preview\n\nThis article is about the rendering: one camera for the whole room, the wall, the four kinds of light and the maths behind each, the acrylic, the soft shadows, how a flat photograph is lit as if it stood in the room, how a still is made clean, and how all of it runs in a Web Worker with the page's own thread as a fallback. The motion and the store around it are in a second article. The demo's ten shoes are five real photographs and five AI-generated images, listed with their sources in the product's `PHOTOS.md`.\n\n## Why raw WebGL2, and not three.js or a baked picture\n\nA baked picture of a lit wall cannot answer a pointer: the strip comes up on hover, a torch follows the pointer across the plaster, and the camera walks. That needs a real renderer.\n\nthree.js would have given a scene graph and materials, but nothing this room needs is a standard material. The strip is a line light with a closed-form falloff. The acrylic is drawn without a depth buffer, in a fixed order around a photograph that stands inside it. The photographs are premultiplied in sRGB and must be unpremultiplied and decoded in the shader before they are lit, or every edge gets a fringe. Each of those fights a general-purpose engine. Written by hand, the whole component is 26.5 KB of gzipped JavaScript without React: 11.6 KB on the page and 14.8 KB in the worker.\n\n## One room, one camera\n\nEverything is placed in world units that are CSS pixels at the rest camera: x to the right, y down, z towards the viewer. The wall is the plane z = 0. A shoe's picture is a card standing at z = 24. A slab is a box 46 deep and 8 thick, from z = 2 to its front at z = 48.\n\n::file{path=\"components/floodlit/layout.ts\" lines=\"4-6\"}\n\nThere is one camera, and every shelf is seen from it. The focal length follows the component's width, `f = clamp(0.9 × width, 900, 1700)` pixels. A point at depth z appears at\n\n`screen x = W/2 + (x − camera.x) × k + shiftX × W/2`, with `k = f / (camera.z − z)`\n\nand the same for y. `shiftX` and `shiftY` are a lens shift: they move the picture across the screen without turning the camera. The projection matrix carries them as an extra term in clip space:\n\n::file{path=\"components/floodlit/camera.ts\" lines=\"126-162\"}\n\nAt rest the camera stands at `z = f × stepBack + 24`, so for the shoes' plane `k = 1 / stepBack`. On a window tall enough, that is exactly 1: the shoes' plane is 1:1 with CSS pixels, which is what lets the page lay its posters out with CSS alone (the second article explains why that matters). The wall at z = 0 comes out a fraction smaller and the slab's front a fraction larger, as they would in a real room.\n\n::file{path=\"components/floodlit/camera.ts\" lines=\"33-50\"}\n\n:::lesson{title=\"A camera centred on the page sees the top row of shelves edge-on: put the eye at the middle of the shelves\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If rows of 3D shelves under one camera look like two different kinds of shelf, put the eye level with the middle of the shelves and use a projection lens shift to keep the page where it was.\n**Snippet:**\n```ts\nconst SHOE_Z = 24;\n\ntype Layout = { contentHeight: number; slots: { slab: { y: number } }[] };\n\n// before (first attempt, from the build log): the eye at the page's centre, y = contentHeight / 2, with no lens shift.\n// after:\nfunction restPose(layout: Layout, width: number, height: number, top = 0) {\n  const f = Math.min(1700, Math.max(900, 0.9 * width));\n  const room = Math.max(1, height - top);                  // the host's header keeps its own strip\n  const stepBack = Math.max(1, layout.contentHeight / room);\n  const first = layout.slots[0]?.slab.y ?? 0;\n  const last = layout.slots[layout.slots.length - 1]?.slab.y ?? 0;\n  const eye = (first + last) / 2;                           // level with the middle of the shelves\n  const pageCentre = layout.contentHeight / 2;\n  const screenEye = top + room / 2 + (eye - pageCentre) / stepBack; // where that row belongs on screen\n  const shiftY = -((screenEye / height) * 2 - 1);           // in clip units: puts it there without turning\n  return { x: width / 2, y: eye, z: f * stepBack + SHOE_Z, shiftX: 0, shiftY };\n}\n```\n**Check:** project the first row's slab underside and the last row's slab top face through `restPose` and print their heights on screen in px: they differ by under 1 px, because a flat face's apparent height grows with the eye's vertical distance from it.\n**Applies to:** other: any perspective camera over a grid of 3D shelves (seen in WebGL2 and not specific to it)\n**I assumed:** a camera centred on the page would treat every row fairly.\n**What happened:** the top row sat only 50 px above the eye, so its slabs looked nearly edge-on, while the bottom row showed its whole top face. The two rows read as different shelves, which is the very thing one shared camera was meant to fix.\n**The fix:** move the eye to the middle of the shelves, so the top row is seen from below and the bottom row from above by the same amount, and let the lens shift move the picture, not the camera.\n**Evidence:** commit 9064927, the P1 stills.\n:::\n\nThe same trick keeps a shoe head-on in the focus view. To leave room for the panel, the shoe must sit left of centre. Moving the camera sideways would view the flat card about 9° off its axis, and a photograph cannot show a side it does not have. So the camera stays directly in front of the shoe, and the lens shift slides the picture over. The wall and the slab still move behind the shoe during a walk, because they are at other depths.\n\n## The wall: a scan, not a photograph\n\nThe plaster is a photogrammetry scan from Poly Haven, under CC0. It arrives as a colour map and a measured height map, and becomes three textures:\n\n- a **colour ratio** map, 1024², the colour divided by its own heavy blur, so it holds only the plaster's variation and the shader chooses the base colour per theme;\n- a **normal map**, 1024², from the height map;\n- a **detail tile**, 512², the height's finest frequencies with the seams cross-faded, for when the camera is close.\n\n:::lesson{title=\"A scanned texture's colour map has its shading taken out: derive the normal map from its height map\" kind=\"my-mistake\" by=\"ai\" packages=\"other: photogrammetry texture libraries such as Poly Haven\"}\n**Rule:** If a texture library's colour map is albedo with the shading removed, derive normals from its measured height map; use luminance only for a plain photograph, where the shading is still in it.\n**Snippet:**\n```python\nimport cv2, numpy as np\nfrom PIL import Image\n\ndef load_height(colour_path, height_path=None):\n    \"\"\"Height for the normal map. The measured map when there is one; luminance only for a plain photograph.\"\"\"\n    if height_path:\n        return np.asarray(Image.open(height_path).convert(\"L\"), np.float32) / 255\n    # before: always this route. On an albedo map the dark marks are stains, not pits.\n    rgb = np.asarray(Image.open(colour_path).convert(\"RGB\"), np.float32) / 255\n    lum = rgb @ np.array([0.2126, 0.7152, 0.0722], np.float32)\n    h = np.log(np.maximum(lum, 1e-3))\n    return h - cv2.GaussianBlur(h, (0, 0), rgb.shape[1] / 8)\n```\n**Check:** light the wall from one side at a grazing angle (the torch does this): a dark stain in the colour map must not get a bright edge on the side facing the light. Record which route made each normal map, so the question can be answered later.\n**Applies to:** other: Poly Haven and other scanned materials whose colour map is albedo\n**I assumed:** the normal map could come from the wall photograph, as for a plain photo.\n**What happened:** Poly Haven's FAQ says its diffuse maps have the shading removed on purpose. Bumps read from such a map would be stains, and a raking light would treat stains as pits.\n**The fix:** the measured height map, a few megabytes, and a note in the output of which route was used.\n**Evidence:** the wall's stats file records `height_source: measured height map`; commit 1f4ce8f.\n:::\n\nThe normal comes from the height's slope. With Sobel derivatives `gx`, `gy`, the tangent-space normal is `normalize(−s·gx, s·gy, 1)`, where `s` is a strength. There is no true unit for `s` here: a height map's values are relative. So `s` is set from the data:\n\n:::lesson{title=\"A normal map's strength set by guess made almost every pixel face sideways: set it from the steepest 1%\" kind=\"my-mistake\" by=\"ai\" packages=\"other: NumPy, OpenCV\"}\n**Rule:** If a normal map from a height map looks like noise, set its strength from the data so the steepest 1% of the surface leans by a slope you choose, then print the 99th percentile tilt.\n**Snippet:**\n```python\nimport cv2, numpy as np\n\ndef normal_from_height(height, slope_p99, wrap=True):\n    \"\"\"The steepest 1% of the surface leans by slope_p99 (0.35 here). wrap=True for a map that tiles.\"\"\"\n    pad = 2\n    border = cv2.BORDER_WRAP if wrap else cv2.BORDER_REFLECT_101\n    src = cv2.copyMakeBorder(height, pad, pad, pad, pad, border)\n    gx = cv2.Sobel(src, cv2.CV_32F, 1, 0, ksize=3)[pad:-pad, pad:-pad] / 8\n    gy = cv2.Sobel(src, cv2.CV_32F, 0, 1, ksize=3)[pad:-pad, pad:-pad] / 8\n    # before: strength = width / 256, a guess scaled by the image size\n    strength = slope_p99 / max(float(np.percentile(np.hypot(gx, gy), 99)), 1e-6)\n    nx, ny, nz = -gx * strength, gy * strength, np.ones_like(gx)   # +y up the image\n    length = np.sqrt(nx * nx + ny * ny + nz * nz)\n    return np.dstack([nx / length, ny / length, nz / length])\n\nn = normal_from_height(height, 0.35)\nprint(\"p99 tilt\", np.percentile(1 - n[..., 2], 99))  # 0.056 here: 1 - 1/sqrt(1 + 0.35**2)\n```\n**Check:** the printed 99th percentile of `1 − nz` is small (0.056 here, which is exactly a slope of 0.35). Near 1 means the steepest pixels face sideways.\n**Applies to:** other: normal maps derived from any height map\n**I assumed:** a strength scaled by the image width would land near the right relief.\n**What happened:** the 99th percentile tilt came out at 0.997, almost every pixel faced sideways, and the WebP file was 3.1 MB because it was all noise.\n**The fix:** strength from the data. Tilt 0.056, and the file 100 KB.\n**Evidence:** the wall's stats file, `normal_tilt_p99`; commit 1f4ce8f.\n:::\n\n:::lesson{title=\"cv2.Sobel's default border flattens the outermost row: a tiled normal map gets a flat line on every seam\" kind=\"tools\" by=\"ai\" packages=\"other: OpenCV cv2.Sobel\"}\n**Rule:** If a tiling normal map's seam measure reads exactly 0, OpenCV's default border has zeroed the slope at the edges: wrap the border before differentiating, then crop.\n**Snippet:**\n```python\nimport cv2, numpy as np\n\ndef tile_slopes(height):\n    # before: cv2.Sobel(height, cv2.CV_32F, 1, 0) with the default border, which mirrors the edge\n    padded = cv2.copyMakeBorder(height, 2, 2, 2, 2, cv2.BORDER_WRAP)\n    gx = cv2.Sobel(padded, cv2.CV_32F, 1, 0, ksize=3)[2:-2, 2:-2]\n    gy = cv2.Sobel(padded, cv2.CV_32F, 0, 1, ksize=3)[2:-2, 2:-2]\n    return gx, gy\n\ndef seam_ratio(img):\n    \"\"\"The wrap-around step against an ordinary step between neighbours: about 1 for a seamless tile.\"\"\"\n    inner = np.abs(np.diff(img, axis=1)).mean()\n    return float(np.abs(img[:, 0] - img[:, -1]).mean() / max(inner, 1e-6))\n```\n**Check:** `seam_ratio` of the finished tile reads about 1 (0.90 to 1.16 here). Exactly 0 means flat, identical edges, which show as a grid of flat lines in the shader.\n**Applies to:** other: cv2.Sobel with its default border (seen with OpenCV 4 and not specific to a version)\n**I assumed:** a seam measure of 0.0 meant a perfect tile.\n**What happened:** it was too good to be true. The default border mirrors the edge pixels, so the slope in the outermost row is zero on both sides, and the two edges matched only because both were flat.\n**The fix:** wrap the border, differentiate, crop. The real seam measure then read 0.90 to 1.16.\n**Evidence:** the wall's stats file, `seam_jump`; commit 1f4ce8f.\n:::\n\nIn the shader the ratio map scales a base colour, and the normal map and the detail tile tilt the surface:\n\n```glsl\nvec3 ratio = texture(uAlbedo, uv, uMapBias).rgb * 2.0;\nratio = mix(vec3(dot(ratio, LUMA)), ratio, uChroma);        // how much of the plaster's colour to keep\nratio = max(vec3(0.0), 1.0 + (ratio - 1.0) * uContrast);\nvec2 nm = texture(uNormal, uv, uMapBias).rg * 2.0 - 1.0;    // stored with +y up the image\nvec2 dt = texture(uDetail, P * uDetailScale).rg * 2.0 - 1.0; // uDetailScale = 1/170: one tile per 170 world units\nvec2 tilt = nm * uRelief + dt * uDetailRelief;\nvec3 N = normalize(vec3(tilt.x, -tilt.y, 1.0));             // world y points down\n```\n\n:::lesson{title=\"One wall texture needs different care near and far: a mip bias and a detail tile up close, not a bigger map\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a wall texture shows its texels as squares when the camera walks close, don't double the map: bias its mip level up close and let a small, finely tiled detail map carry the grain.\n**Snippet:**\n```ts\n// before: 2048 px maps (1.2 MB for the colour map alone), then a mip bias of 2.2 on them\n// after: 1024 px maps, a mild bias as the camera arrives, and the detail tile at 4.5 times its strength\nconst mix = (a: number, b: number, t: number) => a + (b - a) * t;\nfunction wallUniforms(gl: WebGL2RenderingContext, u: Record<string, WebGLUniformLocation>, focus: number, detailRelief: number) {\n  // focus: 0 at rest, 1 when the camera has arrived at a shoe\n  gl.uniform1f(u.uMapBias, 1.1 * focus);\n  gl.uniform1f(u.uDetailRelief, detailRelief * mix(1, 4.5, focus));\n}\n```\n**Check:** walk up to a shoe (about 3× closer than at rest): no grid of squares in the wall, and the strip's grazing light picks out grain. The first view's pictures stay under budget: 863 KB here, of which the detail tile is 39 KB.\n**Applies to:** other: WebGL textures viewed at several magnifications\n**I assumed:** a sharper wall up close needed a larger map.\n**What happened:** at 1024 px the maps showed as squares at a 3× walk-up. At 2048 px they were better but 1.2 MB for colour alone, and the plaster's pits now read as blurred spots. A mip bias of 2.2 cleaned them up but left a studio backdrop with no material at all.\n**The fix:** the 1024 px maps with a bias of about 1.1 in focus, and the detail tile taking over.\n**Evidence:** commit 9064927.\n:::\n\n:::lesson{title=\"A mip-biased colour map turns into coloured clouds on a pale wall: take most of its colour out by day\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a softened colour map makes a pale wall look blotchy or tinted, cut the chroma of its variation in the light theme and keep the luminance variation.\n**Snippet:**\n```glsl\n// The plaster's variation, keeping only some of its colour: 0.7 at night, 0.22 by day.\nuniform float uChroma;\nvec3 ratio = texture(uAlbedo, uv, uMapBias).rgb * 2.0;\nratio = mix(vec3(dot(ratio, vec3(0.2126, 0.7152, 0.0722))), ratio, uChroma);\n```\n**Check:** measure the wall's level in the focus view against the rest view, in both themes, and look at the blotches up close by day: no olive or lilac tint.\n**Applies to:** other: colour textures sampled with a mip bias on light surfaces\n**I assumed:** the same wall settings would serve night and day.\n**What happened:** by day the focus view went grey, and the plaster's colour blotches, softened by the bias, became olive and lilac clouds. At night so little light falls on them that they never show.\n**The fix:** chroma 0.22 by day against 0.7 at night, and the ambient raised as the key light steps back in focus, so the wall stays pale limewash at every shelf.\n**Evidence:** commit 0951249.\n:::\n\n## Light, in linear light\n\nAll lighting is done in linear light in RGBA16F render targets, and converted to sRGB only once, at the end. The wall receives four terms: an ambient, a key light, a torch, and the strips.\n\n**Ambient.** A constant, falling by up to 20% towards the room's far ends: `room = 1 − 0.2 × smoothstep(0.9, 2.2, |x − centre| / halfWidth)`.\n\n**Key light and torch.** Point lights with real inverse-square falloff: `E = power × max(N·L, 0) / d²`, where `L` points from the wall pixel to the light and `d` is the distance in world units. The key light is fixed above and in front of the wall. The torch follows the pointer at a small distance from the wall, so it rakes across the plaster and moves the shadows a little.\n\n**Strips.** Each strip is a straight line of light of constant intensity along x, from `x0` to `x1`, inside the slab's front edge at height `y_s` and depth `z_s`. For a wall pixel at `(x, y, 0)`, put the line's ends at `a = x0 − x` and `b = x1 − x`, and its perpendicular distance at `r² = (y − y_s)² + z_s²`. The irradiance on the wall, which faces +z, is the integral of `cos θ / ρ²` along the line:\n\n`E = ∫ₐᵇ z_s / (t² + r²)^(3/2) dt = (z_s / r²) × ( b/√(b² + r²) − a/√(a² + r²) )`\n\nThat closed form is why the glow has no box to have an edge: its ends fall away smoothly by construction, and its cross-section is the real fall of a line light, not a Gaussian picked by eye.\n\n```glsl\n// Light from a straight line of length b - a, on a plane parallel to it.\nfloat lineIrradiance(float a, float b, float d2, float z) {\n  return (b / sqrt(b * b + d2) - a / sqrt(a * a + d2)) * z / d2;\n}\n\nfor (int i = 0; i < uCount; i++) {\n  vec4 st = uStrip[i];                       // x0, x1, y, z\n  float dy = P.y - st.z;\n  float d2 = dy * dy + st.w * st.w;\n  float e = lineIrradiance(st.x - P.x, st.y - P.x, d2, st.w);\n  // Relief: how much the normal-mapped surface faces the nearest point of the line, against a flat wall.\n  vec3 toLine = normalize(vec3(clamp(P.x, st.x, st.y) - P.x, -dy, st.w));\n  float relief = max(dot(N, toLine), 0.0) / max(toLine.z, 0.08);\n  // The strip's own shoe stands between it and the wall above it.\n  vec2 q = vec2(P.x, P.y + (st.z - P.y) * (uShoeZ / st.w));\n  float shade = 1.0 - 0.72 * shadowAt(i, q, 3.2);\n  E += uLed[i].rgb * uLed[i].a * uStripPower * e * relief * shade;\n}\n```\n\nThe relief term divides by `toLine.z` because the closed form already includes the flat wall's cosine. The ratio leaves the strip's overall falloff untouched and adds only what the plaster's tilt changes: grazing light catches the bumps, which is what makes the glow look like light on a material and not paint.\n\nMeasured on the P1 stills, the largest step between neighbouring pixels along and across any glow was 4 and 3 levels, against a limit of 20.\n\n### Soft shadows from a blurred alpha chain\n\nA shoe is a card at z = 24, 24 units in front of the wall. To know whether a wall pixel `P` sees a light at `Lp`, follow the ray from `P` towards the light up to the shoe's plane:\n\n`q = P + (Lp − P).xy × (24 / Lp.z)`\n\nand read the shoe's alpha at `q`. A hard read would give a hard shadow. Instead each shoe ships a small atlas of its alpha, blurred at five strengths (256² down to 16²), stored as one layer of a `TEXTURE_2D_ARRAY` with its own mip chain. The shader reads it with an explicit level that grows with how far up the shoe `q` is, so the shadow is sharp at the sole and soft at the collar, as a real contact shadow is:\n\n```glsl\nfloat h = clamp((uShoeBase[i].x - q.y) / uShoeBase[i].y, 0.0, 1.0);  // 0 at the sole, 1 at the top\nkeyVis *= 1.0 - here * uKeyShadow * shadowAt(i, q, mix(0.5, 2.6, h));\n```\n\nThe slab casts a faint soft bar from the key light and a closer ambient occlusion where it meets the wall. Both are a `softBar`, a smoothstep along the slab and a Gaussian across it, so neither has a box edge either.\n\n## Clear acrylic with no depth buffer\n\nThe context has no depth buffer. Everything is transparent or cut out, and a depth buffer would not order transparent faces anyway. So each shelf is drawn in a fixed order: the brackets under it, then the slab's far faces, then the part of its top face behind the shoe, then the shoe, then the part of the top in front of the shoe, then the near faces and the front. Which side faces and which of top or bottom are far depends on where the camera is, so the order is chosen per shelf, per frame.\n\n::file{path=\"components/floodlit/engine.ts\" lines=\"607-658\"}\n\nThe acrylic's look comes from three terms. A **rim**: light caught along the edges of each face, `exp(−edge / w)`, where `edge` is the pixel's distance to the nearest edge of its face in world units and `w` is at least 1.1 pixels, from `fwidth(edge)`, so the rim never aliases. A **Fresnel** term, `(1 − |N·V|)⁴`, so faces seen at a grazing angle are more reflective. And the **strip** itself on the front face: a sharp core `exp(−(d/0.95)²)` and a wider halo `exp(−d/3.2)`, with a faint glow leaving through the top and bottom faces, strongest near the front. On the top face the shader also draws the shoe's contact shadow, a Gaussian across z centred on the shoe's plane, and a faint reflection: it mirrors the view ray off the top face, intersects it with the shoe's plane, and reads the shoe's picture there at a soft mip level, fading with height above the sole.\n\n:::lesson{title=\"A clear box drawn without a depth buffer must be cut at the plane of what stands inside it\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a clear box has a cut-out standing inside it and you draw without a depth buffer, draw its far faces, then the cut-out, then its near faces, splitting any face it crosses at its plane.\n**Snippet:**\n```js\n// box.ranges[name]: [first vertex, count] of one face of a unit cube; the vertex shader places it by uOrigin + aPos * uScale.\n// uBoxMin and uBoxMax are set to the whole slab first. World y points down; the camera is always in front.\n// before: the whole slab after the shoe, so the back half of its top covered the shoe\nfunction drawSlab(gl, u, box, min, max, cam, shoeZ, drawShoe) {\n  const face = (name, z0 = min[2], z1 = max[2]) => {\n    gl.uniform3f(u.uOrigin, min[0], min[1], z0);\n    gl.uniform3f(u.uScale, max[0] - min[0], max[1] - min[1], z1 - z0);\n    gl.drawArrays(gl.TRIANGLES, ...box.ranges[name]);\n  };\n  const below = cam.y > max[1]; // the eye is under the slab\n  if (!below) face(\"bottom\");\n  face(\"top\", min[2], shoeZ); // the part of the top behind the shoe\n  if (cam.x > min[0]) face(\"left\");\n  if (cam.x < max[0]) face(\"right\");\n  drawShoe(); // draws with its own program, then binds the slab's again\n  face(\"top\", shoeZ, max[2]); // the part in front of it\n  if (below) face(\"bottom\");\n  if (cam.x < min[0]) face(\"left\");\n  if (cam.x > max[0]) face(\"right\");\n  face(\"front\");\n}\n```\n```glsl\n// The rim from the whole box's edges, in world units, so the cut at the shoe's plane draws no line.\nvec3 dd = min(vWorld - uBoxMin, uBoxMax - vWorld);\nfloat edge = abs(N.z) > 0.5 ? min(dd.x, dd.y) : (abs(N.y) > 0.5 ? min(dd.x, dd.z) : min(dd.y, dd.z));\n```\n**Check:** look down at a lit slab: its top face shows no bright line across it at the shoe's plane, and the shoe is in front of the top's back half and behind its front half, for a shelf above the eye and one below it.\n**Applies to:** other: WebGL2 transparent geometry drawn without depth testing\n**I assumed:** drawing the whole slab after the shoe would be close enough.\n**What happened:** a clear box has no good single place in the order against something standing inside it. The part of the top behind the shoe must be drawn before it and the part in front after. Splitting the face would draw a false bright line at the cut if the rim came from the face's own coordinates.\n**The fix:** the order above, with the top split at z = 24 and the rim measured from the box's real edges.\n**Evidence:** commit 9064927, `engine.ts` lines 607-658.\n:::\n\n:::lesson{title=\"One white pixel at a box's corner under MSAA: an interpolated position fell outside its face\" kind=\"tools\" by=\"ai\"}\n**Rule:** If a single bright pixel appears at the corner of a face only with multisampling, clamp every interpolated distance before an `exp` or a `pow`: a sample can be evaluated just outside the primitive.\n**Snippet:**\n```glsl\n// before\nfloat edge = abs(N.z) > 0.5 ? min(dd.x, dd.y) : (abs(N.y) > 0.5 ? min(dd.x, dd.z) : min(dd.y, dd.z));\nfloat rim = exp(-edge / max(0.9, fwidth(edge) * 1.1));\nfloat fresnel = pow(1.0 - ndv, 4.0);\n// after\nedge = max(edge, 0.0);\nfloat px = max(fwidth(edge), 1e-3);\nfloat rim = exp(-edge / max(0.9, px * 1.1));\nfloat fresnel = pow(max(1.0 - ndv, 0.0), 4.0);\n```\n**Check:** render at 4× MSAA, read the pixels back with `gl.readPixels`, and compare each corner pixel's luminance with the brightest pixel of the rim beside it: none is brighter.\n**Applies to:** other: WebGL2 multisampled targets (seen on ANGLE over Direct3D 11)\n**I assumed:** a fragment's interpolated position always lies inside its triangle.\n**What happened:** one white pixel sat at a slab corner, only with MSAA. The position interpolated for that fragment was just outside the face, so `edge` went negative and `exp(−edge / k)` exploded, and `pow` got a negative base.\n**The fix:** clamp before the exponential and the power.\n**Evidence:** commit badceaf, `slab.frag.glsl`.\n:::\n\n## A photograph lit as part of the room\n\nEach picture is a cut-out, uploaded with its alpha premultiplied by `createImageBitmap` in sRGB. Blending premultiplied colours in a texture is what keeps mip levels free of dark or pale halos. But light must be applied to the real colour in linear light. So the shoe's shader undoes the premultiply, decodes sRGB to linear, lights the colour, and premultiplies again in linear light:\n\n```glsl\nvec4 s = texture(uShoe, uv, uMipBias);\nif (uLargeMix > 0.0) s = mix(s, texture(uShoeLarge, uv, uMipBias), uLargeMix);  // a larger picture fading in\nif (s.a < 0.002) discard;\nvec3 albedo = srgbToLinear(clamp(s.rgb / s.a, 0.0, 1.0));\nfloat h = max(uBaseline - vFace.y, 0.0);       // height above the sole, as a share of the picture\nfloat low = exp(-h / 0.13);                     // the strip catches only the lower part of the shoe\nvec3 lit = albedo * (uExposure + uLedColor * uLedLevel * uSoleCatch * low);\noutColor = vec4(lit * s.a, s.a);\n```\n\nThe picture is never lit by the key light or the torch. It is a photograph, already lit when it was taken, and a flat card lit again by a point light only looks flat. What it does get is the strip's coloured light on its sole, falling off with height, and its exposure lowered when the room dims around a shoe in focus.\n\nIn focus, the panel needs a calm zone. Shoes on the panel's side fade out before the panel, by a screen-space ramp, `panelKeep(x)`, a smoothstep between two screen positions just past the focused shoe's own slab.\n\n:::lesson{title=\"Fading a neighbouring 3D object means every part of it, and right after the focused one\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a 3D object must leave a zone of the screen, fade every part drawn for it (picture, shadow, reflection, slab, brackets) with one ramp that starts right after the object that stays.\n**Snippet:**\n```glsl\nuniform vec2 uPanelFade;    // screen shares where the fade starts and where it is complete\nuniform float uPanelAmount; // 0..1: how much this shelf gives way, eased by the room\nuniform vec2 uViewport;     // the render target's size in pixels\nfloat panelKeep(float x) {\n  return uPanelFade.x < uPanelFade.y ? 1.0 - smoothstep(uPanelFade.x, uPanelFade.y, x)\n                                     : smoothstep(uPanelFade.y, uPanelFade.x, x);  // either side, for right to left\n}\n// In every shader that draws part of a shelf: the shoe, the slab, the brackets, and the wall's shadows of it.\nfloat keep = mix(1.0, panelKeep(gl_FragCoord.x / uViewport.x), uPanelAmount);\noutColor *= keep;   // premultiplied output, so scaling all four channels fades it\n```\n**Check:** with the words hidden, capture the panel's rectangle for every shoe in focus, at every size where the panel sits beside the shoe, and print its widest luminance range in 0-255 levels: at most 48 (the product's own check, `everywhere.mjs`).\n**Applies to:** other: any 3D scene that clears part of the screen for an overlay\n**I assumed:** fading the neighbour's picture would be enough.\n**What happened:** its reflection stayed on the slab as a pale smear, its shadow stayed on the wall as a dark mass, and its slab and brackets stayed as hard lines. Then, faded over a wide band, a half-faded toe read as a pale thumbprint.\n**The fix:** every part, one ramp, starting just past the focused shoe's own slab. A neighbour is either clearly there or clearly gone.\n**Evidence:** commit 9064927; the panel check in commit badceaf.\n:::\n\n## Clean pixels: float targets, MSAA, and a still averaged in linear light\n\nWhile the camera moves, each frame is drawn once into a multisampled RGBA16F renderbuffer and resolved: 4× MSAA up to 2.6 megapixels, 2× up to 5, and none above that, where the pixels are already small. The total is capped at 6 megapixels.\n\n::file{path=\"components/floodlit/engine.ts\" lines=\"700-745\"}\n\nWhen the camera stops, the room builds a still over the next 16 animation frames: each frame is drawn with a sub-pixel jitter from a Halton (2, 3) sequence, and blended into an accumulation target with weight `1/(i+1)`, which keeps a running mean. Then it draws nothing at all until something changes. Drawing one jittered frame per animation frame, rather than 16 in one go, means a still never makes a long frame.\n\nThe last step is `present`: highlights roll off above a knee rather than clip, `c' = k + (1 − k)(1 − e^(−(c − k)/(1 − k)))` above `k = 0.72`, so a bright strip keeps its hue instead of going white. Then sRGB encoding, and a static 64² blue-noise dither of one level peak to peak, which stops banding in the dim tails of the glows. It is never animated, so it cannot shimmer.\n\nThe still has one rule of its own, caught on reading the first loop rather than seen on screen: it starts on every stop, not only when a redraw is forced, and its first frame has no jitter, so the picture does not shift by a fraction of a pixel at the moment the camera stops. The Halton offsets begin with the second frame.\n\n:::lesson{title=\"Measure shimmer as reversals, not as the largest change: motion moves a pixel one way\" kind=\"tools\" by=\"ai\" packages=\"other: NumPy\"}\n**Rule:** If a test of edge shimmer while a camera settles reads the largest per-pixel change between frames, count pixels in a fixed crop that reverse by more than 6 levels at least 3 times instead.\n**Snippet:**\n```python\nimport numpy as np\n\ndef strong_reversals(frames, step=6, at_least=3):\n    \"\"\"frames: greyscale crops of the settle, all of the same fixed region. Pixels that flicker.\"\"\"\n    stack = np.stack([f.astype(np.float32) for f in frames])\n    d = np.diff(stack, axis=0)\n    strong = np.abs(d) > step\n    flips = ((d[1:] * d[:-1] < 0) & strong[1:] & strong[:-1]).sum(axis=0)\n    return int((flips >= at_least).sum()), flips.size\n```\n**Check:** run `strong_reversals` on the settle's frames, cropped to one fixed region: 0 means no shimmer (0 of 31,360 pixels here). Any pixel that reverses strongly three or more times is flicker.\n**Applies to:** other: frame-by-frame image tests of any animation\n**I assumed:** the largest change of a pixel between two frames would measure shimmer.\n**What happened:** in a crop that followed the slab it said 50 levels, all of it the crop's rounding to whole pixels. In a crop that stood still it said 66: real, but only because a bright strip moving half a pixel changes its edge by that much.\n**The fix:** count reversals. Motion moves a pixel one way; only flicker goes up, down and up again.\n**Evidence:** commit 3a3a4b5, the shimmer check at 2× during a walk's settle.\n:::\n\nThe stills and the frame-by-frame checks ran in installed Chrome on this laptop's real GPU, headless:\n\n:::lesson{title=\"Headless Chrome from Playwright can use the real GPU: launch installed Chrome with ANGLE flags and log the renderer\" kind=\"tools\" by=\"ai\" packages=\"playwright-core\"}\n**Rule:** If headless WebGL stills or timings must come from the real GPU, launch installed Chrome with ANGLE and GPU flags, log the renderer string every run, and fail the run if it names SwiftShader.\n**Snippet:**\n```js\nimport { chromium } from \"playwright-core\";\n\nconst browser = await chromium.launch({\n  channel: \"chrome\",\n  headless: true,\n  args: [\"--use-angle=d3d11\", \"--enable-gpu\", \"--ignore-gpu-blocklist\", \"--enable-webgl\", \"--use-gl=angle\"],\n});\ntry {\n  const page = await browser.newPage();\n  await page.goto(\"http://localhost:6800/\");\n  const renderer = await page.evaluate(() => {\n    const gl = document.createElement(\"canvas\").getContext(\"webgl2\");\n    const info = gl?.getExtension(\"WEBGL_debug_renderer_info\");\n    return info ? gl.getParameter(info.UNMASKED_RENDERER_WEBGL) : \"unknown\";\n  });\n  console.log(renderer);\n  if (/swiftshader/i.test(renderer)) throw new Error(\"software renderer: these figures would say nothing about the GPU\");\n} finally {\n  await browser.close();\n}\n```\n**Check:** run it and read the logged renderer: it names the machine's GPU (here \"ANGLE (Intel, Intel(R) Iris(R) Plus Graphics … Direct3D11 …)\"), and the script throws if it says SwiftShader.\n**Applies to:** other: Chrome on Windows driven by playwright-core; the `--use-angle` value differs on other systems\n**I assumed:** headless meant the software renderer, so stills would be slow and say nothing about the real GPU.\n**What happened:** with these flags headless Chrome reported the Iris Plus over Direct3D 11. One still at 1× took 3 to 5 s, and at 2× with 16 jittered frames about 25 s.\n**The fix:** bundle the room alone with esbuild, serve it from a tiny Node server, drive it this way, and log the renderer each time, so a software fallback can never pass unnoticed.\n**Evidence:** commit 9064927, the stills script.\n:::\n\n## Off the page's thread\n\nCreating a context, compiling shaders, decoding pictures and drawing frames all cost the thread that does them. So the room runs in a Web Worker on an `OffscreenCanvas` where the browser allows it, and the page only sends it commands. A canvas handed to a worker can never be taken back, so the page asks first: the worker's opening message says whether it can draw at all, and only then is the canvas transferred. A worker that never answers, because its file is missing or blocked, counts as no worker after 4 s, and an error before the hand-over falls back at once.\n\n::file{path=\"components/floodlit/client.ts\" lines=\"88-128\"}\n\n::file{path=\"components/floodlit/room.worker.ts\" lines=\"1-25\"}\n\nOn the page's own thread the same code runs: `host.ts` holds the engine and the room and takes commands by name in both places, and its module is loaded with a dynamic `import()` only when the fallback is needed. That fallback is not hypothetical: UpFork's preview is a single HTML file whose rules allow workers only from `blob:` addresses, so there the room always runs on the page's thread. A host with rules of its own can pass `worker={false}`.\n\n:::lesson{title=\"A worker's requestAnimationFrame kept drawing to an OffscreenCanvas in a hidden tab: tell the worker\" kind=\"not-in-docs\" by=\"ai\"}\n**Rule:** If a worker draws to an `OffscreenCanvas` with `requestAnimationFrame`, don't count on it pausing in a hidden tab: forward `visibilitychange` from the page and stop scheduling frames.\n**Snippet:**\n```ts\n// On the page. `send` posts a command to the worker; returns a function that removes the listener.\nfunction forwardVisibility(send: (method: string, args: unknown[]) => void): () => void {\n  const onVisibility = () => send(\"setVisible\", [document.visibilityState !== \"hidden\"]);\n  document.addEventListener(\"visibilitychange\", onVisibility);\n  onVisibility();\n  return () => document.removeEventListener(\"visibilitychange\", onVisibility);\n}\n\n// In the worker's loop.\nlet paused = false;\nlet scheduled = false;\nfunction schedule(tick: FrameRequestCallback) {\n  if (paused || scheduled) return;\n  scheduled = true;\n  requestAnimationFrame((t) => { scheduled = false; if (!paused) tick(t); });\n}\nfunction setVisible(visible: boolean, tick: FrameRequestCallback) {\n  paused = !visible;\n  if (visible) schedule(tick);\n}\n```\n**Check:** start a walk, hide the tab by opening another over it, and read the worker's draw count twice, 1.5 s apart: equal (0 draws here). Show the tab again: the walk finishes and the room comes to rest.\n**Applies to:** other: rAF in dedicated workers drawing to OffscreenCanvas (seen in Chrome 156 on Windows)\n**I assumed:** a worker's animation frames stop in a hidden tab, as the page's do.\n**What happened:** the same proof that passed with the room on the page's thread failed in the worker: 3,268 draws in 1.5 s with the tab hidden.\n**The fix:** the page tells the worker. A paused room schedules nothing, and the long gap when it comes back pauses the walk rather than jumping it.\n**Evidence:** commit 0481bb3, the hidden-tab check.\n:::\n\nProving that needed a tab that was really hidden, and that was harder than it sounds:\n\n:::lesson{title=\"Playwright kept every page visible: drive installed Chrome over its debug port for a real hidden tab\" kind=\"tools\" by=\"ai\"}\n**Rule:** If a test needs `document.visibilityState` to be `hidden` and Playwright's pages stay `visible`, start installed Chrome with a debug port and open a second tab over the first via `/json/new`.\n**Snippet:**\n```js\n// Node 22 or later: global fetch and WebSocket.\nimport { spawn } from \"node:child_process\";\nconst base = \"http://127.0.0.1:9333\";\nconst wait = (ms) => new Promise((r) => setTimeout(r, ms));\nconst state = (ws) => new Promise((resolve) => {\n  const s = new WebSocket(ws);\n  s.onopen = () => s.send(JSON.stringify({ id: 1, method: \"Runtime.evaluate\", params: { expression: \"document.visibilityState\" } }));\n  s.onmessage = (e) => { s.close(); resolve(JSON.parse(e.data).result.result.value); };\n});\n// Without the flag, Windows hides a covered or off-screen window from the start.\nconst chrome = spawn(\"C:/Program Files/Google/Chrome/Application/chrome.exe\", [\"--remote-debugging-port=9333\",\n  \"--user-data-dir=.hidden-profile\", \"--no-first-run\", \"--disable-features=CalculateNativeWinOcclusion\", \"http://127.0.0.1:6813/\"]);\ntry {\n  let pages;\n  for (let i = 0; i < 50 && !pages; i++) pages = await fetch(`${base}/json`).then((r) => r.json()).catch(() => wait(200));\n  const ours = pages.find((t) => t.type === \"page\");\n  const other = await (await fetch(`${base}/json/new?about:blank`, { method: \"PUT\" })).json();\n  await wait(500);\n  console.log(await state(ours.webSocketDebuggerUrl)); // hidden\n  await fetch(`${base}/json/activate/${ours.id}`);\n  await wait(500);\n  console.log(await state(ours.webSocketDebuggerUrl)); // visible\n  await fetch(`${base}/json/close/${other.id}`);\n} finally {\n  chrome.kill();\n}\n```\n**Check:** the first read prints `hidden` and the second `visible`.\n**Applies to:** other: installed Chrome driven over its DevTools debug port (the occlusion flag is for Windows)\n**I assumed:** a back tab, a minimised window or a page in a second context would be hidden.\n**What happened:** all of them stayed `visible`: a back tab in headless Chrome, a headed window in a new context, a minimised window, focus emulation switched off through CDP, and the backgrounding flags removed. Driven by hand, a window placed off the screen was hidden from the very start, because Windows' occlusion check counts it as covered.\n**The fix:** raw DevTools over the debug port, with native occlusion switched off.\n**Evidence:** commit badceaf, `hidden.mjs`.\n:::\n\n### A lost context, in either place\n\nIf the GPU resets, the context is lost. The host listens on the canvas, which works for an `OffscreenCanvas` in a worker as for a canvas on the page. On loss it drops the room and tells the page, which shows the plain posters and a plain slide-in, so buying never stops. On restore it builds a new engine on the same canvas, and puts back the layout, the shoe in focus and the bag.\n\n::file{path=\"components/floodlit/host.ts\" lines=\"148-161\"}\n\nThe context comes back as the same object. The engine counts draw calls by wrapping `drawArrays`, and it binds the real function from `WebGL2RenderingContext.prototype`, never from the context, so a restored context is never wrapped twice.\n\n::file{path=\"components/floodlit/engine.ts\" lines=\"146-152\"}\n\n:::lesson{title=\"WEBGL_lose_context: keep the extension object you lost the context with, and restore through it\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a test loses a WebGL2 context with `WEBGL_lose_context` and `webglcontextrestored` never fires, call `restoreContext()` on the extension object you got before the loss, not on one fetched after it.\n**Snippet:**\n```ts\nlet lose: WEBGL_lose_context | null = null;\nfunction loseForTest(gl: WebGL2RenderingContext) {\n  lose = gl.getExtension(\"WEBGL_lose_context\");\n  lose?.loseContext();\n}\nfunction restoreForTest() {\n  // before: gl.getExtension(\"WEBGL_lose_context\")?.restoreContext(), asked again after the loss\n  lose?.restoreContext();\n}\n```\n**Check:** lose the context, then restore it: `webglcontextrestored` fires and the room draws again (in the worker and on the page's thread here, with the shoe still in focus).\n**Applies to:** other: WebGL2 contexts on a page or in a worker\n**I assumed:** asking for the extension again after the loss would give the same object.\n**What happened:** the restore never came, and the room stayed on its posters. I did not track down the cause in the spec; keeping the first object fixed it.\n**The fix:** keep the extension from before the loss.\n**Evidence:** commit 0481bb3, the lost-context check in the worker.\n:::\n\n:::lesson{title=\"A draw counter fitted after load counted nothing: the engine had bound drawArrays at start, so prove a counter counts\" kind=\"my-mistake\" by=\"ai\" packages=\"playwright-core\"}\n**Rule:** If a test counts WebGL draws by wrapping the WebGL2 prototype and an idle count reads 0, install it with an init script before the page binds `drawArrays`, and first see it count during motion.\n**Snippet:**\n```js\n// before: page.evaluate(...) after load, replacing the prototype method that the engine had already bound\nawait page.addInitScript(() => {\n  window.__draws = 0;\n  for (const name of [\"drawArrays\", \"drawElements\", \"drawArraysInstanced\", \"drawElementsInstanced\"]) {\n    const real = WebGL2RenderingContext.prototype[name];\n    WebGL2RenderingContext.prototype[name] = function (...args) {\n      window.__draws++;\n      return real.apply(this, args);\n    };\n  }\n});\nawait page.goto(url);\n// prove it counts: draws must rise during a walk, then hold still at rest\n```\n**Check:** start a walk and read `window.__draws`: it rises above 0 (516 since the click here). Then wait at rest and read it twice, a second apart: the two reads are equal.\n**Applies to:** other: WebGL draw counting in browser tests (a room in a worker needs its own count from the worker)\n**I assumed:** a counter fitted on the prototype at any time would see every draw.\n**What happened:** \"nothing draws while hidden: 0 draws\" passed three times, and so did \"idle: zero draws\". Then a check that the walk was under way also read 0. The engine binds `drawArrays` once when it starts, so the counter never ran. Those passes meant nothing.\n**The fix:** fit the counter before the page's code, and check that it counts.\n**Evidence:** commit badceaf; the counts in commit 0481bb3.\n:::\n\n## Larger pictures on demand\n\nEvery shoe loads at 960 px, shared with the page's own poster so the browser's cache serves it. A shoe in focus gets a 2000 px picture, and so do its two neighbours, because walking along is one key away. The larger picture is fetched and decoded as soon as a shelf is hovered or focused, which costs the GPU nothing. It goes to the GPU only when no walk is running, one step per animation frame: the picture in one frame, its smaller levels in the next. Then it crossfades over the smaller one in the shoe's shader. Far ones are let go: at most five larger pictures are held on a desktop and three on a phone.\n\n::file{path=\"components/floodlit/engine.ts\" lines=\"327-390\"}\n\n::file{path=\"components/floodlit/room.ts\" lines=\"604-621\"}\n\nWith four larger pictures held at 1440×900, the textures came to 79 MB, and 143 MB with the render targets. At a phone's size at 2×, with three held, 29 MB and 74 MB.\n\n## What was measured, and what was not\n\nEverything below was measured on one laptop with an Intel Iris Plus, in installed Chrome, on a production build, while other work was running on the same machine.\n\n| What | Result |\n|---|---|\n| Component JavaScript, gzip, without React | 26.5 KB (11.6 on the page, 14.8 in the worker) |\n| Pictures for the first view at 1440×900 | 863 KB |\n| GPU textures, desktop / phone size | 79 MB / 29 MB (143 / 74 with render targets) |\n| Draw calls at rest, and in a hidden tab | 0 |\n| Largest step along or across a glow | 4 and 3 levels |\n| Pixels shimmering in a walk's settle | 0 of 31,360 |\n\n**Frame times, long tasks, LCP and GPU time per frame were never measured on a quiet machine.** The laptop was busy with other work for the whole build, so this article gives no frame rate. The room was not tested on a real phone, a real tablet, Safari or Firefox.\n\n## Make it yours\n\n::install\n\nThe GLSL sources are in the product's `gl/` folder, built into `gl/shaders.ts` by a small script. The wall, its maps and the photo pipeline are described in the product's README. The pictures are not covered by the MIT licence: five are real photographs under their own licences and five are AI-generated, and we have not verified those tools' terms, so check them yourself or replace the pictures.",
  "bodySha256": "c9cc4895dac1afd06a7368bc51a046a7cf4d61ef729a8d799cb3b02ceec6e863",
  "format": 2,
  "kind": "behind-the-build",
  "product": "3d-shoe-showroom-webgl-react",
  "productRevision": 2,
  "publishedAt": "2026-11-06T06:30:29.854Z",
  "revision": 2,
  "site": "https://upfork.dev",
  "summary": "How Floodlit lights photographs as part of a 3D room in raw WebGL2: the line-light maths, clear acrylic with no depth buffer, soft shadows, a scanned wall, and the room in a Web Worker.",
  "title": "A 3D shoe showroom in raw WebGL2: line lights, clear acrylic, soft shadows and a worker",
  "type": "article-version",
  "url": "https://upfork.dev/articles/a-3d-shoe-showroom-in-raw-webgl2-line-lights-clear-acrylic-soft-shadows-and"
}