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

package/dist/pipeline.d.ts

@@ -0,0 +1,113 @@
+import type { Webgl2PipelineLayout } from './binding.js';
+import type { Webgl2Device } from './device.js';
+import type { GlslTranslation } from './naga.js';
+export declare class Webgl2ShaderModule {
+    readonly id: number;
+    readonly code: string;
+    readonly label: string;
+    constructor(d: GPUShaderModuleDescriptor);
+    /** Answered without translating: pipelines report what doesn't translate or link. */
+    getCompilationInfo(): Promise<{
+        messages: readonly unknown[];
+    }>;
+}
+/** One stage's WGSL and entry point. */
+export interface StageSource {
+    code: string;
+    entry: string;
+}
+/** A uniform block of the program, and the group binding that feeds it. */
+export interface ProgramBlock {
+    group: number;
+    binding: number;
+    point: number;
+    /**
+     * The block's size in GLSL (std140 rounds a block up to 16 bytes; WGSL doesn't round a uniform
+     * struct): a draw fails unless at least this much is bound.
+     */
+    size: number;
+}
+/** A combined sampler of the program: its texture unit, texture binding and sampler binding. */
+export interface ProgramSampler {
+    unit: number;
+    group: number;
+    binding: number;
+    /** The sampler's group and binding, or -1 for `texelFetch` reads (no sampler). */
+    samplerGroup: number;
+    samplerBinding: number;
+}
+export interface VertexAttribute {
+    location: number;
+    size: number;
+    type: number;
+    normalized: boolean;
+    integer: boolean;
+    offset: number;
+}
+export interface VertexBufferLayout {
+    stride: number;
+    instanced: boolean;
+    attributes: VertexAttribute[];
+}
+interface BlendState {
+    enabled: boolean;
+    colorOp: number;
+    colorSrc: number;
+    colorDst: number;
+    alphaOp: number;
+    alphaSrc: number;
+    alphaDst: number;
+}
+export declare class Webgl2RenderPipeline {
+    readonly id: number;
+    readonly label: string;
+    readonly layout: Webgl2PipelineLayout;
+    program: WebGLProgram | null;
+    readonly blocks: ProgramBlock[];
+    readonly samplers: ProgramSampler[];
+    firstInstance: WebGLUniformLocation | null;
+    /** The first instance the program's uniform holds (-1: not set yet). */
+    firstInstanceValue: number;
+    /** Reads `@builtin(vertex_index)`: a nonzero baseVertex would shift it. */
+    readonly vertexIndex: boolean;
+    readonly vertexBuffers: VertexBufferLayout[];
+    readonly topology: number;
+    readonly cull: number;
+    readonly frontFace: number;
+    readonly depthTest: boolean;
+    readonly depthWrite: boolean;
+    readonly depthFunc: number;
+    readonly depthBias: number;
+    readonly depthSlope: number;
+    readonly stencil: boolean;
+    readonly stencilFront: [number, number, number, number];
+    readonly stencilBack: [number, number, number, number];
+    readonly stencilReadMask: number;
+    readonly stencilWriteMask: number;
+    readonly blends: BlendState[];
+    readonly masks: number[];
+    /** Every target blends and masks alike: one set of GL calls covers them all. */
+    readonly uniformTargets: boolean;
+    readonly targets: number;
+    readonly sampleCount: number;
+    private readonly device;
+    private readonly descriptor;
+    constructor(device: Webgl2Device, d: GPURenderPipelineDescriptor);
+    /** The WGSL and entry point of each stage, to translate. */
+    stages(): {
+        vertex: StageSource;
+        fragment: StageSource | undefined;
+    };
+    /** Compiles both stages' GLSL and starts linking the program. */
+    build(v: GlslTranslation, f: GlslTranslation | undefined): WebGLProgram;
+    /** The shaders and translations of a program still linking. */
+    private link;
+    /** Whether the driver has finished linking (KHR_parallel_shader_compile), or can't say. */
+    linked(): boolean;
+    /** After linking: the status, and the binding points and units from the reflection. */
+    finish(): void;
+    getBindGroupLayout(index: number): unknown;
+}
+/** The entry point a stage runs when the descriptor names none: the first of that stage. */
+export declare function entryPointOf(code: string, stage: 'vertex' | 'fragment'): string;
+export {};

package/dist/pipeline.js

@@ -0,0 +1,294 @@
+import { unsupported } from "./errors.js";
+import { GL } from "./gl.js";
+import { COMPARE } from "./resources.js";
+let nextId = 1;
+class Webgl2ShaderModule {
+  id = nextId++;
+  code;
+  label;
+  constructor(d) {
+    this.code = d.code;
+    this.label = d.label ?? "";
+  }
+  /** Answered without translating: pipelines report what doesn't translate or link. */
+  getCompilationInfo() {
+    return Promise.resolve({ messages: [] });
+  }
+}
+const FACTOR = {
+  zero: GL.ZERO,
+  one: GL.ONE,
+  src: GL.SRC_COLOR,
+  "one-minus-src": GL.ONE_MINUS_SRC_COLOR,
+  "src-alpha": GL.SRC_ALPHA,
+  "one-minus-src-alpha": GL.ONE_MINUS_SRC_ALPHA,
+  dst: GL.DST_COLOR,
+  "one-minus-dst": GL.ONE_MINUS_DST_COLOR,
+  "dst-alpha": GL.DST_ALPHA,
+  "one-minus-dst-alpha": GL.ONE_MINUS_DST_ALPHA,
+  "src-alpha-saturated": GL.SRC_ALPHA_SATURATE,
+  constant: GL.CONSTANT_COLOR,
+  "one-minus-constant": GL.ONE_MINUS_CONSTANT_COLOR
+};
+const OPERATION = {
+  add: GL.FUNC_ADD,
+  subtract: GL.FUNC_SUBTRACT,
+  "reverse-subtract": GL.FUNC_REVERSE_SUBTRACT,
+  min: GL.MIN,
+  max: GL.MAX
+};
+const STENCIL_OP = {
+  keep: GL.KEEP,
+  zero: GL.ZERO,
+  replace: GL.REPLACE,
+  invert: GL.INVERT,
+  "increment-clamp": GL.INCR,
+  "decrement-clamp": GL.DECR,
+  "increment-wrap": GL.INCR_WRAP,
+  "decrement-wrap": GL.DECR_WRAP
+};
+const VERTEX_FORMAT = {
+  float32: [1, GL.FLOAT, false, false],
+  float32x2: [2, GL.FLOAT, false, false],
+  float32x3: [3, GL.FLOAT, false, false],
+  float32x4: [4, GL.FLOAT, false, false],
+  float16x2: [2, GL.HALF_FLOAT, false, false],
+  float16x4: [4, GL.HALF_FLOAT, false, false],
+  uint32: [1, GL.UNSIGNED_INT, false, true],
+  uint32x2: [2, GL.UNSIGNED_INT, false, true],
+  uint32x3: [3, GL.UNSIGNED_INT, false, true],
+  uint32x4: [4, GL.UNSIGNED_INT, false, true],
+  sint32: [1, GL.INT, false, true],
+  sint32x2: [2, GL.INT, false, true],
+  sint32x3: [3, GL.INT, false, true],
+  sint32x4: [4, GL.INT, false, true],
+  uint16x2: [2, GL.UNSIGNED_SHORT, false, true],
+  uint16x4: [4, GL.UNSIGNED_SHORT, false, true],
+  unorm16x2: [2, GL.UNSIGNED_SHORT, true, false],
+  unorm16x4: [4, GL.UNSIGNED_SHORT, true, false],
+  uint8x2: [2, GL.UNSIGNED_BYTE, false, true],
+  uint8x4: [4, GL.UNSIGNED_BYTE, false, true],
+  unorm8x2: [2, GL.UNSIGNED_BYTE, true, false],
+  unorm8x4: [4, GL.UNSIGNED_BYTE, true, false],
+  snorm8x4: [4, GL.BYTE, true, false]
+};
+const EMPTY_FRAGMENT = "#version 300 es\nprecision highp float;\nvoid main() {}\n";
+class Webgl2RenderPipeline {
+  id = nextId++;
+  label;
+  layout;
+  program = null;
+  blocks = [];
+  samplers = [];
+  firstInstance = null;
+  /** The first instance the program's uniform holds (-1: not set yet). */
+  firstInstanceValue = -1;
+  /** Reads `@builtin(vertex_index)`: a nonzero baseVertex would shift it. */
+  vertexIndex;
+  vertexBuffers;
+  topology;
+  cull;
+  frontFace;
+  depthTest;
+  depthWrite;
+  depthFunc;
+  depthBias;
+  depthSlope;
+  stencil;
+  stencilFront;
+  stencilBack;
+  stencilReadMask;
+  stencilWriteMask;
+  blends;
+  masks;
+  /** Every target blends and masks alike: one set of GL calls covers them all. */
+  uniformTargets;
+  targets;
+  sampleCount;
+  device;
+  descriptor;
+  constructor(device, d) {
+    this.device = device;
+    this.descriptor = d;
+    this.label = d.label ?? "";
+    if (d.layout === "auto") throw unsupported(`make "${this.label}" with layout 'auto'`);
+    this.layout = d.layout;
+    const vs = d.vertex.module;
+    this.vertexIndex = /@builtin\(\s*vertex_index\s*\)/.test(vs.code);
+    this.vertexBuffers = (d.vertex.buffers ?? []).map((b) => ({
+      stride: b?.arrayStride ?? 0,
+      instanced: b?.stepMode === "instance",
+      attributes: (b ? [...b.attributes] : []).map((a) => {
+        const f = VERTEX_FORMAT[a.format];
+        if (!f) throw unsupported(`read the vertex format ${a.format}`);
+        return {
+          location: a.shaderLocation,
+          size: f[0],
+          type: f[1],
+          normalized: f[2],
+          integer: f[3],
+          offset: a.offset
+        };
+      })
+    }));
+    const p = d.primitive ?? {};
+    const topology = p.topology ?? "triangle-list";
+    this.topology = topology === "triangle-list" ? GL.TRIANGLES : topology === "triangle-strip" ? GL.TRIANGLE_STRIP : topology === "line-list" ? GL.LINES : topology === "line-strip" ? GL.LINE_STRIP : GL.POINTS;
+    this.cull = p.cullMode === "front" ? GL.FRONT : p.cullMode === "back" ? GL.BACK : 0;
+    this.frontFace = (p.frontFace ?? "ccw") === "ccw" ? GL.CW : GL.CCW;
+    const ds = d.depthStencil;
+    this.depthTest = ds !== void 0 && ((ds.depthCompare ?? "always") !== "always" || ds.depthWriteEnabled === true);
+    this.depthWrite = ds?.depthWriteEnabled === true;
+    this.depthFunc = COMPARE[ds?.depthCompare ?? "always"];
+    this.depthBias = ds?.depthBias ?? 0;
+    this.depthSlope = ds?.depthBiasSlopeScale ?? 0;
+    const face = (s) => [
+      COMPARE[s?.compare ?? "always"],
+      STENCIL_OP[s?.failOp ?? "keep"],
+      STENCIL_OP[s?.depthFailOp ?? "keep"],
+      STENCIL_OP[s?.passOp ?? "keep"]
+    ];
+    this.stencilFront = face(ds?.stencilFront);
+    this.stencilBack = face(ds?.stencilBack);
+    this.stencilReadMask = ds?.stencilReadMask ?? 255;
+    this.stencilWriteMask = ds?.stencilWriteMask ?? 255;
+    this.stencil = ds !== void 0 && (ds.format === "stencil8" || ds.format.includes("stencil")) && (ds.stencilFront !== void 0 || ds.stencilBack !== void 0);
+    if (d.multisample?.alphaToCoverageEnabled)
+      throw unsupported(`use alpha to coverage ("${this.label}")`);
+    this.sampleCount = d.multisample?.count ?? 1;
+    const targets = d.fragment ? [...d.fragment.targets] : [];
+    this.targets = targets.length;
+    this.blends = targets.map((t) => {
+      const b = t?.blend;
+      return {
+        enabled: b !== void 0,
+        colorOp: OPERATION[b?.color.operation ?? "add"],
+        colorSrc: FACTOR[b?.color.srcFactor ?? "one"],
+        colorDst: FACTOR[b?.color.dstFactor ?? "zero"],
+        alphaOp: OPERATION[b?.alpha.operation ?? "add"],
+        alphaSrc: FACTOR[b?.alpha.srcFactor ?? "one"],
+        alphaDst: FACTOR[b?.alpha.dstFactor ?? "zero"]
+      };
+    });
+    this.masks = targets.map((t) => t?.writeMask ?? 15);
+    const same = (a, b) => a.enabled === b.enabled && a.colorOp === b.colorOp && a.colorSrc === b.colorSrc && a.colorDst === b.colorDst && a.alphaOp === b.alphaOp && a.alphaSrc === b.alphaSrc && a.alphaDst === b.alphaDst;
+    this.uniformTargets = this.blends.every(
+      (b, i) => same(b, this.blends[0]) && this.masks[i] === this.masks[0]
+    );
+  }
+  /** The WGSL and entry point of each stage, to translate. */
+  stages() {
+    const d = this.descriptor;
+    const vs = d.vertex.module;
+    const fs = d.fragment?.module;
+    return {
+      vertex: { code: vs.code, entry: d.vertex.entryPoint ?? entryPointOf(vs.code, "vertex") },
+      fragment: fs && d.fragment ? { code: fs.code, entry: d.fragment.entryPoint ?? entryPointOf(fs.code, "fragment") } : void 0
+    };
+  }
+  /** Compiles both stages' GLSL and starts linking the program. */
+  build(v, f) {
+    const gl = this.device.gl;
+    const program = gl.createProgram();
+    const shader = (type, source) => {
+      const s = gl.createShader(type);
+      gl.shaderSource(s, source);
+      gl.compileShader(s);
+      gl.attachShader(program, s);
+      return s;
+    };
+    const vsShader = shader(GL.VERTEX_SHADER, v.glsl);
+    const fsShader = shader(GL.FRAGMENT_SHADER, f?.glsl ?? EMPTY_FRAGMENT);
+    gl.linkProgram(program);
+    this.program = program;
+    this.link = { vs: vsShader, fs: fsShader, v, f };
+    return program;
+  }
+  /** The shaders and translations of a program still linking. */
+  link;
+  /** Whether the driver has finished linking (KHR_parallel_shader_compile), or can't say. */
+  linked() {
+    if (!this.device.caps.parallelCompile || !this.program) return true;
+    return this.device.gl.getProgramParameter(this.program, GL.COMPLETION_STATUS_KHR);
+  }
+  /** After linking: the status, and the binding points and units from the reflection. */
+  finish() {
+    const gl = this.device.gl;
+    const program = this.program;
+    const link = this.link;
+    this.link = void 0;
+    if (!gl.getProgramParameter(program, GL.LINK_STATUS)) {
+      const log = [
+        gl.getShaderInfoLog(link.vs),
+        gl.getShaderInfoLog(link.fs),
+        gl.getProgramInfoLog(program)
+      ].filter(Boolean).join("\n");
+      gl.deleteProgram(program);
+      this.program = null;
+      throw new Error(`GLSL for "${this.label}" didn't link: ${log}`);
+    }
+    gl.deleteShader(link.vs);
+    gl.deleteShader(link.fs);
+    const points = /* @__PURE__ */ new Map();
+    for (const u of [...link.v.uniforms, ...link.f?.uniforms ?? []]) {
+      const index = gl.getUniformBlockIndex(program, u.name);
+      if (index === 4294967295) continue;
+      const key = `${u.group}:${u.binding}`;
+      const size = gl.getActiveUniformBlockParameter(
+        program,
+        index,
+        GL.UNIFORM_BLOCK_DATA_SIZE
+      );
+      let point = points.get(key);
+      if (point === void 0) {
+        point = points.size;
+        points.set(key, point);
+        this.blocks.push({ group: u.group, binding: u.binding, point, size });
+      } else {
+        const block = this.blocks[point];
+        block.size = Math.max(block.size, size);
+      }
+      gl.uniformBlockBinding(program, index, point);
+    }
+    gl.useProgram(program);
+    const units = /* @__PURE__ */ new Map();
+    for (const t of [...link.v.textures, ...link.f?.textures ?? []]) {
+      const location = gl.getUniformLocation(program, t.name);
+      if (!location) continue;
+      const key = `${t.group}:${t.binding}:${t.sampler ? t.sampler.join(":") : "-"}`;
+      let unit = units.get(key);
+      if (unit === void 0) {
+        unit = units.size;
+        units.set(key, unit);
+        this.samplers.push({
+          unit,
+          group: t.group,
+          binding: t.binding,
+          samplerGroup: t.sampler ? t.sampler[0] : -1,
+          samplerBinding: t.sampler ? t.sampler[1] : -1
+        });
+      }
+      gl.uniform1i(location, unit);
+    }
+    if (units.size > this.device.caps.combinedUnits - 1) {
+      throw new Error(
+        `"${this.label}" samples ${units.size} textures; this device binds ${this.device.caps.combinedUnits - 1}`
+      );
+    }
+    this.firstInstance = link.v.firstInstance ? gl.getUniformLocation(program, "naga_vs_first_instance") : null;
+    this.device.state.forgetProgram();
+  }
+  getBindGroupLayout(index) {
+    return this.layout.groups[index];
+  }
+}
+function entryPointOf(code, stage) {
+  const m = new RegExp(`@${stage}\\s+fn\\s+([A-Za-z_]\\w*)`).exec(code);
+  if (!m) throw new Error(`No @${stage} entry point`);
+  return m[1];
+}
+export {
+  Webgl2RenderPipeline,
+  Webgl2ShaderModule,
+  entryPointOf
+};

package/dist/present.d.ts

@@ -0,0 +1,18 @@
+import { Webgl2Texture } from './resources.js';
+/** The canvas context for `canvas`: one per canvas, as `getContext` gives. */
+export declare function canvasContext(canvas: HTMLCanvasElement | OffscreenCanvas): Webgl2CanvasContext;
+export declare class Webgl2CanvasContext {
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    private device;
+    private configuration;
+    private texture;
+    private target;
+    private readonly read;
+    constructor(canvas: HTMLCanvasElement | OffscreenCanvas);
+    configure(configuration: GPUCanvasConfiguration): void;
+    getConfiguration(): GPUCanvasConfiguration | null;
+    unconfigure(): void;
+    getCurrentTexture(): Webgl2Texture;
+    /** @internal Shows `texture` on the canvas. */
+    present(texture: Webgl2Texture): void;
+}

package/dist/present.js

@@ -0,0 +1,108 @@
+import { TextureUsage } from "./constants.js";
+import { unsupported } from "./errors.js";
+import { Attachments } from "./fbo.js";
+import { GL } from "./gl.js";
+import { Webgl2Texture } from "./resources.js";
+const contexts = /* @__PURE__ */ new WeakMap();
+function canvasContext(canvas) {
+  let context = contexts.get(canvas);
+  if (!context) {
+    context = new Webgl2CanvasContext(canvas);
+    contexts.set(canvas, context);
+  }
+  return context;
+}
+class Webgl2CanvasContext {
+  canvas;
+  device;
+  configuration;
+  texture;
+  target;
+  read = new Attachments();
+  constructor(canvas) {
+    this.canvas = canvas;
+  }
+  configure(configuration) {
+    if (configuration.format !== "rgba8unorm") {
+      throw unsupported(
+        `present ${configuration.format}`,
+        "Configure the canvas with getPreferredCanvasFormat() ('rgba8unorm' on WebGL2)."
+      );
+    }
+    this.texture?.destroy();
+    this.texture = void 0;
+    this.device = configuration.device;
+    this.configuration = configuration;
+  }
+  getConfiguration() {
+    return this.configuration ?? null;
+  }
+  unconfigure() {
+    this.texture?.destroy();
+    this.texture = void 0;
+    this.device = void 0;
+    this.configuration = void 0;
+  }
+  getCurrentTexture() {
+    const device = this.device;
+    const configuration = this.configuration;
+    if (!device || !configuration)
+      throw new Error("getCurrentTexture: the canvas context is not configured");
+    const width = Math.max(1, this.canvas.width);
+    const height = Math.max(1, this.canvas.height);
+    let texture = this.texture;
+    if (!texture || texture.destroyed || texture.width !== width || texture.height !== height) {
+      texture?.destroy();
+      texture = new Webgl2Texture(device, {
+        label: "canvas",
+        size: [width, height],
+        format: "rgba8unorm",
+        usage: (configuration.usage ?? TextureUsage.RENDER_ATTACHMENT) | TextureUsage.RENDER_ATTACHMENT
+      });
+      texture.surface = this;
+      this.texture = texture;
+    }
+    return texture;
+  }
+  /** @internal Shows `texture` on the canvas. */
+  present(texture) {
+    const device = this.device;
+    if (!device || device.isLost || texture !== this.texture) return;
+    const gl = device.gl;
+    const glCanvas = device.canvas;
+    if (!glCanvas) return;
+    const w = texture.width;
+    const h = texture.height;
+    const own = glCanvas === this.canvas;
+    if (!own) {
+      if (glCanvas.width !== w) glCanvas.width = w;
+      if (glCanvas.height !== h) glCanvas.height = h;
+    }
+    this.read.reset();
+    this.read.color(0, texture, 0, 0);
+    gl.bindFramebuffer(GL.READ_FRAMEBUFFER, device.fbos.get(this.read));
+    gl.bindFramebuffer(GL.DRAW_FRAMEBUFFER, null);
+    device.state.enable(GL.SCISSOR_TEST, false);
+    gl.blitFramebuffer(0, 0, w, h, 0, h, w, 0, GL.COLOR_BUFFER_BIT, GL.NEAREST);
+    const opaque = this.configuration?.alphaMode !== "premultiplied";
+    if (opaque) {
+      gl.bindFramebuffer(GL.FRAMEBUFFER, null);
+      device.state.prepareClear();
+      gl.colorMask(false, false, false, true);
+      gl.clearColor(0, 0, 0, 1);
+      gl.clear(GL.COLOR_BUFFER_BIT);
+      gl.colorMask(true, true, true, true);
+    }
+    if (own) return;
+    if (this.target === void 0) {
+      this.target = this.canvas.getContext("2d", { alpha: !opaque });
+    }
+    if (!this.target) return;
+    this.target.globalCompositeOperation = "copy";
+    this.target.drawImage(glCanvas, 0, 0);
+  }
+}
+export {
+  Webgl2CanvasContext,
+  canvasContext
+};

package/dist/queries.d.ts

@@ -0,0 +1,41 @@
+import type { Webgl2Device } from './device.js';
+import type { Webgl2Buffer } from './resources.js';
+export declare const TIME_ELAPSED_EXT = 35007;
+export declare const GPU_DISJOINT_EXT = 36795;
+/** Queries resolved into a buffer, waiting for results: pair k's begin/end at `offset + 16k`. */
+export interface QueryRead {
+    offset: number;
+    queries: (WebGLQuery | null)[];
+}
+export declare class Webgl2QuerySet {
+    readonly type: GPUQueryType;
+    readonly count: number;
+    label: string;
+    /** The query recording each pair this frame (one per pass), until resolved. */
+    private readonly pairs;
+    private readonly device;
+    private destroyed;
+    constructor(device: Webgl2Device, descriptor: GPUQuerySetDescriptor);
+    /** @internal Replay: starts timing pair `pair` (a pass with timestamp writes begins). */
+    begin(pair: number): void;
+    /** @internal Replay: the timed pass ended. */
+    end(): void;
+    /** @internal Replay: hands queries `first` to `first + count` to `buffer` at `offset`. */
+    resolve(first: number, count: number, buffer: Webgl2Buffer, offset: number): void;
+    destroy(): void;
+}
+/** Query objects, reused: a frame times a few dozen passes, every frame. */
+export declare class QueryPool {
+    private readonly free;
+    private readonly gl;
+    constructor(gl: WebGL2RenderingContext);
+    take(): WebGLQuery | null;
+    give(query: WebGLQuery): void;
+    /** Forgets the pool (the context was lost: its queries went with it). */
+    clear(): void;
+}
+/**
+ * Waits for `buffer`'s pending query results and writes them into `bytes` (the mapped range, which
+ * starts at `mapOffset`), then returns the queries to the pool.
+ */
+export declare function finishQueryReads(device: Webgl2Device, buffer: Webgl2Buffer, bytes: Uint8Array, mapOffset: number): Promise<void>;

package/dist/queries.js

@@ -0,0 +1,110 @@
+const TIME_ELAPSED_EXT = 35007;
+const GPU_DISJOINT_EXT = 36795;
+const QUERY_RESULT = 34918;
+const QUERY_RESULT_AVAILABLE = 34919;
+const WAIT_MS = 2e3;
+class Webgl2QuerySet {
+  type = "timestamp";
+  count;
+  label;
+  /** The query recording each pair this frame (one per pass), until resolved. */
+  pairs;
+  device;
+  destroyed = false;
+  constructor(device, descriptor) {
+    this.device = device;
+    this.count = descriptor.count;
+    this.label = descriptor.label ?? "";
+    this.pairs = new Array(Math.ceil(descriptor.count / 2)).fill(null);
+  }
+  /** @internal Replay: starts timing pair `pair` (a pass with timestamp writes begins). */
+  begin(pair) {
+    if (this.destroyed) return;
+    const query = this.device.queries.take();
+    if (!query) return;
+    this.device.gl.beginQuery(TIME_ELAPSED_EXT, query);
+    this.pairs[pair] = query;
+  }
+  /** @internal Replay: the timed pass ended. */
+  end() {
+    this.device.gl.endQuery(TIME_ELAPSED_EXT);
+  }
+  /** @internal Replay: hands queries `first` to `first + count` to `buffer` at `offset`. */
+  resolve(first, count, buffer, offset) {
+    const from = first >> 1;
+    const to = first + count + 1 >> 1;
+    const queries = [];
+    for (let p = from; p < to; p++) {
+      queries.push(this.pairs[p] ?? null);
+      this.pairs[p] = null;
+    }
+    buffer.queryReads.push({ offset, queries });
+  }
+  destroy() {
+    this.destroyed = true;
+    for (let p = 0; p < this.pairs.length; p++) {
+      const q = this.pairs[p];
+      if (q) this.device.queries.give(q);
+      this.pairs[p] = null;
+    }
+  }
+}
+class QueryPool {
+  free = [];
+  gl;
+  constructor(gl) {
+    this.gl = gl;
+  }
+  take() {
+    return this.free.pop() ?? this.gl.createQuery();
+  }
+  give(query) {
+    this.free.push(query);
+  }
+  /** Forgets the pool (the context was lost: its queries went with it). */
+  clear() {
+    this.free.length = 0;
+  }
+}
+const waitTick = () => new Promise((resolve) => setTimeout(resolve, 4));
+async function finishQueryReads(device, buffer, bytes, mapOffset) {
+  const reads = buffer.queryReads.splice(0);
+  if (reads.length === 0) return;
+  const gl = device.gl;
+  const deadline = performance.now() + WAIT_MS;
+  const ready = () => reads.every(
+    (r) => r.queries.every((q) => !q || gl.getQueryParameter(q, QUERY_RESULT_AVAILABLE) === true)
+  );
+  while (!device.isLost && !ready() && performance.now() < deadline) await waitTick();
+  const lost = device.isLost;
+  const disjoint = !lost && gl.getParameter(GPU_DISJOINT_EXT) === true;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (const read of reads) {
+    let at = device.timerAt;
+    for (let k = 0; k < read.queries.length; k++) {
+      const q = read.queries[k];
+      const pos = read.offset - mapOffset + k * 16;
+      let begin = 0n;
+      let end = 0n;
+      if (q && !lost && !disjoint && gl.getQueryParameter(q, QUERY_RESULT_AVAILABLE) === true) {
+        const elapsed = BigInt(gl.getQueryParameter(q, QUERY_RESULT));
+        begin = at;
+        end = at + elapsed;
+        at = end;
+        device.timerAt = end;
+      }
+      if (pos >= 0 && pos + 16 <= bytes.byteLength) {
+        view.setBigUint64(pos, begin, true);
+        view.setBigUint64(pos + 8, end, true);
+      }
+      if (q && !lost) device.queries.give(q);
+    }
+  }
+}
+export {
+  GPU_DISJOINT_EXT,
+  QueryPool,
+  TIME_ELAPSED_EXT,
+  Webgl2QuerySet,
+  finishQueryReads
+};

package/dist/queue.d.ts

@@ -0,0 +1,13 @@
+import type { Webgl2CommandBuffer } from './commands.js';
+import type { Webgl2Device } from './device.js';
+import type { Webgl2Buffer } from './resources.js';
+export declare class Webgl2Queue {
+    label: string;
+    private readonly device;
+    constructor(device: Webgl2Device);
+    submit(buffers: Iterable<Webgl2CommandBuffer>): void;
+    onSubmittedWorkDone(): Promise<undefined>;
+    writeBuffer(buffer: Webgl2Buffer, offset: number, data: BufferSource, dataOffset?: number, size?: number): void;
+    writeTexture(destination: GPUTexelCopyTextureInfo, data: BufferSource, layout: GPUTexelCopyBufferLayout, size: GPUExtent3D): void;
+    copyExternalImageToTexture(source: GPUCopyExternalImageSourceInfo, destination: GPUCopyExternalImageDestInfo, size: GPUExtent3D): void;
+}