vgpu-render 0.0.0-stage → 0.1.0

package/dist/infinite-grid-3d.js

@@ -0,0 +1,407 @@
+/**
+ * Shader-driven infinite ground grid, ported from the reference reference
+ * `the upstream reference`.
+ *
+ * The port keeps the reference algorithm and parameters:
+ * - a finite XZ quad is drawn once and faded near its bounds, so it reads as endless;
+ * - lines are computed in the fragment shader from world XZ coordinates;
+ * - three decimal LOD layers (finer / current / coarser) are combined, and their
+ *   alphas are de-duplicated so overlapping layers do not stack brightness;
+ * - the LOD distance follows the reference camera-state rules from
+ *   `infinite_grid_3d.gd::_update_camera_lod_distance`.
+ *
+ * Everything else (`grid_size`, `cell_size`, `line_width_pixels`, LOD ranges,
+ * center/grazing/edge/far fades, stipple discard and line colors) mirrors the
+ * reference uniforms one to one. `setOpacity` is the only demo-side extension:
+ * it scales the two reference line alphas instead of replacing them.
+ */
+import { draw, geometry } from "vgpu";
+import { prepareShader } from "@vgpu/wgsl/prepare";
+import { linearGridColor } from "./color-space.js";
+const GRID_SHADER = prepareShader(`
+struct GridUniforms {
+  viewProjection: mat4x4f,
+  cameraPosition: vec3f,
+  cellSize: f32,
+  viewGridCenter: vec2f,
+  gridCenter: vec2f,
+  lineWidthPixels: f32,
+  gridSize: f32,
+  edgeFadeStartRatio: f32,
+  edgeFadeEndRatio: f32,
+  minLodPower: f32,
+  maxLodPower: f32,
+  cameraLodDistance: f32,
+  cameraFarClip: f32,
+  grazingFadeStartFactor: f32,
+  grazingFadeEndFactor: f32,
+  lodCenterFadeLineCount: f32,
+  optionsA: vec4<u32>,
+  optionsB: vec4<u32>,
+  thinLineColor: vec4f,
+  thickLineColor: vec4f,
+}
+@group(0) @binding(0) var<uniform> grid: GridUniforms;
+
+// optionsA: x = camera_is_orthogonal, y = debug_lod_colors, z = enable_grazing_opacity,
+//           w = enable_stipple_discard.
+// optionsB: x = enable_lod_center_fade.
+
+struct In { @location(0) position: vec3f }
+struct Out {
+  @builtin(position) clip: vec4f,
+  @location(0) world: vec3f,
+}
+
+@vertex fn vs_main(input: In) -> Out {
+  var out: Out;
+  let world = input.position + vec3f(grid.gridCenter.x, 0.0, grid.gridCenter.y);
+  out.world = world;
+  out.clip = grid.viewProjection * vec4f(world, 1.0);
+  return out;
+}
+
+// Line coverage in pixel units so lines keep a stable screen-space width.
+fn gridLineAlpha(uv: vec2f, currentCellSize: f32) -> f32 {
+  let coord = uv / currentCellSize;
+  let pixelSize = max(abs(dpdx(coord)) + abs(dpdy(coord)), vec2f(0.00001));
+  let distanceToLine = min(fract(coord), 1.0 - fract(coord));
+  let distancePixels = distanceToLine / pixelSize;
+  // 1 px AA transition avoids hard edges and flicker on thin lines.
+  let halfLineWidthPixels = max(grid.lineWidthPixels, 0.25) * 0.5;
+  let coverage = 1.0 - smoothstep(
+    vec2f(max(halfLineWidthPixels - 0.5, 0.0)),
+    vec2f(halfLineWidthPixels + 0.5),
+    distancePixels
+  );
+  return max(coverage.x, coverage.y);
+}
+
+fn lodCenterFade(uv: vec2f, currentCellSize: f32) -> f32 {
+  if (grid.optionsB.x == 0u) {
+    return 1.0;
+  }
+  let halfLineCount = max(grid.lodCenterFadeLineCount * 0.5, 1.0);
+  let snappedCenter = round(grid.viewGridCenter / currentCellSize) * currentCellSize;
+  let levelCoord = (uv - snappedCenter) / max(currentCellSize * halfLineCount, 0.00001);
+  if (grid.optionsA.x != 0u) {
+    let edge = 1.0 - min(1.0, dot(levelCoord, levelCoord));
+    return edge * edge;
+  }
+  return 1.0 - min(1.0, length(levelCoord));
+}
+
+@fragment fn fs_main(input: Out) -> @location(0) vec4f {
+  let uv = input.world.xz;
+
+  let safeCellSize = max(grid.cellSize, 0.00001);
+  let minPower = min(grid.minLodPower, grid.maxLodPower - 2.0);
+  let maxPower = max(grid.maxLodPower, minPower + 2.0);
+  let minLodCellSize = safeCellSize * pow(10.0, minPower);
+  let lodDistance = max(grid.cameraLodDistance, minLodCellSize);
+  let currentLodPower = clamp(
+    floor(log(lodDistance / safeCellSize) / log(10.0)),
+    minPower,
+    maxPower
+  );
+
+  // Select the current decimal LOD and fade toward the next coarser cell size.
+  let currentLodCellSize = safeCellSize * pow(10.0, currentLodPower);
+  let nextLodCellSize = currentLodCellSize * 10.0;
+  let lodFade = clamp(
+    (lodDistance - currentLodCellSize) / max(nextLodCellSize - currentLodCellSize, 0.00001),
+    0.0,
+    1.0
+  );
+
+  // Three neighboring LOD layers: fine lines fade out while major lines remain.
+  let lod0Power = clamp(currentLodPower - 1.0, minPower, maxPower);
+  let lod1Power = clamp(currentLodPower, minPower, maxPower);
+  let lod2Power = clamp(currentLodPower + 1.0, minPower, maxPower);
+  let lod0CellSize = safeCellSize * pow(10.0, lod0Power);
+  let lod1CellSize = safeCellSize * pow(10.0, lod1Power);
+  let lod2CellSize = safeCellSize * pow(10.0, lod2Power);
+
+  let lod0Alpha = gridLineAlpha(uv, lod0CellSize) * lodCenterFade(uv, lod0CellSize) * (1.0 - lodFade);
+  let lod1Alpha = gridLineAlpha(uv, lod1CellSize) * lodCenterFade(uv, lod1CellSize);
+  let lod2Alpha = gridLineAlpha(uv, lod2CellSize) * lodCenterFade(uv, lod2CellSize);
+
+  // Prevent overlapping LOD layers from stacking alpha and causing brightness jumps.
+  let lod2VisibleAlpha = lod2Alpha;
+  let lod1VisibleAlpha = lod1Alpha * (1.0 - lod2VisibleAlpha);
+  let lod0VisibleAlpha = lod0Alpha * (1.0 - lod1Alpha) * (1.0 - lod2VisibleAlpha);
+
+  // Blend minor/current/major line colors across the active LOD transition.
+  var lod0Color = grid.thinLineColor;
+  var lod1Color = mix(grid.thickLineColor, grid.thinLineColor, lodFade);
+  var lod2Color = grid.thickLineColor;
+  if (grid.optionsA.y != 0u) {
+    // Debug layers: blue = lower/finer, green = current, red = upper/coarser.
+    // Only RGB is replaced so alpha stays directly comparable with debug off.
+    lod0Color = vec4f(0.1, 0.35, 1.0, lod0Color.a);
+    lod1Color = vec4f(0.1, 1.0, 0.25, lod1Color.a);
+    lod2Color = vec4f(1.0, 0.15, 0.1, lod2Color.a);
+  }
+
+  let lod0LayerAlpha = lod0VisibleAlpha * lod0Color.a;
+  let lod1LayerAlpha = lod1VisibleAlpha * lod1Color.a;
+  let lod2LayerAlpha = lod2VisibleAlpha * lod2Color.a;
+  let lineAlpha = clamp(lod0LayerAlpha + lod1LayerAlpha + lod2LayerAlpha, 0.0, 1.0);
+  let lineColor = (
+    lod0Color.rgb * lod0LayerAlpha +
+    lod1Color.rgb * lod1LayerAlpha +
+    lod2Color.rgb * lod2LayerAlpha
+  ) / max(lineAlpha, 0.00001);
+
+  // Fade out near the finite mesh bounds so the grid appears endless.
+  let halfGridSize = max(grid.gridSize * 0.5, 0.00001);
+  let normalizedGridCoord = (uv - grid.gridCenter) / halfGridSize;
+  let edgeStart = clamp(grid.edgeFadeStartRatio, 0.0, 1.0);
+  let edgeEnd = max(clamp(grid.edgeFadeEndRatio, 0.0, 1.0), edgeStart + 0.00001);
+  let edgeProgress = clamp(
+    (length(normalizedGridCoord) - edgeStart) / (edgeEnd - edgeStart),
+    0.0,
+    1.0
+  );
+  var edgeOpacity = 1.0 - edgeProgress;
+  if (grid.optionsA.x != 0u) {
+    edgeOpacity = pow(1.0 - edgeProgress * edgeProgress, 2.0);
+  }
+
+  // Fade at grazing view angles to reduce distant transparent trails.
+  var grazingOpacity = 1.0;
+  if (grid.optionsA.z != 0u) {
+    let viewDir = normalize(grid.cameraPosition - input.world);
+    let viewFloorFactor = abs(dot(viewDir, vec3f(0.0, 1.0, 0.0)));
+    let grazingStart = min(grid.grazingFadeStartFactor, grid.grazingFadeEndFactor);
+    let grazingEnd = max(grid.grazingFadeStartFactor, grid.grazingFadeEndFactor);
+    var grazingProgress = step(grazingStart, viewFloorFactor);
+    if (grazingEnd - grazingStart > 0.00001) {
+      grazingProgress = clamp(
+        (viewFloorFactor - grazingStart) / (grazingEnd - grazingStart),
+        0.0,
+        1.0
+      );
+    }
+    grazingOpacity = smoothstep(0.0, 1.0, grazingProgress);
+  }
+
+  // Fade near the camera far clip before the grid is clipped by depth.
+  let farClip = max(grid.cameraFarClip, 0.00001);
+  let cameraDistance = length(grid.cameraPosition - input.world);
+  let distanceOpacity = 1.0 - smoothstep(0.0, 0.5 * farClip, cameraDistance - 0.5 * farClip);
+
+  let alpha = lineAlpha * edgeOpacity * distanceOpacity * grazingOpacity;
+
+  // Stipple discard below 0.1 alpha avoids muddy trails from transparent depth blending.
+  if (grid.optionsA.w != 0u) {
+    let dashCoord = uv / lod1CellSize;
+    let dashDistanceToLine = min(fract(dashCoord), 1.0 - fract(dashCoord));
+    let dashAxis = select(input.clip.x, input.clip.y, dashDistanceToLine.x < dashDistanceToLine.y);
+    if (alpha < 0.1 && alpha / 0.1 < fract(dashAxis / 4.0)) {
+      discard;
+    }
+  }
+
+  if (alpha <= 0.001) {
+    discard;
+  }
+
+  return vec4f(lineColor, alpha);
+}
+`);
+const REFERENCE_THIN_LINE_COLOR = [0.42, 0.42, 0.42, 0.45];
+const REFERENCE_THICK_LINE_COLOR = [0.62, 0.62, 0.62, 0.65];
+const MIN_LOD_CELL_SIZE = 0.0001;
+/** Mirrors the reference property setters, including their clamps. */
+export function resolveGridOptions(options) {
+    return {
+        size: Math.max(options.size ?? 2000, 1),
+        edgeFadeStartRatio: clamp(options.edgeFadeStartRatio ?? 0, 0, 1),
+        edgeFadeEndRatio: clamp(options.edgeFadeEndRatio ?? 1, 0, 1),
+        cellSize: Math.max(options.cellSize ?? 1, 0.0001),
+        lineWidthPixels: Math.max(options.lineWidthPixels ?? 1, 0.25),
+        lodFinerLevels: Math.max(Math.trunc(options.lodFinerLevels ?? 3), 0),
+        lodTotalLevels: Math.max(Math.trunc(options.lodTotalLevels ?? 8), 3),
+        enableGrazingOpacity: options.enableGrazingOpacity ?? true,
+        grazingFadeStart: clamp(options.grazingFadeStart ?? 3, 0, 90),
+        grazingFadeEnd: clamp(options.grazingFadeEnd ?? 20, 0, 90),
+        enableStippleDiscard: options.enableStippleDiscard ?? false,
+        enableLodCenterFade: options.enableLodCenterFade ?? true,
+        lodCenterFadeLineCount: options.lodCenterFadeLineCount ?? 151,
+        thinLineColor: options.thinLineColor ?? REFERENCE_THIN_LINE_COLOR,
+        thickLineColor: options.thickLineColor ?? REFERENCE_THICK_LINE_COLOR,
+        debugLodColors: options.debugLodColors ?? false,
+    };
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** Reference `_get_min_lod_cell_size()`. */
+export function minLodCellSize(options) {
+    return Math.max(options.cellSize * 10 ** -options.lodFinerLevels, MIN_LOD_CELL_SIZE);
+}
+/** Reference `_apply_lod_range_parameters()`. */
+export function lodPowers(options) {
+    const min = -options.lodFinerLevels;
+    return { min, max: min + options.lodTotalLevels - 1 };
+}
+/** Reference `_apply_grazing_fade_parameters()`. */
+export function grazingFactors(options) {
+    const toRadians = (degrees) => (degrees * Math.PI) / 180;
+    return { start: Math.sin(toRadians(options.grazingFadeStart)), end: Math.sin(toRadians(options.grazingFadeEnd)) };
+}
+/**
+ * Reference `_update_camera_lod_distance()` with the grid plane at y = 0: the
+ * distance to the view floor drives the LOD, falling back to camera height near
+ * grazing angles so the LOD distance cannot blow up.
+ */
+export function gridLodState(camera, options = {}) {
+    const resolved = resolveGridOptions(options);
+    const minimum = minLodCellSize(resolved);
+    const [forwardX, forwardY, forwardZ] = camera.cameraForward;
+    const [cameraX, cameraY, cameraZ] = camera.cameraPosition;
+    const gridY = 0;
+    if (camera.projection === "orthographic") {
+        const size = Math.max(camera.orthographicSize ?? 0, minimum);
+        let center = [cameraX, cameraZ];
+        if (Math.abs(forwardY) > 0.0001) {
+            const rayDistance = (gridY - cameraY) / forwardY;
+            center = [cameraX + forwardX * rayDistance, cameraZ + forwardZ * rayDistance];
+        }
+        return { lodDistance: size, viewGridCenter: center, cameraIsOrthogonal: true };
+    }
+    const height = Math.abs(cameraY - gridY);
+    const viewFloorFactor = Math.abs(forwardY);
+    const rayFloorDistance = height / Math.max(viewFloorFactor, 0.0001);
+    // Match Blender: blend view-to-ground distance toward camera height near grazing angles.
+    const lodDistance = Math.max(rayFloorDistance + (height - rayFloorDistance) * (1 - viewFloorFactor), minimum);
+    return {
+        lodDistance,
+        viewGridCenter: [cameraX + forwardX * lodDistance, cameraZ + forwardZ * lodDistance],
+        cameraIsOrthogonal: false,
+    };
+}
+/** The quad is centered on the camera XZ, matching `follow_viewport_camera`. */
+export class InfiniteGrid3D {
+    #gpu;
+    #draw;
+    #geometry;
+    #options;
+    #opacity = 1;
+    #camera = {
+        viewProjection: new Float32Array(16),
+        cameraPosition: [0, 5, 8],
+        cameraForward: [0, -1, 0],
+        projection: "perspective",
+        farClip: 100,
+    };
+    constructor(gpu, options = {}) {
+        this.#gpu = gpu;
+        this.#options = resolveGridOptions(options);
+        this.#geometry = buildGeometry(gpu, this.#options.size);
+        this.#draw = buildDraw(gpu, this.#geometry);
+    }
+    prepare(camera) {
+        this.#camera = camera;
+    }
+    /**
+     * Applies reference-style property updates. Only `size` rebuilds the quad;
+     * every other field is a per-frame uniform, exactly like the reference setters.
+     */
+    setOptions(options) {
+        const previousSize = this.#options.size;
+        this.#options = resolveGridOptions({ ...this.#currentOptions(), ...options });
+        if (this.#options.size !== previousSize)
+            this.#rebuild();
+    }
+    /** Reference `set_grid_size()`: rebuilds the finite quad. */
+    setSize(size) {
+        this.#options.size = Math.max(size, 1);
+        this.#rebuild();
+    }
+    /**
+     * Demo extension over the reference: scales `thin_line_color.a` and
+     * `thick_line_color.a` without discarding their reference ratio.
+     */
+    setOpacity(opacity) {
+        this.#opacity = clamp(opacity, 0, 1);
+    }
+    draw(pass) {
+        const options = this.#options;
+        const lod = gridLodState(this.#camera, options);
+        const powers = lodPowers(options);
+        const grazing = grazingFactors(options);
+        const thinAlpha = options.thinLineColor[3] * this.#opacity;
+        const thickAlpha = options.thickLineColor[3] * this.#opacity;
+        this.#draw.set({
+            grid: {
+                viewProjection: this.#camera.viewProjection,
+                cameraPosition: this.#camera.cameraPosition,
+                cellSize: options.cellSize,
+                viewGridCenter: lod.viewGridCenter,
+                gridCenter: [this.#camera.cameraPosition[0], this.#camera.cameraPosition[2]],
+                lineWidthPixels: options.lineWidthPixels,
+                gridSize: options.size,
+                edgeFadeStartRatio: options.edgeFadeStartRatio,
+                edgeFadeEndRatio: options.edgeFadeEndRatio,
+                minLodPower: powers.min,
+                maxLodPower: powers.max,
+                cameraLodDistance: lod.lodDistance,
+                cameraFarClip: this.#camera.farClip,
+                grazingFadeStartFactor: grazing.start,
+                grazingFadeEndFactor: grazing.end,
+                lodCenterFadeLineCount: options.lodCenterFadeLineCount,
+                optionsA: [
+                    lod.cameraIsOrthogonal ? 1 : 0,
+                    options.debugLodColors ? 1 : 0,
+                    options.enableGrazingOpacity ? 1 : 0,
+                    options.enableStippleDiscard ? 1 : 0,
+                ],
+                optionsB: [options.enableLodCenterFade ? 1 : 0, 0, 0, 0],
+                thinLineColor: linearGridColor(options.thinLineColor, thinAlpha),
+                thickLineColor: linearGridColor(options.thickLineColor, thickAlpha),
+            },
+        });
+        pass.draw(this.#draw);
+    }
+    destroy() {
+        this.#draw.dispose();
+        this.#geometry.destroy();
+    }
+    #rebuild() {
+        this.#draw.dispose();
+        this.#geometry.destroy();
+        this.#geometry = buildGeometry(this.#gpu, this.#options.size);
+        this.#draw = buildDraw(this.#gpu, this.#geometry);
+    }
+    #currentOptions() {
+        return { ...this.#options, thinLineColor: this.#options.thinLineColor, thickLineColor: this.#options.thickLineColor };
+    }
+}
+function buildGeometry(gpu, size) {
+    const half = size * 0.5;
+    return geometry(gpu, {
+        buffers: [{
+                attributes: { position: "float32x3" },
+                data: new Float32Array([
+                    -half, 0, -half, half, 0, -half, half, 0, half,
+                    -half, 0, -half, half, 0, half, -half, 0, half,
+                ]),
+            }],
+        vertexCount: 6,
+    });
+}
+/**
+ * Reference shader uses `render_mode unshaded, blend_mix, depth_draw_always,
+ * cull_disabled`: unlit, straight-alpha blending, two-sided, and depth writes on.
+ */
+function buildDraw(gpu, quad) {
+    return draw(gpu, {
+        shader: GRID_SHADER,
+        geometry: quad,
+        blend: "alpha",
+        cull: "none",
+        depth: { write: true, compare: "less-equal" },
+    });
+}

package/dist/layout-3d.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Layout and drawing specifications ported from `the upstream reference`.
+ *
+ * Every reference scene shares the same layout contract, which is why it lives here rather
+ * than being re-derived per scene:
+ *
+ * ```
+ * column_x(column) = column * COLUMN_SPACING + 0.5      // COLUMN_SPACING is 2.0, axes 2.2
+ * row_z(row)       = SAMPLE_START_Z - row * spacing     // START_Z is -0.45, rows go along -Z
+ * ```
+ *
+ * Each scene has its own `SAMPLE_SPACING`, and some columns override it (radius, size,
+ * angle, height). Coordinates are local to the scene root; the reference capture harness
+ * translates the whole root by `REFERENCE_OFFSET` without rescaling any geometry, so the
+ * same translation is applied here.
+ */
+import type { Color, Vec3 } from "./frame-recorder.js";
+/** `scene.position = Vector3(-10, 0, 1.5)` from `the reference capture script`. */
+export declare const REFERENCE_OFFSET: Vec3;
+export declare function referenceOffset(p: Vec3): Vec3;
+/** Shared value tables used by the reference scenes. */
+export declare const WIDTH_VALUES: readonly [1, 2, 5.5, 10];
+export declare const ALPHA_VALUES: readonly [1, 0.65, 0.35, 0.1];
+export declare const DASH_VALUES: readonly (readonly [number, number])[];
+export declare const JOINT_VALUES: readonly ["none", "round", "bevel", "miter"];
+export declare const RADIUS_VALUES: readonly [0.18, 0.28, 0.38, 0.5];
+export declare const SEGMENT_VALUES: readonly [8, 16, 32, 64];
+export declare const ROTATION_SAMPLE_COUNT = 8;
+export declare const NORMAL_SAMPLE_COUNT = 4;
+export declare const WHITE: Color;
+export declare const CYAN: Color;
+export declare const LIME: Color;
+export declare const ORANGE: Color;
+export declare const ORANGE_SOFT: Color;
+export declare const VIOLET: Color;
+export declare const TEAL: Color;
+export declare const PINK: Color;
+export declare const GOLD: Color;
+/** Reference `_get_normal_sample_color` / `_get_normal_sample_width`, shared by most scenes. */
+export declare function normalSampleColor(row: number): Color;
+export declare function normalSampleWidth(row: number, baseWidth: number): number;
+/**
+ * reference `Color.from_hsv(h, s, v, a)`. The reference solid samples use this, so a fixed
+ * palette color cannot reproduce them. `h` is in `[0, 1]`, matching reference.
+ */
+export declare function fromHsv(h: number, s: number, v: number, a: number): Color;
+export declare function normalizeVector(p: Vec3): Vec3;
+export declare function crossVector(a: Vec3, b: Vec3): Vec3;
+/** reference `Vector3.rotated(axis, angle)` equivalent (right-handed Rodrigues). */
+export declare function rotateAroundAxis(p: Vec3, axis: Vec3, angle: number): Vec3;
+export type CircleBasis = {
+    readonly x: Vec3;
+    readonly y: Vec3;
+    readonly z: Vec3;
+};
+/** Port of `_get_circle_rotation(normal, angle)` from `circle.gd`. */
+export declare function circleBasis(normal: Vec3, angle: number): CircleBasis;
+/** Points on a circle in the plane spanned by a reference rotation basis. */
+export declare function basisCirclePoints(centerLocal: Vec3, radius: number, segments: number, basis: CircleBasis): Vec3[];
+/**
+ * Column/row placement shared by every reference scene.
+ *
+ * The reference files re-implement the same three lines per scene, differing only in the
+ * spacing constants. Modelling that here keeps each scene a small table of numbers instead
+ * of another copy of the coordinate math:
+ *
+ * - `columnX(column) = column * columnSpacing + columnOffset`
+ * - `rowZ(row) = sampleStartZ - row * rowSpacing` (rows advance along **-Z**)
+ * - a per-column override covers the scenes whose radius/size/angle/height columns use a
+ *   wider spacing than the rest (for example `circle` radius 1.15 vs 0.82).
+ */
+export type SceneLayout = {
+    /** Distance between adjacent columns; `2.0` for every scene except `axes` (2.2). */
+    readonly columnSpacing: number;
+    /** Added to `column * columnSpacing`; `0.5` for every ported scene. */
+    readonly columnOffset: number;
+    readonly sampleSpacing: number;
+    readonly sampleStartZ: number;
+    /** Row spacing for specific columns, overriding `sampleSpacing`. */
+    readonly perColumnSpacing?: Readonly<Record<number, number>>;
+    /** Column-specific Y offset, used by scenes that lift a tunnel or grow by radius. */
+    readonly columnY?: (column: number, row: number, baseY: number) => number;
+};
+export declare function createLayout(layout: SceneLayout, baseY: number): {
+    columnX: (column: number) => number;
+    rowZ: (column: number, row: number) => number;
+    rowSpacing: (column: number) => number;
+    at: (column: number, row: number) => Vec3;
+    atLocal: (column: number, row: number) => Vec3;
+};
+export type ScenePositions = ReturnType<typeof createLayout>;
+/** Reference `circle.gd` layout: radius column uses 1.15 row spacing, the rest 0.82. */
+export declare const CIRCLE_REFERENCE_LAYOUT: SceneLayout;
+/**
+ * Per-scene layouts, copied from the constants at the top of each `examples/*.gd`.
+ *
+ * Every reference scene differs only in these numbers, so they are data here rather than
+ * duplicated coordinate math. `columnSpacing` is 2.0 everywhere except `axes` (2.2).
+ */
+export declare const SCENE_LAYOUTS: {
+    /** `index.gd`: absolute origin, its own row spacing, samples lifted to y = 0.55. */
+    readonly index: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 1;
+        readonly sampleSpacing: 1.25;
+        readonly sampleStartZ: -1;
+        readonly baseY: 0.55;
+    };
+    readonly arrow: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.78;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+    };
+    readonly axes: {
+        readonly columnSpacing: 2.2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.86;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 0: 1.05;
+            readonly 3: 1.05;
+        };
+    };
+    readonly grid: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.72;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.06;
+    };
+    readonly rect: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.62;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 0.9;
+        };
+    };
+    readonly box: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.82;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.08;
+        readonly perColumnSpacing: {
+            readonly 1: 1.05;
+        };
+    };
+    readonly arc: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.92;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 1.15;
+            readonly 2: 1.08;
+        };
+    };
+    readonly curve: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.82;
+        readonly sampleStartZ: -2;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 2: number;
+            readonly 4: number;
+        };
+    };
+    readonly sphere: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.86;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 1.08;
+        };
+    };
+    readonly cone: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.84;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 1.05;
+            readonly 2: 1.08;
+        };
+    };
+    readonly cylinder: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.84;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 1.05;
+            readonly 2: 1.08;
+        };
+    };
+    readonly capsule: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 0.5;
+        readonly sampleSpacing: 0.86;
+        readonly sampleStartZ: -0.45;
+        readonly baseY: 0.1;
+        readonly perColumnSpacing: {
+            readonly 1: 1.02;
+            readonly 2: 1.02;
+        };
+    };
+    readonly world_space_width: {
+        readonly columnSpacing: 2;
+        readonly columnOffset: 1;
+        readonly sampleSpacing: 1.25;
+        readonly sampleStartZ: -1;
+        readonly baseY: 0.55;
+    };
+};
+export type SceneLayoutId = keyof typeof SCENE_LAYOUTS;