@aethervtt/shard-gpu-webgl2 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-gpu-webgl2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/binding.d.ts

@@ -0,0 +1,32 @@
+import { type Webgl2Buffer, Webgl2Sampler, Webgl2TextureView } from './resources.js';
+export declare class Webgl2BindGroupLayout {
+    readonly id: number;
+    readonly label: string;
+    readonly entries: readonly GPUBindGroupLayoutEntry[];
+    /** Uniform buffers with a dynamic offset, in binding order: the order dynamic offsets come in. */
+    readonly dynamic: readonly number[];
+    constructor(d: GPUBindGroupLayoutDescriptor);
+}
+export declare class Webgl2PipelineLayout {
+    readonly id: number;
+    readonly label: string;
+    readonly groups: readonly Webgl2BindGroupLayout[];
+    constructor(d: GPUPipelineLayoutDescriptor);
+}
+export interface BoundBuffer {
+    buffer: Webgl2Buffer;
+    offset: number;
+    size: number;
+}
+export declare class Webgl2BindGroup {
+    readonly id: number;
+    readonly label: string;
+    readonly layout: Webgl2BindGroupLayout;
+    /** By binding number. */
+    readonly buffers: (BoundBuffer | undefined)[];
+    readonly views: (Webgl2TextureView | undefined)[];
+    readonly samplers: (Webgl2Sampler | undefined)[];
+    /** Where each dynamic offset applies: its binding, in the order offsets are given. */
+    readonly dynamic: readonly number[];
+    constructor(d: GPUBindGroupDescriptor);
+}

package/dist/binding.js

@@ -0,0 +1,81 @@
+import { unsupported } from "./errors.js";
+import { Webgl2Sampler, Webgl2TextureView } from "./resources.js";
+let nextId = 1;
+class Webgl2BindGroupLayout {
+  id = nextId++;
+  label;
+  entries;
+  /** Uniform buffers with a dynamic offset, in binding order: the order dynamic offsets come in. */
+  dynamic;
+  constructor(d) {
+    this.label = d.label ?? "";
+    this.entries = [...d.entries];
+    for (const e of this.entries) {
+      if (e.storageTexture) throw unsupported(`bind a storage texture ("${this.label}")`);
+      if (e.buffer && (e.buffer.type === "storage" || e.buffer.type === "read-only-storage")) {
+        if (e.visibility & 3) {
+          throw unsupported(
+            `bind a storage buffer to a vertex or fragment shader ("${this.label}" #${e.binding})`,
+            "Read engine data through a @data declaration (0064)."
+          );
+        }
+      }
+      if (e.externalTexture) throw unsupported(`bind an external texture ("${this.label}")`);
+    }
+    this.dynamic = this.entries.filter((e) => e.buffer?.hasDynamicOffset).map((e) => e.binding).sort((a, b) => a - b);
+  }
+}
+class Webgl2PipelineLayout {
+  id = nextId++;
+  label;
+  groups;
+  constructor(d) {
+    this.label = d.label ?? "";
+    this.groups = [...d.bindGroupLayouts];
+  }
+}
+class Webgl2BindGroup {
+  id = nextId++;
+  label;
+  layout;
+  /** By binding number. */
+  buffers = [];
+  views = [];
+  samplers = [];
+  /** Where each dynamic offset applies: its binding, in the order offsets are given. */
+  dynamic;
+  constructor(d) {
+    this.label = d.label ?? "";
+    this.layout = d.layout;
+    this.dynamic = this.layout.dynamic;
+    for (const e of d.entries) {
+      const r = e.resource;
+      if (r instanceof Webgl2TextureView) {
+        if (!r.bindable()) {
+          throw unsupported(
+            `bind "${r.texture.label}" as a ${r.dimension} view of layers ${r.baseArrayLayer}\u2013${r.baseArrayLayer + r.arrayLayerCount - 1} (it binds as ${r.texture.bindingDimension})`,
+            "A baseline texture binds as the one dimension it was made for (textureBindingViewDimension)."
+          );
+        }
+        this.views[e.binding] = r;
+      } else if (r instanceof Webgl2Sampler) {
+        this.samplers[e.binding] = r;
+      } else if (r && typeof r === "object" && "buffer" in r) {
+        const b = r;
+        const offset = b.offset ?? 0;
+        this.buffers[e.binding] = {
+          buffer: b.buffer,
+          offset,
+          size: b.size ?? b.buffer.size - offset
+        };
+      } else {
+        throw unsupported(`bind ${String(r)} ("${this.label}" #${e.binding})`);
+      }
+    }
+  }
+}
+export {
+  Webgl2BindGroup,
+  Webgl2BindGroupLayout,
+  Webgl2PipelineLayout
+};

package/dist/cache.d.ts

@@ -0,0 +1,73 @@
+import { type GlslStage, type GlslTranslation, type Naga } from './naga.js';
+/** The naga build in `wasm/shard_naga.wasm` (crates/shard-naga): part of every key. */
+export declare const NAGA_VERSION = "30.0.1";
+/**
+ * The shim's own version, also in every key: bump it when what the shim asks naga for, or does to
+ * its GLSL, changes.
+ */
+export declare const SHIM_VERSION = 1;
+/** What a baked set holds (`.shard/shaders/webgl2.json`). */
+export interface BakedTranslations {
+    format: 'shard-webgl2-glsl';
+    naga: string;
+    shim: number;
+    /** By key (`translationKey`). */
+    entries: Record<string, GlslTranslation>;
+}
+export interface ShaderCacheStats {
+    /** Translations found without naga, by where. */
+    hits: {
+        memory: number;
+        baked: number;
+        stored: number;
+    };
+    /** What naga translated this session, and how long each took (ms). */
+    misses: {
+        entry: string;
+        stage: GlslStage;
+        ms: number;
+    }[];
+    /** How long loading naga took, or undefined if this session never needed it. */
+    nagaLoadMs: number | undefined;
+    /** Translations in the baked set (0 without one, or if it was for another naga or shim). */
+    baked: number;
+}
+export interface TranslatorOptions {
+    /** EXT_clip_control is on: only y is flipped in the vertex stage. */
+    clipControl: boolean;
+    /** A baked set, or where it's served. */
+    baked?: string | URL | BakedTranslations;
+    /** Keeps translations in IndexedDB across sessions. Default true where there is IndexedDB. */
+    persist?: boolean;
+    /** Loads naga. Tests stub it. */
+    naga?: () => Promise<Naga>;
+}
+/**
+ * A translation's key: naga's and the shim's versions, the clip mode, the stage and entry point,
+ * and the linked WGSL. A define or a data layout changes the WGSL, so the key; nothing else does.
+ */
+export declare function translationKey(code: string, entry: string, stage: GlslStage, clipControl: boolean): string;
+export declare class Translator {
+    readonly stats: ShaderCacheStats;
+    private readonly options;
+    private readonly memory;
+    private bakedSet;
+    private bakedEntries;
+    private store;
+    private naga;
+    constructor(options: TranslatorOptions);
+    /**
+     * Every translation this session used, as a baked set: what a host records by running once on
+     * WebGL2, to ship (`webgl2.shaders`) so later sessions skip naga for them.
+     */
+    export(): BakedTranslations;
+    /** From memory or the (already fetched) baked set; undefined otherwise. Never loads anything. */
+    cached(code: string, entry: string, stage: GlslStage): GlslTranslation | undefined;
+    translate(code: string, entry: string, stage: GlslStage): Promise<GlslTranslation>;
+    /** Fetches the baked set once; a set for another naga or shim counts as none. */
+    private loadBaked;
+    private loadNaga;
+    private db;
+    private read;
+    private write;
+}

package/dist/cache.js

@@ -0,0 +1,184 @@
+import { loadNaga } from "./naga.js";
+const NAGA_VERSION = "30.0.1";
+const SHIM_VERSION = 1;
+function hash(text) {
+  const lane = (seed) => {
+    let h1 = 3735928559 ^ seed;
+    let h2 = 1103547991 ^ seed;
+    for (let i = 0; i < text.length; i++) {
+      const c = text.charCodeAt(i);
+      h1 = Math.imul(h1 ^ c, 2654435761);
+      h2 = Math.imul(h2 ^ c, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+    h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, "0");
+  };
+  return lane(1) + lane(2);
+}
+function translationKey(code, entry, stage, clipControl) {
+  return hash(
+    `${NAGA_VERSION}|${SHIM_VERSION}|${clipControl ? "clip" : "remap"}|${stage}|${entry}|${code}`
+  );
+}
+const DB = "shard";
+const STORE = "webgl2-glsl";
+function openStore() {
+  const idb = globalThis.indexedDB;
+  if (!idb) return Promise.resolve(void 0);
+  return new Promise((resolve) => {
+    try {
+      const request = idb.open(DB, 1);
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains(STORE))
+          request.result.createObjectStore(STORE);
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => resolve(void 0);
+      request.onblocked = () => resolve(void 0);
+    } catch {
+      resolve(void 0);
+    }
+  });
+}
+class Translator {
+  stats = {
+    hits: { memory: 0, baked: 0, stored: 0 },
+    misses: [],
+    nagaLoadMs: void 0,
+    baked: 0
+  };
+  options;
+  memory = /* @__PURE__ */ new Map();
+  bakedSet;
+  bakedEntries;
+  store;
+  naga;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Every translation this session used, as a baked set: what a host records by running once on
+   * WebGL2, to ship (`webgl2.shaders`) so later sessions skip naga for them.
+   */
+  export() {
+    return {
+      format: "shard-webgl2-glsl",
+      naga: NAGA_VERSION,
+      shim: SHIM_VERSION,
+      entries: Object.fromEntries(this.memory)
+    };
+  }
+  /** From memory or the (already fetched) baked set; undefined otherwise. Never loads anything. */
+  cached(code, entry, stage) {
+    const key = translationKey(code, entry, stage, this.options.clipControl);
+    const hit = this.memory.get(key);
+    if (hit) {
+      this.stats.hits.memory++;
+      return hit;
+    }
+    const baked = this.bakedEntries?.[key];
+    if (baked) {
+      this.memory.set(key, baked);
+      this.stats.hits.baked++;
+    }
+    return baked;
+  }
+  async translate(code, entry, stage) {
+    const key = translationKey(code, entry, stage, this.options.clipControl);
+    const hit = this.memory.get(key);
+    if (hit) {
+      this.stats.hits.memory++;
+      return hit;
+    }
+    const baked = (await this.loadBaked())?.[key];
+    if (baked) {
+      this.memory.set(key, baked);
+      this.stats.hits.baked++;
+      return baked;
+    }
+    const stored = await this.read(key);
+    if (stored) {
+      this.memory.set(key, stored);
+      this.stats.hits.stored++;
+      return stored;
+    }
+    const naga = await this.loadNaga();
+    const start = performance.now();
+    const made = naga.translate(code, entry, stage, { clipControl: this.options.clipControl });
+    this.stats.misses.push({ entry, stage, ms: performance.now() - start });
+    this.memory.set(key, made);
+    void this.write(key, made);
+    return made;
+  }
+  /** Fetches the baked set once; a set for another naga or shim counts as none. */
+  loadBaked() {
+    const source = this.options.baked;
+    if (!source) return Promise.resolve(void 0);
+    this.bakedSet ??= (async () => {
+      try {
+        let set;
+        if (typeof source === "string" || source instanceof URL) {
+          const response = await fetch(source);
+          if (!response.ok) return void 0;
+          set = await response.json();
+        } else {
+          set = source;
+        }
+        if (set.format !== "shard-webgl2-glsl" || set.naga !== NAGA_VERSION || set.shim !== SHIM_VERSION) {
+          return void 0;
+        }
+        this.stats.baked = Object.keys(set.entries).length;
+        this.bakedEntries = set.entries;
+        return set.entries;
+      } catch {
+        return void 0;
+      }
+    })();
+    return this.bakedSet;
+  }
+  loadNaga() {
+    this.naga ??= (async () => {
+      const start = performance.now();
+      const naga = await (this.options.naga ?? loadNaga)();
+      this.stats.nagaLoadMs = performance.now() - start;
+      return naga;
+    })();
+    this.naga.catch(() => {
+      this.naga = void 0;
+    });
+    return this.naga;
+  }
+  db() {
+    if (this.options.persist === false) return Promise.resolve(void 0);
+    this.store ??= openStore();
+    return this.store;
+  }
+  async read(key) {
+    const db = await this.db();
+    if (!db) return void 0;
+    return new Promise((resolve) => {
+      try {
+        const request = db.transaction(STORE, "readonly").objectStore(STORE).get(key);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => resolve(void 0);
+      } catch {
+        resolve(void 0);
+      }
+    });
+  }
+  async write(key, value) {
+    const db = await this.db();
+    if (!db) return;
+    try {
+      db.transaction(STORE, "readwrite").objectStore(STORE).put(value, key);
+    } catch {
+    }
+  }
+}
+export {
+  NAGA_VERSION,
+  SHIM_VERSION,
+  Translator,
+  translationKey
+};

package/dist/commands.d.ts

@@ -0,0 +1,101 @@
+import type { Webgl2BindGroup } from './binding.js';
+import type { Webgl2RenderPipeline } from './pipeline.js';
+import type { Webgl2QuerySet } from './queries.js';
+import type { Webgl2Buffer, Webgl2TextureView } from './resources.js';
+export declare const OP: {
+    readonly BEGIN_PASS: 1;
+    readonly END_PASS: 2;
+    readonly SET_PIPELINE: 3;
+    readonly SET_BIND_GROUP: 4;
+    readonly SET_VERTEX_BUFFER: 5;
+    readonly SET_INDEX_BUFFER: 6;
+    readonly DRAW: 7;
+    readonly DRAW_INDEXED: 8;
+    readonly VIEWPORT: 9;
+    readonly SCISSOR: 10;
+    readonly STENCIL_REFERENCE: 11;
+    readonly BLEND_CONSTANT: 12;
+    readonly COPY_BUFFER: 13;
+    readonly COPY_BUFFER_TO_TEXTURE: 14;
+    readonly COPY_TEXTURE_TO_BUFFER: 15;
+    readonly COPY_TEXTURE: 16;
+    readonly CLEAR_BUFFER: 17;
+    readonly BEGIN_QUERY: 18;
+    readonly END_QUERY: 19;
+    readonly RESOLVE_QUERIES: 20;
+};
+export declare class CommandStream {
+    nums: Float64Array<ArrayBuffer>;
+    n: number;
+    readonly refs: unknown[];
+    r: number;
+    num(value: number): void;
+    ref(value: unknown): void;
+    /** Empties it, dropping its references so recorded objects can be collected. */
+    reset(): void;
+}
+export declare class Webgl2CommandBuffer {
+    label: string;
+    /** What to replay; undefined once submitted. */
+    stream: CommandStream | undefined;
+    /** The encoder that made it, pooled again after the submit. */
+    readonly encoder: Webgl2CommandEncoder;
+    constructor(encoder: Webgl2CommandEncoder);
+}
+type Extent = GPUExtent3D;
+export declare class Webgl2CommandEncoder {
+    label: string;
+    /** @internal The pass being recorded times itself (`timestampWrites`): its end ends the query. */
+    timedPass: boolean;
+    private stream;
+    private readonly pass;
+    private readonly buffer;
+    constructor();
+    /** @internal Starts recording into `stream` (a new or pooled encoder). */
+    begin(stream: CommandStream, label: string): this;
+    /** @internal The stream commands record into. */
+    get recording(): CommandStream;
+    beginRenderPass(d: GPURenderPassDescriptor): Webgl2RenderPassEncoder;
+    beginComputePass(d?: GPUComputePassDescriptor): never;
+    copyBufferToBuffer(source: Webgl2Buffer, a: number | Webgl2Buffer, b?: Webgl2Buffer | number, c?: number, d?: number): void;
+    copyBufferToTexture(source: GPUTexelCopyBufferInfo, destination: GPUTexelCopyTextureInfo, size: Extent): void;
+    copyTextureToBuffer(source: GPUTexelCopyTextureInfo, destination: GPUTexelCopyBufferInfo, size: Extent): void;
+    copyTextureToTexture(source: GPUTexelCopyTextureInfo, destination: GPUTexelCopyTextureInfo, size: Extent): void;
+    clearBuffer(buffer: Webgl2Buffer, offset?: number, size?: number): void;
+    /** Pairs of the set to the buffer: written when the buffer is mapped (queries.ts). */
+    resolveQuerySet(querySet: Webgl2QuerySet, firstQuery: number, queryCount: number, destination: Webgl2Buffer, destinationOffset: number): void;
+    writeTimestamp(): never;
+    pushDebugGroup(): void;
+    popDebugGroup(): void;
+    insertDebugMarker(): void;
+    finish(d?: GPUCommandBufferDescriptor): Webgl2CommandBuffer;
+}
+export declare class Webgl2RenderPassEncoder {
+    label: string;
+    private readonly encoder;
+    constructor(encoder: Webgl2CommandEncoder);
+    setPipeline(pipeline: Webgl2RenderPipeline): void;
+    setBindGroup(index: number, group: Webgl2BindGroup | null, offsets?: Iterable<number> | Uint32Array, start?: number, length?: number): void;
+    setVertexBuffer(slot: number, buffer: Webgl2Buffer | null, offset?: number, size?: number): void;
+    setIndexBuffer(buffer: Webgl2Buffer, format: GPUIndexFormat, offset?: number, size?: number): void;
+    draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
+    drawIndexed(indexCount: number, instanceCount?: number, firstIndex?: number, baseVertex?: number, firstInstance?: number): void;
+    drawIndirect(): never;
+    drawIndexedIndirect(): never;
+    setViewport(x: number, y: number, width: number, height: number, minDepth: number, maxDepth: number): void;
+    setScissorRect(x: number, y: number, width: number, height: number): void;
+    setStencilReference(reference: number): void;
+    setBlendConstant(color: GPUColor): void;
+    executeBundles(): never;
+    beginOcclusionQuery(): never;
+    endOcclusionQuery(): never;
+    pushDebugGroup(): void;
+    popDebugGroup(): void;
+    insertDebugMarker(): void;
+    end(): void;
+}
+/** Where a view attaches: its array layer, cube face, or (3D) the pass's depth slice. */
+export declare function layerOf(view: Webgl2TextureView, depthSlice: number): number;
+/** A mip level's extent. */
+export declare function mipSize(size: number, mip: number): number;
+export {};