@aardworx/wombat.rendering 0.8.0 → 0.9.0

package/dist/runtime/heapEffect.d.ts

@@ -0,0 +1,235 @@
+import type { Effect } from "@aardworx/wombat.shader";
+export interface HeapEffectInput {
+    readonly name: string;
+    readonly wgslType: string;
+    readonly byteSize: number;
+    readonly location?: number;
+}
+/**
+ * One field of the VS-output / FS-input inter-stage struct ("VsOut"
+ * conventionally). Drives the per-effect VsOut struct generated into
+ * the prelude — no hardcoded clipPos/worldPos/etc. The runtime stays
+ * agnostic to varying names, just like uniforms.
+ */
+export interface HeapVarying {
+    readonly name: string;
+    readonly wgslType: string;
+    readonly location?: number;
+    readonly builtin?: string;
+    readonly interpolation?: "smooth" | "flat" | "centroid" | "sample" | "no-perspective";
+}
+/** One texture binding the effect declares (post link + DCE). */
+export interface HeapTextureBinding {
+    readonly name: string;
+    /** WGSL type expression, e.g. "texture_2d<f32>", "texture_cube<f32>". */
+    readonly wgslType: string;
+}
+/** One sampler binding the effect declares (post link + DCE). */
+export interface HeapSamplerBinding {
+    readonly name: string;
+    /** WGSL type — "sampler" or "sampler_comparison". */
+    readonly wgslType: string;
+}
+export interface HeapEffectSchema {
+    readonly attributes: readonly HeapEffectInput[];
+    readonly uniforms: readonly HeapEffectInput[];
+    readonly varyings: readonly HeapVarying[];
+    readonly fragmentOutputs: readonly {
+        readonly name: string;
+        readonly location: number;
+        readonly wgslType: string;
+    }[];
+    readonly textures: readonly HeapTextureBinding[];
+    readonly samplers: readonly HeapSamplerBinding[];
+}
+export interface CompiledHeapEffect {
+    readonly rawVs: string;
+    readonly rawFs: string;
+    readonly schema: HeapEffectSchema;
+}
+/**
+ * Maps fragment-output names to framebuffer locations. Outputs not
+ * in the map are pruned by `linkFragmentOutputs`, which cascades
+ * through `pruneCrossStage` / `reduceUniforms` — uniforms that only
+ * fed the dropped outputs vanish from the schema entirely.
+ */
+export interface FragmentOutputLayout {
+    readonly locations: ReadonlyMap<string, number>;
+}
+export declare function compileHeapEffect(effect: Effect, fragmentOutputLayout?: FragmentOutputLayout): CompiledHeapEffect;
+export interface DrawHeaderField {
+    readonly name: string;
+    readonly wgslName: string;
+    readonly wgslType: string;
+    readonly byteOffset: number;
+    readonly byteSize: number;
+    readonly kind: "uniform-ref" | "attribute-ref" | "texture-ref";
+    /**
+     * For `uniform-ref`: the uniform's underlying WGSL type. The
+     * rewriter uses this to pick the right inline read expression
+     * (mat4x4 → 4 vec4 reads, vec3 → 3 f32 reads, etc.).
+     */
+    readonly uniformWgslType?: string;
+    /**
+     * For `attribute-ref`: the attribute's declared WGSL type. Drives
+     * the inline `attributeLoadExpr` when generating preamble lets.
+     */
+    readonly attributeWgslType?: string;
+    /**
+     * For `texture-ref`: which sub-entry this is. Atlas-variant texture
+     * bindings expand into four contiguous drawHeader entries —
+     * `pageRef` (u32 slot index), `formatBits` (u32 packed sampler
+     * state + mip + format), `origin` (vec2<f32>, mip-0 top-left in
+     * normalized atlas coords), `size` (vec2<f32>, mip-0 size). The
+     * runtime packs these as inline values (not pool refs); the
+     * shader pass that consumes them lands in a follow-up PR.
+     */
+    readonly textureSub?: "pageRef" | "formatBits" | "origin" | "size";
+    /** For `texture-ref`: the schema's logical texture binding name (shared by all four sub-entries). */
+    readonly textureBindingName?: string;
+}
+export interface BucketLayout {
+    readonly drawHeaderFields: readonly DrawHeaderField[];
+    readonly drawHeaderBytes: number;
+    /** Generated WGSL prelude — bindings + per-effect VsOut struct. No helper fns, no DrawHeader struct. */
+    readonly preludeWgsl: string;
+    /** DrawHeader stride in u32 elements (drawHeaderBytes / 4). */
+    readonly strideU32: number;
+    /**
+     * Names (schema-side) of uniforms that vary per instance. Populated
+     * from `spec.instances.values` at addDraw time; the rewriter pulls
+     * these via `instanceLoadExpr` instead of `uniformLoadExpr`.
+     */
+    readonly perInstanceUniforms: ReadonlySet<string>;
+    /**
+     * Names (schema-side) of attributes that vary per instance. Populated
+     * from `spec.instanceAttributes` at addDraw time. The rewriter
+     * indexes per-instance attribute reads by `iidx` (= `instance_index`
+     * the megacall path) instead of `vid`.
+     */
+    readonly perInstanceAttributes: ReadonlySet<string>;
+    /**
+     * Texture bindings: name + WGSL type + bind-group binding number
+     * (allocated starting at TEX_BINDING_START, after the four heap-
+     * data bindings 0–3 and the three megacall bindings 4–6).
+     */
+    readonly textureBindings: readonly {
+        readonly name: string;
+        readonly wgslType: string;
+        readonly binding: number;
+    }[];
+    /** Sampler bindings, allocated after textures. */
+    readonly samplerBindings: readonly {
+        readonly name: string;
+        readonly wgslType: string;
+        readonly binding: number;
+    }[];
+    /**
+     * Atlas-routed texture binding names, exposed for the FS rewriter so
+     * it can substitute `textureSample(name, smp, uv)` with the heap
+     * `atlasSample(...)` helper for these names only.
+     */
+    readonly atlasTextureBindings: ReadonlySet<string>;
+}
+/**
+ * First texture binding number; samplers come after the textures.
+ * Bindings 0–3 are the four heap arena views, 4–6 are megacall
+ * (drawTable, indexStorage, firstDrawInTile).
+ */
+export declare const HEAP_TEX_BINDING_START = 7;
+/**
+ * Number of independent pages per format. Drives both the BGL slot
+ * count (N consecutive linear bindings + N consecutive srgb bindings
+ * + 1 sampler) and the shader's `switch pageRef` ladder. Must match
+ * `ATLAS_MAX_PAGES_PER_FORMAT` in `textureAtlas/atlasPool.ts`.
+ */
+export declare const ATLAS_ARRAY_SIZE = 8;
+/** First atlas binding (linear texture for page 0). */
+export declare const ATLAS_LINEAR_BINDING_BASE = 11;
+/** First srgb atlas binding (= linear base + N). */
+export declare const ATLAS_SRGB_BINDING_BASE: number;
+/** Atlas sampler binding (= linear base + 2N). */
+export declare const ATLAS_SAMPLER_BINDING: number;
+export declare function buildBucketLayout(schema: HeapEffectSchema, _hasTextures: boolean, opts?: {
+    perInstanceUniforms?: ReadonlySet<string>;
+    perInstanceAttributes?: ReadonlySet<string>;
+    /**
+     * Names of schema texture bindings routed via the atlas binding-array
+     * path. Each such binding is dropped from `textureBindings` /
+     * `samplerBindings` and replaced with four `texture-ref` drawHeader
+     * fields (pageRef / formatBits / origin / size). Pass an empty set
+     * (default) for the standalone texture path.
+     */
+    atlasTextureBindings?: ReadonlySet<string>;
+}): BucketLayout;
+/**
+ * Atlas prelude: declares N independent `texture_2d<f32>` bindings
+ * per format (linear + srgb), plus a shared atlas sampler. The N-way
+ * `switch pageRef` ladder picks the matching texture pair for each
+ * draw. Each atlas page is its own `GPUTexture` — adding pages to a
+ * format is just a fresh allocation slotted into the next BGL entry,
+ * no GPU-side `copyTextureToTexture` required.
+ *
+ * `binding_array<texture_2d<f32>, N>` would collapse the switch into
+ * a runtime index but requires Chrome's experimental bindless
+ * feature; the N-consecutive-bindings + switch pattern is native
+ * WebGPU 1.0.
+ *
+ * Mip filtering is software (the GPU's mip walk would walk the
+ * texture's mip chain, not our embedded Iliffe pyramid). LOD is
+ * computed from screen-space derivatives of `uv * size_px` in mip-0
+ * texels-per-screen-pixel.
+ *
+ * Sample math (verified by `tests-browser/atlas-sampling-conformance.test.ts`
+ * to match native hardware bilinear within 1 LSB across clamp/repeat/
+ * mirror at any uv):
+ *   - Clamp:  atlas_p = origin_px + clamp(uv, 0, 1) * size_px
+ *   - Mirror: atlas_p = origin_px + mirrorUv(uv) * size_px
+ *   - Repeat: atlas_p = origin_px + fract(uv) * size_px, then shift ∓1
+ *             if within 0.5 atlas-pixel of the sub-rect edge, so
+ *             hardware bilinear straddles the outer wrap-gutter ring.
+ * `origin_px` / `size_px` are atlas-pixel coordinates of mip-0, NOT
+ * normalized. Mip-k rect is computed by walking the integer floor-
+ * halving sequence that matches the CPU packer's pyramid layout.
+ * Each sub-rect (incl. every mip slot) carries a 2-px gutter (inner
+ * ring = clamp-replicate edge, outer ring = wrap = opposite edge)
+ * filled by the upload kernel; without it bilinear at the edges
+ * bleeds across sub-rect boundaries.
+ */
+export declare function generateAtlasPrelude(): string;
+/**
+ * Emit `2 * ATLAS_ARRAY_SIZE + 1` binding declarations: N linear
+ * `texture_2d<f32>`, N srgb `texture_2d<f32>`, then the shared
+ * atlas sampler.
+ */
+export declare function generateAtlasBindings(): string;
+/**
+ * Emit the `switch pageRef` ladder body for `atlasSampleAtMip`. Each
+ * case picks the matching `atlasLinear<i>` / `atlasSrgb<i>` decl and
+ * blends on `format == 1u`. The fallback (page out of range) is the
+ * function-level `vec4<f32>(0.0)` after the switch.
+ */
+export declare function generateAtlasSwitch(): string;
+/** Atlas-texture varying names used by the VS→FS threading + FS preamble. */
+export declare function atlasVaryingNames(name: string): {
+    pageRef: string;
+    formatBits: string;
+    origin: string;
+    size: string;
+};
+/**
+ * Megacall VS prelude: binary-search `drawTable` (one record per slot,
+ * 5 u32s: firstEmit, drawIdx, indexStart, indexCount, instanceCount)
+ * for the slot owning the given `emitIdx`, then split the in-record
+ * offset into `(instId, vid)` so per-RO instancing collapses to one
+ * record + one drawIndirect. Defines:
+ *   - `heap_drawIdx` — per-RO selector for header reads.
+ *   - `instId`         — instance index in [0, instanceCount-1].
+ *   - `vid`            — vertex index pulled from indexStorage.
+ *
+ * Layout: each record emits `indexCount * instanceCount` vertices.
+ * `local = emitIdx - firstEmit`, `instId = local / indexCount`,
+ * `vid = indices[indexStart + local % indexCount]`.
+ */
+export declare function megacallSearchPrelude(): string;
+//# sourceMappingURL=heapEffect.d.ts.map

package/dist/runtime/heapEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heapEffect.d.ts","sourceRoot":"","sources":["../../src/runtime/heapEffect.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,gBAAgB,CAAC;CACvF;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrH,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,kBAAkB,CAajH;AAwGD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,GAAG,aAAa,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnE,qGAAqG;IACrG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wGAAwG;IACxG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpH,kDAAkD;IAClD,QAAQ,CAAC,eAAe,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpH;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,oDAAoD;AACpD,eAAO,MAAM,uBAAuB,QAA+C,CAAC;AACpF,kDAAkD;AAClD,eAAO,MAAM,qBAAqB,QAAmD,CAAC;AAEtF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,OAAO,EACrB,IAAI,GAAE;IACJ,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACvC,GACL,YAAY,CAmHd;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAmG7C;AAOD;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAU9C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAY5C;AAYD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC/C,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CACnE,CAOA;AAGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAS9C"}