vgpu-render 0.0.0-stage → 0.2.0

package/dist/gpu-instancing.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Instancing plumbing shared by the debug-draw and text renderers.
+ *
+ * Both renderers have the same shape: one `instances()` collection per primitive kind, an
+ * indirect draw whose arguments a one-thread compute shader refreshes each frame, and a
+ * transient mesh that only has to supply a vertex count. Keeping the helpers here means the
+ * two renderers cannot drift apart on trim, publish or indirect-argument bookkeeping.
+ */
+import { type Compute, type Gpu, type StorageBuffer } from "vgpu";
+import type { InstanceCollection, InstanceId } from "vgpu/scene";
+/**
+ * Shared WGSL for depth handling, ported from `debug_line_3d_common.gdshaderinc`.
+ *
+ * `apply_depth_bias` keeps the reference's exponential form so a `-0.001` bias behaves
+ * like reference and reference (`depth * exp2(-bias * log2(clip.w / depth))`). `depth_bias`
+ * is baked into the source instead of a uniform: the reference sets it once per scene
+ * and it keeps the camera uniform layout identical across all pipelines.
+ */
+export declare function depthBiasHelpers(depthBias: number): string;
+export declare function identity(): Float32Array;
+/** Instances carry no per-instance transform; the vertex stage places them from attributes. */
+export declare function world(collection: InstanceCollection, id: InstanceId): void;
+/** Removes the instances past `count` and reports whether the collection shrank. */
+export declare function trim(collection: InstanceCollection, ids: InstanceId[], count: number): boolean;
+export declare function indirectArgs(buffer: StorageBuffer, vertexCount: number, instanceCount: number): void;
+/**
+ * Copies the current vertex/instance counts into a draw's indirect buffer. The counts live in
+ * a uniform so the pass needs no CPU-side buffer writes: one dispatch per draw rewrites the
+ * four `drawIndirect` words.
+ */
+export declare const INDIRECT_SHADER: import("vgpu").ShaderSource;
+export declare function indirectCompute(gpu: Gpu): Compute;
+/** A six-vertex quad whose corners the vertex stage derives from `vertex_index`. */
+export declare function zeroGeometry(gpu: Gpu): import("vgpu").Geometry;

package/dist/gpu-instancing.js

@@ -0,0 +1,93 @@
+/**
+ * Instancing plumbing shared by the debug-draw and text renderers.
+ *
+ * Both renderers have the same shape: one `instances()` collection per primitive kind, an
+ * indirect draw whose arguments a one-thread compute shader refreshes each frame, and a
+ * transient mesh that only has to supply a vertex count. Keeping the helpers here means the
+ * two renderers cannot drift apart on trim, publish or indirect-argument bookkeeping.
+ */
+import { compute, geometry } from "vgpu";
+import { prepareShader } from "@vgpu/wgsl/prepare";
+/** Epsilon floors of the reference depth-bias formula (`debug_line_3d_common.gdshaderinc`). */
+const DEPTH_BIAS_EPSILON = 0.000488;
+const NEAR_CLIP_EPSILON = 0.000488;
+/**
+ * Shared WGSL for depth handling, ported from `debug_line_3d_common.gdshaderinc`.
+ *
+ * `apply_depth_bias` keeps the reference's exponential form so a `-0.001` bias behaves
+ * like reference and reference (`depth * exp2(-bias * log2(clip.w / depth))`). `depth_bias`
+ * is baked into the source instead of a uniform: the reference sets it once per scene
+ * and it keeps the camera uniform layout identical across all pipelines.
+ */
+export function depthBiasHelpers(depthBias) {
+    return `
+const DEPTH_BIAS: f32 = ${depthBias};
+const DEPTH_BIAS_EPSILON: f32 = ${DEPTH_BIAS_EPSILON};
+const NEAR_CLIP_EPSILON: f32 = ${NEAR_CLIP_EPSILON};
+
+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));
+}
+
+fn clip_near_plane_t(a: vec4f, b: vec4f) -> f32 {
+  if (a.z > a.w && b.z <= b.w) {
+    let distance_a = a.z - a.w;
+    let distance_b = b.z - b.w;
+    return clamp(distance_a / (distance_a - distance_b) + NEAR_CLIP_EPSILON, 0.0, 1.0);
+  }
+  return 0.0;
+}
+`;
+}
+export function identity() {
+    return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+}
+/** Instances carry no per-instance transform; the vertex stage places them from attributes. */
+export function world(collection, id) {
+    collection.setWorld(id, identity());
+}
+/** Removes the instances past `count` and reports whether the collection shrank. */
+export function trim(collection, ids, count) {
+    let changed = false;
+    for (let index = ids.length - 1; index >= count; index--) {
+        collection.remove(ids.pop());
+        changed = true;
+    }
+    return changed;
+}
+export function indirectArgs(buffer, vertexCount, instanceCount) {
+    buffer.write(new Uint32Array([vertexCount, instanceCount, 0, 0]));
+}
+/**
+ * Copies the current vertex/instance counts into a draw's indirect buffer. The counts live in
+ * a uniform so the pass needs no CPU-side buffer writes: one dispatch per draw rewrites the
+ * four `drawIndirect` words.
+ */
+export const INDIRECT_SHADER = prepareShader(`
+struct Params { vertexCount: u32, instanceCount: u32 }
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read_write> args: array<u32>;
+@compute @workgroup_size(1)
+fn cs_main() {
+  args[0] = params.vertexCount;
+  args[1] = params.instanceCount;
+  args[2] = 0u;
+  args[3] = 0u;
+}
+`);
+export function indirectCompute(gpu) {
+    return compute(gpu, INDIRECT_SHADER);
+}
+/** A six-vertex quad whose corners the vertex stage derives from `vertex_index`. */
+export function zeroGeometry(gpu) {
+    return geometry(gpu, {
+        buffers: [{ attributes: { position: "float32x3" }, data: new Float32Array(18) }],
+        vertexCount: 6,
+    });
+}

package/dist/gpu-text-3d.d.ts

@@ -0,0 +1,98 @@
+/**
+ * GPU text renderer.
+ *
+ * One instanced quad per glyph, sampling a glyph atlas page, exactly the shape reference
+ * sprite text takes: `TextPipeline` lays the glyphs out, `FontAtlas` holds the rasterised
+ * coverage, and the render pass instantiates one quad per `PositionedGlyph`
+ * (`the reference implementation`, `the reference implementation`).
+ *
+ * The atlas' pages are the layers of one 2D array texture, so growing past a single page costs no
+ * extra draw call: the instance carries the layer it samples, and `GlyphAtlas` recycles pages whose
+ * glyphs are no longer requested. Only the rectangles written since the last upload are copied, and
+ * each mip level is re-sent for the region that maps to it.
+ *
+ * The atlas stores a tintable alpha mask (RGB = 255, A = coverage) like reference `FontAtlas`,
+ * so the fragment stage only has to multiply the coverage into the span colour's alpha. When
+ * the glyph source encodes a distance field instead, the fragment stage reconstructs the edge
+ * from it, which keeps the glyph sharp at any magnification. Three
+ * placement spaces share the pipeline and are selected per instance:
+ *
+ * Layout and the atlas both work in font pixels and the two world spaces scale the result by
+ * `pixelSize`. That split is the reference `Label3D.font_size` / `pixel_size` pair, and it is
+ * what lets a block keep a fixed world size while its glyphs are rasterised at any resolution.
+ *
+ * - `world-plane` builds the block on a fixed local XY plane, so it foreshortens with the
+ *   camera the way a reference `Label3D` does.
+ * - `world-billboard` builds it from the camera's own right/up axes, read out of the view
+ *   matrix, so the block always faces the camera.
+ * - `screen` places it at a top-left origin pixel position with no projection at all.
+ *
+ * Depth is tested but never written. World text is therefore occluded by geometry in front of
+ * it, while screen text sits at the near plane and always wins; not writing depth keeps a
+ * glyph's translucent ink box from clipping the glyphs drawn after it.
+ */
+import { type FrameComputePass, type FramePass, type Gpu } from "vgpu";
+import type { TextCommand } from "./frame-draw-list.js";
+import { type TextMeasurer } from "./text-layout.js";
+import type { GlyphRasterizer } from "./text-font.js";
+/** Both halves of a font: metrics for layout and pixels for the atlas. */
+export type TextFontSource = GlyphRasterizer & TextMeasurer;
+export type GpuText3DOptions = {
+    readonly font: TextFontSource;
+    /** Maximum glyph instances. Defaults to 16384. */
+    readonly capacity?: number;
+    /**
+     * Atlas page size. Must be a multiple of 64 so a page row is a multiple of WebGPU's 256 byte
+     * `bytesPerRow` alignment. Defaults to 512, reference minimum atlas size.
+     */
+    readonly atlasSize?: number;
+    /**
+     * Atlas pages, one array-texture layer each. A glyph that lands in a later page costs no extra
+     * draw call, and the atlas is never "full" until every page is. Defaults to four 512 px pages'
+     * worth of texels split across the page size chosen: 4 pages at 512 px, one at 1024 px.
+     */
+    readonly pages?: number;
+    /**
+     * What a glyph that no page can hold costs. `"skip"` (the default) drops it and counts it in
+     * `skippedGlyphs`, which keeps a live frame drawing; `"throw"` raises instead, which is what a test
+     * or a tool that would rather fail loudly asks for.
+     */
+    readonly onFull?: "throw" | "skip";
+    /** Depth bias baked into the shader, matching the reference primitive bias. */
+    readonly depthBias?: number;
+    /**
+     * Mip levels for the atlas page, including level 0. A chain is what stops distant text from
+     * shimmering, but the packing padding shrinks with every level, so a deep chain eventually
+     * bleeds between neighbours. Defaults to 4, which takes a 512 px page down to 64 px.
+     */
+    readonly mipLevels?: number;
+};
+export declare class GpuText3D {
+    #private;
+    constructor(gpu: Gpu, options: GpuText3DOptions);
+    /**
+     * Glyphs dropped so far because every page was full. Non-zero means the atlas is too small for the
+     * frame — raise `atlasSize` or `pages` — and characters are quietly missing until it is fixed.
+     */
+    get skippedGlyphs(): number;
+    /**
+     * Lays out every block, fills the glyph atlas, and refreshes the instance buffer.
+     *
+     * `viewportSize` is what turns a world block's font pixels into screen pixels, and that ratio is
+     * what the raster rung follows. A caller with no target to measure (the text-reference page) can
+     * leave it out; world blocks then fall back to one pixel per unit and only lose sharpness.
+     */
+    prepare(commands: readonly TextCommand[], camera: {
+        readonly viewProjection: ArrayLike<number>;
+        readonly view: ArrayLike<number>;
+        readonly viewportSize?: readonly [number, number];
+    }): void;
+    /**
+     * Refreshes this draw's indirect arguments inside an already-open compute pass, so a frame
+     * only needs one pass for every indirect draw in it.
+     */
+    dispatchIndirect(pass: FrameComputePass): void;
+    draw(pass: FramePass): void;
+    get glyphCount(): number;
+    destroy(): void;
+}