vgpu-render 0.0.0-stage → 0.2.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/mesh-batch-3d.d.ts

@@ -0,0 +1,10 @@
+import { type FramePass, type Gpu } from "vgpu";
+import type { MeshData } from "./geometry-generators.js";
+import type { Color } from "./frame-draw-list.js";
+export declare class MeshBatch3D {
+    #private;
+    constructor(gpu: Gpu, mesh: MeshData, color: Color, solid: boolean);
+    draw(pass: FramePass, viewProjection: ArrayLike<number>): void;
+    destroy(): void;
+    get solid(): boolean;
+}

package/dist/mesh-batch-3d.js

@@ -0,0 +1,67 @@
+import { draw, geometry } from "vgpu";
+import { prepareShader } from "@vgpu/wgsl/prepare";
+import { DEFAULT_DEPTH_BIAS } from "./gpu-debug-draw-3d.js";
+/** Mirrors the reference mesh/rect shaders: `depth_draw_always` plus the same depth bias. */
+const SHADER = prepareShader(`
+struct Camera { viewProjection: mat4x4f }
+@group(0) @binding(0) var<uniform> camera: Camera;
+const DEPTH_BIAS: f32 = ${DEFAULT_DEPTH_BIAS};
+const DEPTH_BIAS_EPSILON: f32 = 0.000488;
+
+fn apply_depth_bias(clip: vec4f) -> f32 {
+  let bias = clamp(DEPTH_BIAS, -1.0, 1.0);
+  if (bias >= 0.0) {
+    return clip.z * (1.0 - bias);
+  }
+  let safe_depth = max(clip.z, DEPTH_BIAS_EPSILON);
+  let depth_ratio = max(clip.w / safe_depth - DEPTH_BIAS_EPSILON, DEPTH_BIAS_EPSILON);
+  return clip.z * exp2(-bias * log2(depth_ratio));
+}
+
+struct In { @location(0) position: vec3f, @location(1) color: vec4f }
+struct Out { @builtin(position) clip: vec4f, @location(0) color: vec4f }
+@vertex fn vs_main(input: In) -> Out {
+  let clip = camera.viewProjection * vec4f(input.position, 1.0);
+  var out: Out;
+  out.clip = vec4f(clip.xy, apply_depth_bias(clip), clip.w);
+  out.color = input.color;
+  return out;
+}
+@fragment fn fs_main(input: Out) -> @location(0) vec4f { return input.color; }
+`);
+function flatten(mesh, color, solid) {
+    const points = solid ? mesh.triangles.flatMap((triangle) => triangle) : mesh.segments.flatMap((segment) => segment);
+    const data = new Float32Array(points.length * 7);
+    for (let i = 0; i < points.length; i++) {
+        const offset = i * 7;
+        const point = points[i];
+        data.set([point[0], point[1], point[2], color[0], color[1], color[2], color[3]], offset);
+    }
+    return data;
+}
+export class MeshBatch3D {
+    #draw;
+    #geometry;
+    #solid;
+    constructor(gpu, mesh, color, solid) {
+        this.#solid = solid;
+        const data = flatten(mesh, color, solid);
+        this.#geometry = geometry(gpu, {
+            buffers: [{ attributes: { position: "float32x3", color: "float32x4" }, data: data }],
+            vertexCount: data.length / 7,
+            topology: solid ? "triangle-list" : "line-list",
+        });
+        const options = { shader: SHADER, geometry: this.#geometry, depth: { write: true, compare: "less-equal" } };
+        // Filled rects disable culling in the reference; solids keep back-face culling.
+        this.#draw = draw(gpu, solid ? { ...options, blend: "alpha", cull: "back" } : { ...options, cull: "none" });
+    }
+    draw(pass, viewProjection) {
+        this.#draw.set({ camera: { viewProjection } });
+        pass.draw(this.#draw);
+    }
+    destroy() {
+        this.#draw.dispose();
+        this.#geometry.destroy();
+    }
+    get solid() { return this.#solid; }
+}

package/dist/shape2d-shader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * WGSL for the 2D shape pipeline.
+ *
+ * One instanced quad per shape; the fragment stage evaluates a signed distance field, so a
+ * rounded rectangle, an ellipse, an annulus or a regular polygon are all the same pipeline and
+ * none of them is expanded to triangles on the CPU. Coverage comes from the screen-space
+ * derivative of the distance, which keeps edges one pixel wide at any magnification.
+ *
+ * The distance is evaluated in the shape's own space (the space its coordinates were given in),
+ * then converted to canvas pixels, so a stroke width is always a pixel count. `pixelsPerUnit`
+ * and `yFlip` are what make that conversion exact for both 2D spaces: `world2d` has +y up and
+ * `zoom` pixels per unit, `screen` has +y down and one.
+ */
+export declare function shape2dShader(): string;