@solidrt/3d 0.0.46 → 0.0.48

package/examples/sweep-paths.tsx

@@ -0,0 +1,79 @@
+// Swept solids along 3D polylines. sweep() runs a 2D profile along a
+// path with mitred joints: bare path points crease - the strap folds
+// over the crate's edges like real webbing - while smooth-tagged points
+// share averaged normals, so the helix sweeps into ONE continuous coil
+// (per-segment boxes with unmitred gaps are exactly what this replaces).
+// tube() is the round-profile shorthand. Lit materials on purpose:
+// creased vs smooth joints differ only in normals, which unlit color
+// would hide.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, Group, Mesh, PerspectiveCamera, plane, roundRect, Scene, shaderMaterial, sweep, tube, unlit } from "@solidrt/3d"
+import type { SweepPath } from "@solidrt/3d"
+import { HEMISPHERE, LAMBERT, LIT_VERTEX } from "@solidrt/3d/glsl"
+
+const SIZE = 720
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 4000))
+
+  // One hemisphere + lambert look per color (a material instance is the
+  // pipeline handle, so each look is created once and shared).
+  let lit = (r: number, g: number, b: number) =>
+    shaderMaterial({
+      vertex: LIT_VERTEX,
+      fragment: `
+        in vec3 vNormal;
+        ${HEMISPHERE}
+        ${LAMBERT}
+        void main() {
+          vec3 n = normalize(vNormal);
+          vec3 l = normalize(vec3(0.5, 0.8, 0.4));
+          vec3 base = vec3(${r}, ${g}, ${b});
+          fragColor = vec4(base * (hemisphere(n, vec3(0.45), vec3(0.22)) + 0.8 * lambert(n, l)), 1.0);
+        }`,
+    })
+
+  // The strap hugs the crate at half its thickness; every bend is a bare
+  // (sharp) point, so each fold creases exactly on a crate edge.
+  let o = 0.013
+  let strapPath: SweepPath = [
+    [-1.75, o, 0],
+    [-1.3 - o, o, 0],
+    [-1.3 - o, 0.6 + o, 0],
+    [-0.3 + o, 0.6 + o, 0],
+    [-0.3 + o, o, 0],
+    [0.15, o, 0],
+  ]
+  let strap = sweep(roundRect(0.3, 0.026, 0.008), strapPath, "strap")
+
+  // A smooth-tagged helix: one continuous tube, not a stack of segments.
+  let coilPath: SweepPath = []
+  for (let i = 0; i <= 60; i++) {
+    let a = (i / 60) * Math.PI * 5
+    coilPath.push({ p: [0.85 + Math.cos(a) * 0.35, 0.055 + i * 0.0095, Math.sin(a) * 0.35], smooth: true })
+  }
+  let coil = tube(coilPath, 0.05, 12, "coil")
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="sweep-paths">
+          <PerspectiveCamera fov={55} position={[0, 1.9, 3.9]} lookAt={[0, 0.35, 0]} />
+          <Mesh
+            geometry={plane(6, 6, "floor")}
+            material={unlit({ color: [0.16, 0.17, 0.22] })}
+            rotation={[-Math.PI / 2, 0, 0]}
+          />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={box(1, 0.6, 0.8)} material={lit(0.55, 0.42, 0.28)} position={[-0.8, 0.3, 0]} />
+            <Mesh geometry={strap} material={lit(0.9, 0.55, 0.2)} />
+            <Mesh geometry={coil} material={lit(0.45, 0.6, 0.8)} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./math": "./src/math.ts"
+    "./math": "./src/math.ts",
+    "./glsl": "./src/glsl.ts"
   },
   "files": [
     "src/",
@@ -16,6 +17,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.31",
-    "@solidrt/core": "0.0.46"
+    "@solidrt/core": "0.0.48"
   }
 }

package/src/components.tsx

@@ -7,7 +7,7 @@
 // structure and slow state, per-frame motion goes straight to the scene.
 
 import { createContext, createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
-import type { ParentComponent, VoidComponent } from "@solidrt/core"
+import type { Element, ParentComponent, TextureId, VoidComponent } from "@solidrt/core"
 import {
   add,
   createGroup,
@@ -16,13 +16,15 @@ import {
   remove,
   setGeometry,
   setMaterial,
+  setMeshParams,
   setTransform,
   setVisible,
 } from "./scene.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
 import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode } from "./scene.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
-import type { Vec3 } from "./math.ts"
+import type { Quat, Vec3 } from "./math.ts"
 
 type SceneCtx = { scene: SceneHandle; parent: SceneNode }
 let SceneContext = createContext<SceneCtx>()
@@ -37,35 +39,49 @@ export function useScene(): SceneCtx {
 
 export type TransformProps = {
   position?: Vec3
-  /** Euler radians, applied x then y then z. */
+  /** Euler radians in XYZ order (x first), Three's `Euler` default. */
   rotation?: Vec3
+  /** The rotation as a quaternion - what the node stores. Pass this or
+   * `rotation`, not both. */
+  quaternion?: Quat
   scale?: Vec3 | number
   visible?: boolean
 }
 
 function syncNode(node: SceneNode, props: TransformProps): void {
   createEffect(
-    () => [props.position, props.rotation, props.scale, props.visible] as const,
-    ([position, rotation, scale, visible]) => {
-      setTransform(node, { position, rotation, scale })
+    () => [props.position, props.rotation, props.quaternion, props.scale, props.visible] as const,
+    ([position, rotation, quaternion, scale, visible]) => {
+      setTransform(node, { position, rotation, quaternion, scale })
       setVisible(node, visible !== false)
     },
   )
 }
 
 export type SceneProps = {
+  /** Target pixels. With `output`, the leaf's own width/height are layout,
+   * so render size and display size separate (supersampling). */
   width: number
   height: number
   clearColor?: [number, number, number, number]
   label?: string
   ref?: (scene: SceneHandle) => void
+  /**
+   * Compose the output yourself: called once (untracked) with the scene's
+   * texture id, and its return renders in place of the built-in `<texture>`
+   * leaf - a `<d-texture>`, a leaf carrying paint/pointer/layout props, or
+   * a post-effect chain (a shader target sampling the id; created in the
+   * callback it disposes with the Scene). Return null to render no leaf.
+   */
+  output?: (texture: TextureId) => Element
 }
 
 /**
  * Owns a draw target and composites it as an ordinary `<texture>` leaf, so
  * the output takes layout, transforms, blendMode, and pointer events like
- * any element. Children (Mesh/Group/PerspectiveCamera) render nothing
- * themselves - they populate the retained scene through context.
+ * any element - or hand `output` the texture id and compose it yourself.
+ * Children (Mesh/Group/PerspectiveCamera) render nothing themselves - they
+ * populate the retained scene through context.
  */
 export let Scene: ParentComponent<SceneProps> = props => {
   let scene = untrack(() =>
@@ -76,9 +92,14 @@ export let Scene: ParentComponent<SceneProps> = props => {
     ([w, h]) => scene.setSize(w, h),
   )
   untrack(() => props.ref)?.(scene)
+  let output = untrack(() => props.output)
   return (
     <SceneContext value={{ scene, parent: scene.root }}>
-      <texture src={scene.texture} width={props.width} height={props.height} />
+      {output ? (
+        untrack(() => output(scene.texture))
+      ) : (
+        <texture src={scene.texture} width={props.width} height={props.height} />
+      )}
       {props.children}
     </SceneContext>
   )
@@ -98,6 +119,12 @@ export let Group: ParentComponent<TransformProps & { ref?: (node: SceneNode) =>
 export type MeshProps = TransformProps & {
   geometry: Geometry
   material: Material
+  /** Per-mesh uniforms for a custom material (setMeshParams as a prop).
+   * Keys merge - a key that disappears keeps its old value; there is no
+   * unset. Names must be declared by the material's shaders. For values
+   * changing every frame prefer `ref` + setMeshParams from onFrame, the
+   * same split as setTransform. */
+  params?: ShaderParams
   ref?: (mesh: MeshNode) => void
 }
 
@@ -116,6 +143,12 @@ export let Mesh: VoidComponent<MeshProps> = props => {
     m => setMaterial(mesh, m),
     { defer: true },
   )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
   syncNode(mesh, props)
   untrack(() => props.ref)?.(mesh)
   onCleanup(() => remove(mesh))

package/src/geometry.ts

@@ -1,6 +1,11 @@
-// Geometry: interleaved vertex data in the one layout every scene material
-// shares - position vec3, normal vec3, uv vec2 (8 floats per vertex) - plus
-// uint16 indices. Winding is counter-clockwise seen from outside in the
+// Geometry: interleaved vertex data in one of two named layouts - the
+// "standard" position vec3, normal vec3, uv vec2 (8 floats per vertex)
+// every generator emits, and "colored", which appends an aColor vec4
+// (12 floats, derived with withColors) as the per-vertex data channel for
+// custom materials (tint, baked AO, any four scalars) - plus
+// indices, uint16 or uint32 (the generators here emit uint16; hand-built
+// geometry past 64k vertices uses a Uint32Array and the draw entry follows
+// the array type). Winding is counter-clockwise seen from outside in the
 // y-up world, which the standard camera rig (perspective() with its baked
 // y flip) presents as the engine's displayed-CCW front faces: every
 // generator here culls correctly with cull: "back". Normals ride along
@@ -14,29 +19,59 @@
 // disposeGeometry frees them when an app is done with a geometry for good.
 
 import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
-import type { BufferId, VertexAttribute } from "@solidrt/core/gpu"
+import type { BufferId, IndexFormat, VertexAttribute } from "@solidrt/core/gpu"
 import { add, cross, normalize, sub } from "./math.ts"
-import type { Vec3 } from "./math.ts"
+import type { Vec2, Vec3, Vec4 } from "./math.ts"
 
-export const VERTEX_LAYOUT: VertexAttribute[] = [
+export type VertexLayout = "standard" | "colored"
+
+const STANDARD_ATTRIBUTES: VertexAttribute[] = [
   { name: "aPos", format: "vec3" },
   { name: "aNormal", format: "vec3" },
   { name: "aUV", format: "vec2" },
 ]
+
+/** The pipeline attribute list for each named layout. A deliberately small
+ * set (not an open per-geometry model): every layout shares the standard
+ * prefix, so one shader vocabulary serves all of them. */
+export const VERTEX_LAYOUTS: Record<VertexLayout, VertexAttribute[]> = {
+  standard: STANDARD_ATTRIBUTES,
+  colored: [...STANDARD_ATTRIBUTES, { name: "aColor", format: "vec4" }],
+}
+
+/** Floats per vertex in the "standard" layout (what every generator emits). */
 export const FLOATS_PER_VERTEX = 8
+const COLORED_FLOATS = 12
+
+/** Uint16 indices when they fit, Uint32Array past 64k vertices - the draw
+ * entry follows the array type. The tail of every unbounded generator. */
+export function packIndices(indices: number[], vertexCount: number): Uint16Array | Uint32Array {
+  return vertexCount > 65535 ? new Uint32Array(indices) : new Uint16Array(indices)
+}
 
 export type Geometry = {
-  /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex. */
+  /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex, plus color.rgba
+   * in the "colored" layout. */
   vertices: Float32Array
-  indices: Uint16Array
+  /** The array type picks the draw's index format: Uint32Array past 64k
+   * vertices. */
+  indices: Uint16Array | Uint32Array
+  /** Vertex layout; absent means "standard". Must match the material's
+   * layout - the scene rejects a mismatched pair at add(). */
+  layout?: VertexLayout
   /** Debug name for the lazily-created GPU buffers. */
   label?: string
   _buffer?: BufferId
   _index?: BufferId
 }
 
-/** The geometry's GPU buffers, created on first use and cached on it. */
-export function geometryBuffers(geometry: Geometry): { buffer: BufferId; index: BufferId } {
+/** The geometry's GPU buffers, created on first use and cached on it,
+ * plus the index format the draw entry must bind them with. */
+export function geometryBuffers(geometry: Geometry): {
+  buffer: BufferId
+  index: BufferId
+  indexFormat: IndexFormat
+} {
   let buffer = geometry._buffer
   let index = geometry._index
   if (buffer === undefined || index === undefined) {
@@ -51,7 +86,7 @@ export function geometryBuffers(geometry: Geometry): { buffer: BufferId; index:
     geometry._buffer = buffer
     geometry._index = index
   }
-  return { buffer, index }
+  return { buffer, index, indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16" }
 }
 
 /**
@@ -66,6 +101,106 @@ export function disposeGeometry(geometry: Geometry): void {
   geometry._index = undefined
 }
 
+/** Per-vertex aColor values for withColors/fillColors: a flat 4-per-vertex
+ * array, or a callback deriving each vertex's vec4 from the vertex data. */
+export type ColorFill = ArrayLike<number> | ((index: number, pos: Vec3, normal: Vec3, uv: Vec2) => Vec4)
+
+/**
+ * Derive a "colored"-layout geometry from a standard one: the same
+ * positions, normals, uvs and indices, plus an aColor vec4 per vertex -
+ * the data channel for materials whose vertex stage reads `in vec4 aColor`
+ * (a tint, baked ambient occlusion, any four scalars; the name is the
+ * standard vocabulary, the contents are yours). The callback form receives
+ * each vertex's position, normal and uv - what a baker wants. The source
+ * geometry is untouched and its GPU buffers stay independent.
+ */
+export function withColors(geometry: Geometry, fill: ColorFill, label?: string): Geometry {
+  if (geometry.layout === "colored") {
+    throw new Error("withColors: geometry already carries an aColor channel")
+  }
+  if (geometry.vertices.length % FLOATS_PER_VERTEX !== 0) {
+    throw new Error("withColors: vertex data is not a whole number of standard-layout vertices")
+  }
+  let count = geometry.vertices.length / FLOATS_PER_VERTEX
+  if (typeof fill !== "function" && fill.length !== count * 4) {
+    throw new Error("withColors: fill has " + fill.length + " floats, expected 4 per vertex (" + count * 4 + ")")
+  }
+  let src = geometry.vertices
+  let out = new Float32Array(count * COLORED_FLOATS)
+  for (let i = 0; i < count; i++) {
+    let s = i * FLOATS_PER_VERTEX
+    let d = i * COLORED_FLOATS
+    for (let k = 0; k < FLOATS_PER_VERTEX; k++) out[d + k] = src[s + k]!
+  }
+  fillColors(out, fill)
+  return {
+    vertices: out,
+    indices: geometry.indices,
+    layout: "colored",
+    label: label ?? (geometry.label ? geometry.label + "-colored" : undefined),
+  }
+}
+
+/**
+ * The in-place primitive under withColors: write the aColor slots of a
+ * colored-layout interleave you already own - the hook for a merging
+ * builder baking colors over its packed buffer (the pos/normal/uv the
+ * callback receives are read from the buffer itself, so a packer that
+ * bakes transforms while writing hands the baker world-space vertices).
+ * Fills vertices [first, first + count) - count defaults to the rest of
+ * the buffer - and `fill` indexes relative to `first`, so a per-part
+ * callback works unchanged for both APIs. Returns `vertices`.
+ *
+ * This trusts the buffer to BE colored-layout data - a bare array carries
+ * no layout tag, so only the arithmetic is checked. The Geometry-level
+ * withColors stays the checked path.
+ */
+export function fillColors(vertices: Float32Array, fill: ColorFill, first = 0, count?: number): Float32Array {
+  if (vertices.length % COLORED_FLOATS !== 0) {
+    throw new Error("fillColors: vertex data is not a whole number of colored-layout vertices")
+  }
+  let total = vertices.length / COLORED_FLOATS
+  let n = count ?? total - first
+  if (!Number.isInteger(first) || !Number.isInteger(n) || first < 0 || n < 0 || first + n > total) {
+    throw new Error("fillColors: range [" + first + ", " + (first + n) + ") is outside the buffer's " + total + " vertices")
+  }
+  let fn = typeof fill === "function" ? fill : null
+  if (!fn && fill.length !== n * 4) {
+    throw new Error("fillColors: fill has " + fill.length + " floats, expected 4 per vertex (" + n * 4 + ")")
+  }
+  for (let i = 0; i < n; i++) {
+    let d = (first + i) * COLORED_FLOATS
+    let c: Vec4 = fn
+      ? fn(i, [vertices[d]!, vertices[d + 1]!, vertices[d + 2]!], [vertices[d + 3]!, vertices[d + 4]!, vertices[d + 5]!], [vertices[d + 6]!, vertices[d + 7]!])
+      : [(fill as ArrayLike<number>)[i * 4]!, (fill as ArrayLike<number>)[i * 4 + 1]!, (fill as ArrayLike<number>)[i * 4 + 2]!, (fill as ArrayLike<number>)[i * 4 + 3]!]
+    vertices[d + 8] = c[0]
+    vertices[d + 9] = c[1]
+    vertices[d + 10] = c[2]
+    vertices[d + 11] = c[3]
+  }
+  return vertices
+}
+
+// Indices for a row-major (cellRows + 1) x (cellCols + 1) vertex grid: two
+// CCW triangles per cell, split across the row0col0-row1col1 diagonal -
+// the one quad pattern every grid generator here shares (rows run along
+// the surface, columns around, same handedness everywhere). A collapsed
+// first/last vertex row (sphere pole, cone apex) skips its zero-area
+// triangle per cell.
+function gridIndices(cellRows: number, cellCols: number, skipFirst = false, skipLast = false): number[] {
+  let cols = cellCols + 1
+  let out: number[] = []
+  for (let r = 0; r < cellRows; r++) {
+    for (let c = 0; c < cellCols; c++) {
+      let r0 = r * cols + c
+      let r1 = r0 + cols
+      if (!skipFirst || r > 0) out.push(r0 + 1, r0, r1 + 1)
+      if (!skipLast || r < cellRows - 1) out.push(r0, r1, r1 + 1)
+    }
+  }
+  return out
+}
+
 /** An axis-aligned box centered on the origin: 24 vertices, 36 indices. */
 export function box(width = 1, height = 1, depth = 1, label?: string): Geometry {
   let x = width / 2
@@ -174,30 +309,165 @@ export function torusKnot(
     }
   }
 
-  let indices = new Uint16Array(tubularSegments * radialSegments * 6)
-  let n = 0
-  for (let i = 0; i < tubularSegments; i++) {
-    for (let j = 0; j < radialSegments; j++) {
-      let a = i * cols + j
-      let b = (i + 1) * cols + j
-      let c = (i + 1) * cols + j + 1
-      let d = i * cols + j + 1
-      indices[n++] = a
-      indices[n++] = b
-      indices[n++] = c
-      indices[n++] = a
-      indices[n++] = c
-      indices[n++] = d
+  let indices = new Uint16Array(gridIndices(tubularSegments, radialSegments))
+
+  return { vertices, indices, label }
+}
+
+/**
+ * A capped cylinder on the y axis, centered on the origin. Different top
+ * and bottom radii make it a truncated cone (`cone()` is the zero-top
+ * case); side normals tilt with the taper. Side UVs: u around the
+ * circumference, v 0 at the top to 1 at the bottom; caps get a planar
+ * disc map. A zero radius skips that cap and the degenerate side
+ * triangles at the apex.
+ */
+export function cylinder(
+  radiusTop = 0.5,
+  radiusBottom = 0.5,
+  height = 1,
+  radialSegments = 24,
+  label?: string,
+): Geometry {
+  let h = height / 2
+  let cols = radialSegments + 1
+  let verts: number[] = []
+  // Side normal: perpendicular to the slant line in the (radial, y) plane.
+  let slant = Math.hypot(height, radiusBottom - radiusTop) || 1
+  let nr = height / slant
+  let ny = (radiusBottom - radiusTop) / slant
+  let rows = [
+    { r: radiusTop, y: h, v: 0 },
+    { r: radiusBottom, y: -h, v: 1 },
+  ]
+  for (let row of rows) {
+    for (let ix = 0; ix < cols; ix++) {
+      let u = ix / radialSegments
+      let phi = u * Math.PI * 2
+      let dx = -Math.cos(phi)
+      let dz = Math.sin(phi)
+      verts.push(row.r * dx, row.y, row.r * dz, nr * dx, ny, nr * dz, u, row.v)
     }
   }
+  let indices = gridIndices(1, radialSegments, radiusTop <= 0, radiusBottom <= 0)
+  // Caps fan around a center vertex; the planar UV map has no seam, so the
+  // ring wraps with modulo instead of duplicating a column.
+  let cap = (r: number, y: number, up: number) => {
+    let base = verts.length / FLOATS_PER_VERTEX
+    verts.push(0, y, 0, 0, up, 0, 0.5, 0.5)
+    for (let i = 0; i < radialSegments; i++) {
+      let phi = (i / radialSegments) * Math.PI * 2
+      let x = -Math.cos(phi) * r
+      let z = Math.sin(phi) * r
+      verts.push(x, y, z, 0, up, 0, 0.5 + x / (2 * r), 0.5 + (up > 0 ? z : -z) / (2 * r))
+    }
+    for (let i = 0; i < radialSegments; i++) {
+      let j = (i + 1) % radialSegments
+      if (up > 0) indices.push(base, base + 1 + i, base + 1 + j)
+      else indices.push(base, base + 1 + j, base + 1 + i)
+    }
+  }
+  if (radiusTop > 0) cap(radiusTop, h, 1)
+  if (radiusBottom > 0) cap(radiusBottom, -h, -1)
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
 
+/** A capped cone on the y axis, centered on the origin: `cylinder()` with
+ * a zero top radius (each apex vertex carries its column's side normal, so
+ * the surface shades smoothly around). */
+export function cone(radius = 0.5, height = 1, radialSegments = 24, label?: string): Geometry {
+  return cylinder(0, radius, height, radialSegments, label)
+}
+
+/**
+ * A torus lying flat, centered on the origin: the ring lies in the XZ
+ * plane with the hole on the y axis - the y-up orientation torusKnot also
+ * uses (Three's equivalent stands in XY). Signature order is Three's:
+ * radialSegments subdivides the tube cross-section, tubularSegments the
+ * ring. UVs: u 0..1 around the ring, v 0..1 around the tube, seam
+ * row/column duplicated like torusKnot.
+ */
+export function torus(
+  radius = 0.5,
+  tube = 0.2,
+  radialSegments = 12,
+  tubularSegments = 32,
+  label?: string,
+): Geometry {
+  let rows = tubularSegments + 1
+  let cols = radialSegments + 1
+  let vertices = new Float32Array(rows * cols * FLOATS_PER_VERTEX)
+  let at = 0
+  for (let i = 0; i < rows; i++) {
+    let phi = (i / tubularSegments) * Math.PI * 2
+    let dx = -Math.cos(phi)
+    let dz = Math.sin(phi)
+    for (let j = 0; j < cols; j++) {
+      let psi = (j / radialSegments) * Math.PI * 2
+      let cp = Math.cos(psi)
+      let sp = Math.sin(psi)
+      let r = radius + tube * cp
+      vertices[at] = r * dx
+      vertices[at + 1] = tube * sp
+      vertices[at + 2] = r * dz
+      vertices[at + 3] = cp * dx
+      vertices[at + 4] = sp
+      vertices[at + 5] = cp * dz
+      vertices[at + 6] = i / tubularSegments
+      vertices[at + 7] = j / radialSegments
+      at += FLOATS_PER_VERTEX
+    }
+  }
+  let indices = new Uint16Array(gridIndices(tubularSegments, radialSegments))
   return { vertices, indices, label }
 }
 
+/**
+ * A disc in the XY plane facing +z, centered on the origin (rotate flat
+ * like plane()). UVs are the planar map of the disc inscribed in the unit
+ * square.
+ */
+export function circle(radius = 0.5, segments = 32, label?: string): Geometry {
+  let verts: number[] = [0, 0, 0, 0, 0, 1, 0.5, 0.5]
+  let indices: number[] = []
+  for (let i = 0; i < segments; i++) {
+    let a = (i / segments) * Math.PI * 2
+    let c = Math.cos(a)
+    let s = Math.sin(a)
+    verts.push(radius * c, radius * s, 0, 0, 0, 1, 0.5 + c * 0.5, 0.5 - s * 0.5)
+  }
+  for (let i = 0; i < segments; i++) {
+    indices.push(0, 1 + i, 1 + ((i + 1) % segments))
+  }
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
+
+/**
+ * A flat annulus in the XY plane facing +z, centered on the origin. UVs
+ * are the planar map of the OUTER disc, so a ring textures like the
+ * matching circle() with the middle cut out.
+ */
+export function ring(innerRadius = 0.25, outerRadius = 0.5, segments = 32, label?: string): Geometry {
+  let verts: number[] = []
+  let indices: number[] = []
+  for (let i = 0; i < segments; i++) {
+    let a = (i / segments) * Math.PI * 2
+    let c = Math.cos(a)
+    let s = Math.sin(a)
+    for (let r of [innerRadius, outerRadius]) {
+      verts.push(r * c, r * s, 0, 0, 0, 1, 0.5 + (r * c) / (2 * outerRadius), 0.5 - (r * s) / (2 * outerRadius))
+    }
+  }
+  for (let i = 0; i < segments; i++) {
+    let j = (i + 1) % segments
+    indices.push(i * 2, i * 2 + 1, j * 2 + 1, i * 2, j * 2 + 1, j * 2)
+  }
+  return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
+}
+
 /** A UV sphere centered on the origin (poles on the y axis). */
 export function sphere(radius = 0.5, widthSegments = 24, heightSegments = 16, label?: string): Geometry {
   let verts: number[] = []
-  let indices: number[] = []
   for (let iy = 0; iy <= heightSegments; iy++) {
     let v = iy / heightSegments
     let theta = v * Math.PI
@@ -212,16 +482,7 @@ export function sphere(radius = 0.5, widthSegments = 24, heightSegments = 16, la
       verts.push(radius * nx, radius * ny, radius * nz, nx, ny, nz, u, v)
     }
   }
-  let cols = widthSegments + 1
-  for (let iy = 0; iy < heightSegments; iy++) {
-    for (let ix = 0; ix < widthSegments; ix++) {
-      let a = iy * cols + ix + 1
-      let b = iy * cols + ix
-      let c = (iy + 1) * cols + ix
-      let d = (iy + 1) * cols + ix + 1
-      if (iy !== 0) indices.push(a, b, d)
-      if (iy !== heightSegments - 1) indices.push(b, c, d)
-    }
-  }
+  // Both pole rows are collapsed to the pole point.
+  let indices = gridIndices(heightSegments, widthSegments, true, true)
   return { vertices: new Float32Array(verts), indices: new Uint16Array(indices), label }
 }