@godot-scene-web/canvas-effects 0.1.0

package/dist/webgpu.d.mts

@@ -0,0 +1,335 @@
+import { WgslBuiltinOffsets, WgslUniformField } from "@godot-scene-web/effects/shaders";
+import { InstanceBuffer } from "@godot-scene-web/effects";
+
+//#region src/webgpu-pipeline.d.ts
+/** Normative WebGPU flags, stated locally so this module needs no browser host. */
+declare const BUFFER_USAGE: {
+  readonly COPY_DST: 8;
+  readonly UNIFORM: 64;
+};
+declare const SHADER_STAGE: {
+  readonly VERTEX: 1;
+  readonly FRAGMENT: 2;
+};
+/**
+ * Bytes per per-cell uniform slot. 256 is the maximum `minUniformBufferOffsetAlignment` any WebGPU
+ * implementation may report, so a buffer laid out at this pitch is bindable with a dynamic offset
+ * everywhere; the real limit is read off the device and only ever rounds DOWN from here.
+ */
+declare const UNIFORM_SLOT_BYTES = 256;
+/** The first error message from the most recent failed compile/validation (with WGSL line/col when
+ *  the failure was a shader), for diagnostics. Null until something fails. */
+declare function lastPipelineError(): string | null;
+/**
+ * Compile a WGSL module, returning null when the source has an error-severity message.
+ *
+ * Reading `getCompilationInfo()` rather than waiting for pipeline creation is what makes the
+ * message available at all: a module built from bad WGSL is a valid object that only fails later,
+ * inside `createRenderPipeline`, with a generic validation error.
+ */
+declare function compileModule(device: GPUDevice, code: string, label: string, onError?: () => void): Promise<GPUShaderModule | null>;
+/**
+ * Create a render pipeline inside a validation error scope, so a layout/blend/vertex-buffer
+ * mismatch comes back as a message and a null instead of as a surface that draws nothing.
+ */
+declare function createPipeline(device: GPUDevice, descriptor: GPURenderPipelineDescriptor, label: string, onError?: () => void): Promise<GPURenderPipeline | null>;
+/** A uniform bind-group layout with binding 0 as a DYNAMIC-offset uniform buffer — the shape every
+ *  ring in this package binds through. `minBindingSize` must not exceed the size the bind group
+ *  actually binds (the slot, not the buffer), so callers that build their own bind group pass the
+ *  same number to both. */
+declare function uniformBindGroupLayout(device: GPUDevice, visibility?: number, minBindingSize?: number, label?: string): GPUBindGroupLayout;
+/** The per-cell uniform ring: one buffer holding N slots addressed by dynamic offset, so N cells
+ *  cost ONE buffer and one `writeBuffer` per frame instead of N of each. */
+interface UniformRing {
+  buffer: GPUBuffer;
+  layout: GPUBindGroupLayout;
+  bindGroup: GPUBindGroup;
+  /** Slot pitch in BYTES: the dynamic offset for cell i is `i * pitch`. */
+  pitch: number;
+  /** Slot size in BYTES — what the bind group binds, always ≤ `pitch`. */
+  slotBytes: number;
+  /** Slot pitch in FLOATS (`pitch / 4`): cell i's staging window starts at `i * stride`. */
+  stride: number;
+  /** CPU-side mirror of the whole ring, uploaded in one `writeBuffer`. */
+  staging: Float32Array;
+  destroy(): void;
+}
+interface UniformRingOptions {
+  label?: string;
+  /** Reuse a caller-owned layout (e.g. one shared with a pipeline layout) instead of making one. */
+  layout?: GPUBindGroupLayout;
+  visibility?: number;
+}
+declare function createUniformRing(device: GPUDevice, cells: number, slotFloats?: number, options?: UniformRingOptions): UniformRing;
+/** TEST-ONLY: clear the last recorded pipeline/shader error. */
+declare function __resetPipelineErrorForTest(): void;
+//#endregion
+//#region src/particles-webgpu.d.ts
+/** Resolved texture resource supplied by the host. This package never loads URLs or owns images. */
+interface WebgpuParticleTexture {
+  readonly view: GPUTextureView;
+  readonly sampler: GPUSampler;
+}
+interface WebgpuParticleDrawOptions {
+  width: number;
+  height: number;
+  texture: unknown | null;
+  textured: boolean;
+  lutTexture: unknown | null;
+  maskTexture: unknown | null;
+  hframes: number;
+  vframes: number;
+  blendMode: number;
+  alphaFromRed?: boolean;
+  erode?: {
+    threshold: number;
+    softness: number;
+  } | null;
+  uvPolar?: boolean;
+}
+interface WebgpuParticleSurface {
+  readonly context: GPUCanvasContext;
+  readonly textures: {
+    sprite: WebgpuParticleTexture | null;
+    lut: WebgpuParticleTexture | null;
+    mask: WebgpuParticleTexture | null;
+  };
+  readonly onTexturesChanged?: (callback: () => void) => () => void;
+}
+interface WebgpuParticleRendererOptions {
+  readonly device: GPUDevice;
+  readonly format: GPUTextureFormat;
+  readonly readTexturePixels?: (texture: GPUTexture, width: number, height: number) => Promise<Uint8Array>;
+  readonly onPipelineError?: () => void;
+}
+/** Bytes per packed instance record: the shipped `INSTANCE_STRIDE` (10 floats) × 4. Stated as a
+ *  literal because it is what the vertex-buffer layout declares as its `arrayStride` and what every
+ *  attribute offset below is measured in. */
+declare const INSTANCE_STRIDE_BYTES = 40;
+/** Vertex entry point of `PARTICLE_WGSL`. Referenced by the pipeline descriptors, never spelled twice. */
+declare const PARTICLE_VS_ENTRY = "vs_particles";
+/** Fragment entry point for MIX (and every non-additive) blend: premultiplied colour out. */
+declare const PARTICLE_FS_ENTRY = "fs_particles";
+/** Fragment entry point for the ADDITIVE accumulate pass: raw light out, alpha 0. */
+declare const PARTICLE_FS_ADDITIVE_ENTRY = "fs_particles_additive";
+/** Vertex entry point of `ADDITIVE_RESOLVE_WGSL` (a full-target strip). */
+declare const RESOLVE_VS_ENTRY = "vs_resolve";
+/** Fragment entry point of `ADDITIVE_RESOLVE_WGSL`. */
+declare const RESOLVE_FS_ENTRY = "fs_resolve";
+/**
+ * The blend state every non-additive draw uses, and the other half of the premultiply contract in
+ * the module header.
+ *
+ * `one / one-minus-src-alpha` on colour AND alpha: the fragment already carries `rgb * a`, so the
+ * source contributes its light unscaled and the destination is attenuated by the coverage the source
+ * claims — `dst' = src.rgb*src.a + dst*(1-src.a)`, which is what `SRC_ALPHA / ONE_MINUS_SRC_ALPHA`
+ * computes over a straight-alpha source (the GL path's blend). The alpha channel gets the same pair
+ * so the canvas's own alpha accumulates the same way.
+ */
+declare const PREMULTIPLIED_BLEND: GPUBlendState;
+/** The ACCUMULATE pass's blend: `ONE, ONE` on both channels, i.e. `render-webgl`'s
+ *  `blendFactorsFor(1)` — overlapping additive particles SUM their raw light (Godot
+ *  `BLEND_MODE_ADD`) instead of compositing over one another. */
+declare const ADDITIVE_BLEND: GPUBlendState;
+/**
+ * The vertex buffer layout: slot 0 is the static unit-quad corner (stepped per VERTEX), slot 1 is the
+ * packed instance record (stepped per INSTANCE).
+ *
+ * The attribute offsets are the shipped float offsets × 4 — center@0, scale@8, rotation@16,
+ * color@20, frame@36 — i.e. exactly `INSTANCE_ATTRS` in `render-webgl.ts`, in bytes. Exported so a
+ * test can read the stride back without building a device.
+ */
+declare const PARTICLE_VERTEX_BUFFERS: GPUVertexBufferLayout[];
+/**
+ * The instanced particle module — `render-webgl.ts`'s two shader stages, transcribed.
+ *
+ * PER-SYSTEM VALUES ARE UNIFORMS, NOT PIPELINE VARIANTS. `textured`/`lut`/`mask`/`uvPolar` etc. select
+ * branches at runtime out of ONE pipeline, exactly as the GL program's `u_textured`/`u_lut` do — the
+ * alternative (a pipeline per feature combination) is 64 pipelines for a fragment whose branches are
+ * uniform-valued and therefore free of divergence. Sampling inside those branches is legal for two
+ * independent reasons: a branch on a uniform value is UNIFORM CONTROL FLOW (so even
+ * derivative-taking `textureSample` would be allowed), and the samples below use
+ * `textureSampleLevel(..., 0.0)`, which needs no derivatives at all. Level 0 is not an approximation
+ * here: every texture this backend binds is created with a single mip level (see `../webgpu/textures`).
+ */
+declare const PARTICLE_WGSL = "struct Params {\n  viewport: vec2f,       // canvas backing size, device px \u2014 REWRITTEN EVERY DRAW (canvases resize)\n  grid: vec2f,           // hframes, vframes\n  erodeFactors: vec2f,   // threshold, softness\n  textured: u32,\n  lut: u32,\n  alphaFromRed: u32,\n  erode: u32,\n  mask: u32,\n  uvPolar: u32,\n};\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(1) @binding(0) var sprite_tex: texture_2d<f32>;\n@group(1) @binding(1) var sprite_smp: sampler;\n@group(1) @binding(2) var lut_tex: texture_2d<f32>;\n@group(1) @binding(3) var lut_smp: sampler;\n@group(1) @binding(4) var mask_tex: texture_2d<f32>;\n@group(1) @binding(5) var mask_smp: sampler;\n\n// GLSL's `mod` is FLOOR-signed; WGSL's `%` is TRUNC-signed. The flipbook cell index and the polar\n// wrap are both written against GLSL semantics in the shader this ports, so re-derive them rather\n// than swap in an operator that agrees only for positive operands.\nfn godot_mod(x: f32, y: f32) -> f32 {\n  return x - y * floor(x / y);\n}\n\nstruct VsOut {\n  @builtin(position) pos: vec4f,\n  @location(0) uv: vec2f,\n  @location(1) quad: vec2f,\n  @location(2) cell: vec2f,\n  @location(3) color: vec4f,\n};\n\n@vertex\nfn vs_particles(\n  @location(0) corner: vec2f,\n  @location(1) center: vec2f,\n  @location(2) scale: vec2f,\n  @location(3) rotation: f32,\n  @location(4) color: vec4f,\n  @location(5) frame: f32,\n) -> VsOut {\n  let c = cos(rotation);\n  let s = sin(rotation);\n  let rotated = vec2f(corner.x * c - corner.y * s, corner.x * s + corner.y * c);\n  let px = center + rotated * scale;\n  var clip = (px / params.viewport) * 2.0 - 1.0;\n  clip.y = -clip.y;                       // canvas Y-down -> clip Y-up\n  var out: VsOut;\n  out.pos = vec4f(clip, 0.0, 1.0);\n  let uv01 = corner + 0.5;                // 0..1 across the SPRITE quad\n  let cell = vec2f(godot_mod(frame, params.grid.x), floor(frame / params.grid.x));\n  out.uv = (cell + uv01) / params.grid;\n  // The flipbook cell INDEX, so a fragment that re-derives its own sprite-local UV (the polar remap)\n  // can map it back into the same cell instead of over the whole sheet.\n  out.cell = cell;\n  // Quad-local 0..1, INDEPENDENT of the flipbook grid: the untextured dot and the coverage mask are\n  // both measured from this. Deriving them from the atlas-mapped uv put the dot's centre at the\n  // SHEET's centre, so any grid > 1x1 left it off-centre and clipped to a sliver of one cell.\n  out.quad = uv01;\n  out.color = color;\n  return out;\n}\n\nstruct Shaded {\n  col: vec4f,\n  coverage: f32,\n};\n\n// The whole fragment feature set, shared by both entry points below so the mix and additive paths\n// can never disagree about it (in GL they are one shader and a branch).\nfn shade(in: VsOut) -> Shaded {\n  var uv = in.uv;\n  if (params.uvPolar == 1u) {\n    // Godot polar_coordinates(UV, vec2(0.5), 1, 1) (shaders/vfx/_util/polar_coordinates.gdshaderinc):\n    // x = radius from the sprite centre (0..1.41 at the corners), y = the angle mapped to 0..1, both\n    // wrapped \u2014 then RE-WRAPPED INTO THE SAME CELL through in.cell, so a flipbook stays a flipbook.\n    // A radial sheet (common_ring_polar_a) is a RING only through this; sampled flat it is a\n    // vertical BAR.\n    let dir = in.quad - vec2f(0.5);\n    let radius = length(dir) * 2.0;\n    let angle = atan2(dir.y, dir.x) * (1.0 / (3.1416 * 2.0));\n    uv = (in.cell + vec2f(godot_mod(radius, 1.0), godot_mod(angle, 1.0))) / params.grid;\n  }\n  var tex: vec4f;\n  if (params.textured == 1u) {\n    tex = textureSampleLevel(sprite_tex, sprite_smp, uv, 0.0);\n  } else {\n    // Soft round dot when the system has no texture \u2014 measured across the QUAD, not the atlas-mapped\n    // uv, so it stays centred whatever the (meaningless, textureless) grid is.\n    let r = length(in.quad - vec2f(0.5)) * 2.0;\n    tex = vec4f(1.0, 1.0, 1.0, 1.0 - smoothstep(0.7, 1.0, r));\n  }\n  // COVERAGE \u2014 taken PRE-LUT, because the LUT is a colour lookup INDEXED by that same red channel:\n  // reading it afterwards would sample the LUT's own (usually white) output instead of the sheet's\n  // shape. Grayscale VFX sheets are alpha-less PNGs, so tex.a is 1.0 everywhere and the alpha branch\n  // draws a SQUARE.\n  var coverage = select(tex.a, tex.r, params.alphaFromRed == 1u);\n  if (params.lut == 1u) {\n    // Godot's VFX particle-shader family: COLOR = vec4(texture(lut, texture_color.rr).rgb, alpha) *\n    // vertex_color. The sheet is a single-channel MASK, so its own RGB is meaningless; the LUT holds\n    // the real colours. Sampled AFTER the texture/dot resolve so both branches are recoloured, and\n    // the source ALPHA is preserved untouched \u2014 only RGB comes from the LUT.\n    tex = vec4f(textureSampleLevel(lut_tex, lut_smp, vec2f(tex.r, 0.5), 0.0).rgb, tex.a);\n  }\n  if (params.erode == 1u) {\n    // Godot erosion_from_factors(vec2(threshold, softness), coverage) \u2014 a CONSTANT erosion curve,\n    // i.e. the threshold does not sweep over the particle's life. AFTER the LUT, BEFORE the mask.\n    coverage = smoothstep(params.erodeFactors.x, params.erodeFactors.x + params.erodeFactors.y, coverage);\n  }\n  if (params.mask == 1u) {\n    // Godot's mask sampler reads the sprite's own UV, NOT the flipbook cell \u2014 it shapes the whole quad.\n    coverage = coverage * textureSampleLevel(mask_tex, mask_smp, in.quad, 0.0).r;\n  }\n  tex.a = coverage;\n  var out: Shaded;\n  out.col = tex * in.color;\n  out.coverage = coverage;\n  return out;\n}\n\n@fragment\nfn fs_particles(in: VsOut) -> @location(0) vec4f {\n  let col = shade(in).col;\n  // PREMULTIPLIED \u2014 see the module header. Only correct under PREMULTIPLIED_BLEND.\n  return vec4f(col.rgb * col.a, col.a);\n}\n\n@fragment\nfn fs_particles_additive(in: VsOut) -> @location(0) vec4f {\n  // Additive sprites contribute light = colour x alpha (Godot BLEND_MODE_ADD adds src.rgb * src.a to\n  // the framebuffer, so an opaque-black glow background or an alpha-shaped sprite's transparent area\n  // both add nothing). Emit that light RAW and SUM it across particles (ADDITIVE_BLEND, into the\n  // accumulator); the resolve pass converts the per-pixel TOTAL to coverage ONCE. Normalizing per\n  // PARTICLE amplified every faint texel to full brightness and let overlaps clamp to white while\n  // stacking coverage \u2014 a subtle 5-particle fog rendered as an opaque white haze wall.\n  // ALPHA IS 0: the accumulator holds light, not coverage.\n  let shaded = shade(in);\n  return vec4f(shaded.col.rgb * shaded.coverage * in.color.a, 0.0);\n}\n";
+/**
+ * The additive RESOLVE pass: read the summed light out of the accumulator and present it.
+ *
+ * THE ALGEBRA. A premultiplied canvas wants the accumulated light itself: `(light, cov)` composites
+ * to `light + dst*(1-cov)`, with no division at all — and therefore no `cov > 0` guard either, since
+ * the division that would have needed one is gone (at cov = 0 the fragment is (0,0,0,0), which
+ * composites to `dst` exactly). `RESOLVE_FRAGMENT_SRC` in `./render-webgl.ts` is now the same
+ * expression, its canvas being premultiplied too; it used to divide by `cov` for a straight-alpha
+ * canvas and rely on the blit into the node canvas to multiply it back.
+ *
+ * `textureLoad` at integer pixel coordinates, like GL's `texelFetch`: the accumulate pass renders
+ * into the top-left w×h rect of a grow-only accumulator, and WebGPU framebuffer coordinates are
+ * Y-DOWN in both passes, so texel (x, y) is fragment (x, y) with no flip arithmetic anywhere.
+ */
+declare const ADDITIVE_RESOLVE_WGSL = "@group(0) @binding(0) var accum_tex: texture_2d<f32>;\n\n@vertex\nfn vs_resolve(@builtin(vertex_index) index: u32) -> @builtin(position) vec4f {\n  // TRIANGLE_STRIP corner order, matching the particle quad's: (-1,-1) (1,-1) (-1,1) (1,1).\n  var corners = array<vec2f, 4>(\n    vec2f(-1.0, -1.0),\n    vec2f(1.0, -1.0),\n    vec2f(-1.0, 1.0),\n    vec2f(1.0, 1.0)\n  );\n  return vec4f(corners[index], 0.0, 1.0);\n}\n\n@fragment\nfn fs_resolve(@builtin(position) pos: vec4f) -> @location(0) vec4f {\n  let light = textureLoad(accum_tex, vec2i(pos.xy), 0).rgb;\n  let cov = max(light.r, max(light.g, light.b));\n  return vec4f(light, cov);\n}\n";
+/** Per-surface GPU state, supplied with a presentation context and resolved handles by the host. */
+interface WebgpuParticleSurfaceState extends WebgpuParticleSurface {
+  ring: UniformRing;
+  words: Uint32Array;
+  instances: GPUBuffer | null;
+  instanceBytes: number;
+  bindGroup: GPUBindGroup | null;
+  boundViews: [unknown, unknown, unknown];
+  bindGroupDirty: boolean;
+  disposeTextureListener: (() => void) | null;
+}
+/** Construct a renderer after its device program is compiled. Presentation contexts and texture handles stay host-owned. */
+declare function createWebgpuParticleRenderer(options: WebgpuParticleRendererOptions): Promise<WebgpuParticleRenderer | null>;
+declare function peekWebgpuParticleRenderer(options: WebgpuParticleRendererOptions): WebgpuParticleRenderer | null | undefined;
+interface WebgpuParticleRenderer {
+  createSurface(surface: WebgpuParticleSurface): WebgpuParticleSurfaceState;
+  disposeSurface(surface: WebgpuParticleSurfaceState): void;
+  beginFrame(): void;
+  endFrame(): void;
+  clear(surface: WebgpuParticleSurfaceState): void;
+  draw(surface: WebgpuParticleSurfaceState, buffer: InstanceBuffer, opts: WebgpuParticleDrawOptions): void;
+  captureSurface(surface: WebgpuParticleSurfaceState, buffer: InstanceBuffer, opts: WebgpuParticleDrawOptions): Promise<Uint8Array | null>;
+  submits(): number;
+}
+/** TEST-ONLY: drop the device-scope pipelines so a suite can re-probe with a fresh stub device. */
+declare function __resetWebgpuParticleProgramForTest(): void;
+//#endregion
+//#region src/shader-webgpu.d.ts
+declare function createWebgpuShaderBindGroupLayout(device: GPUDevice, label: string, entries: Iterable<GPUBindGroupLayoutEntry>): GPUBindGroupLayout;
+declare function createWebgpuShaderUniformBuffer(device: GPUDevice, label: string, size: number): GPUBuffer;
+declare function createWebgpuShaderBindGroup(device: GPUDevice, label: string, layout: GPUBindGroupLayout, entries: Iterable<GPUBindGroupEntry>): GPUBindGroup;
+interface WebgpuShaderDraw {
+  context?: GPUCanvasContext;
+  target?: GPUTextureView;
+  pipeline: GPURenderPipeline;
+  bindGroup: GPUBindGroup;
+  uniformBuffer: GPUBuffer;
+  uniformBytes: ArrayBuffer | ArrayBufferView;
+  width: number;
+  height: number;
+}
+/** Owns one command encoder per host frame. It never creates contexts or texture handles. */
+declare class WebgpuShaderExecutor {
+  private readonly device;
+  private encoder;
+  private recorded;
+  private implicit;
+  private submitCount;
+  constructor(device: GPUDevice);
+  beginFrame(): void;
+  endFrame(): void;
+  submits(): number;
+  draw(draw: WebgpuShaderDraw): boolean;
+  capture(draw: Omit<WebgpuShaderDraw, "context" | "target" | "width" | "height"> & {
+    width: number;
+    height: number;
+    read: (texture: GPUTexture, width: number, height: number) => Promise<Uint8Array>;
+  }): Promise<Uint8Array | null>;
+  private ensureEncoder;
+  private currentView;
+  private flush;
+}
+//#endregion
+//#region src/webgpu-pack-uniforms.d.ts
+/** A shader parameter's value as the runtime parsed it out of `data-godot-shader-params`: a scalar,
+ *  a vector/array flattened into one number list, or absent (the declared default is used). Kept
+ *  structurally identical to the shader runtime's `ShaderParamValue` so the two cannot drift. */
+type PackedParamValue = number | number[];
+/** The layout half of a `TranspiledWgslShader` — everything `packShaderUniforms` needs and nothing
+ *  else, so a test can hand-build one. */
+interface ShaderUniformLayout {
+  /** Size of the whole struct in bytes (already rounded up to its alignment). */
+  uniformStructSizeBytes: number;
+  builtinOffsets: WgslBuiltinOffsets;
+  uniforms: WgslUniformField[];
+}
+/** The values one render supplies. The built-ins mirror the WebGL backend's uniform writes one for
+ *  one (see `renderNodeGl`), so the two renderers are fed the SAME numbers; the optional ones are
+ *  written only when the shader declared them, which is exactly when the offset exists. */
+interface ShaderUniformValues {
+  /** `_godot_uv_fit` — the fraction of the canvas the fitted texture covers. */
+  uvFit: readonly [number, number];
+  /** `_godot_uv_window` — the node-local sub-rect this canvas covers, [u0,v0,du,dv]. */
+  uvWindow: readonly number[];
+  /** `TIME`, seconds. */
+  time?: number;
+  /** `TEXTURE_PIXEL_SIZE` — 1/texture width, 1/texture height. */
+  texturePixelSize?: readonly [number, number];
+  /** `MODULATE` — the node's colour multiply, RGBA. */
+  modulate?: readonly number[];
+  /** `SCREEN_UV`'s node origin and size within the scene-root viewport. */
+  screenOrigin?: readonly [number, number];
+  screenSize?: readonly [number, number];
+  /** User `shader_parameter/<name>` values, by GODOT name (`WgslUniformField.name`). */
+  params?: Record<string, PackedParamValue | undefined>;
+  /** Godot's own type name per parameter (`PackedColorArray`, …) — the one case where the wire
+   *  format needs re-interpreting; see `PACKED_COLOR_ARRAY` below. */
+  paramKinds?: Record<string, string>;
+}
+/** The staging buffer for one binding: the same bytes seen as floats and as i32s, because one
+ *  uniform struct legitimately holds both. `bytes` is what a `writeBuffer` uploads. */
+interface UniformStaging {
+  bytes: ArrayBuffer;
+  floats: Float32Array;
+  ints: Int32Array;
+}
+/** Allocate a staging block big enough for `sizeBytes` (rounded up to a whole float). */
+declare function createUniformStaging(sizeBytes: number): UniformStaging;
+/**
+ * Write `values` into `staging` at the byte offsets `layout` declares, and return it.
+ *
+ * ZEROED FIRST, deliberately: a uniform whose value disappeared between frames (a param attribute
+ * dropped, a `MODULATE` that stopped applying) must read as 0, not as whatever the previous frame
+ * left in that lane. The struct is small (tens of bytes) and this happens once per binding per
+ * frame, so the clear is not worth optimising away for the class of bug it removes.
+ */
+declare function packShaderUniforms(layout: ShaderUniformLayout, values: ShaderUniformValues, staging?: UniformStaging): UniformStaging;
+//#endregion
+//#region src/webgpu-readback.d.ts
+interface WebgpuReadbackDevice {
+  readonly device: GPUDevice;
+}
+/**
+ * Read `width`×`height` RGBA bytes out of `texture`, tightly packed (`width * 4` bytes per row,
+ * top-down, PREMULTIPLIED alpha as stored — every fragment on this backend emits `vec4f(rgb*a, a)`
+ * under `PREMULTIPLIED_BLEND`, so the bytes in the texture are already multiplied through. A
+ * consumer that needs straight alpha (an encode into a 2D canvas) converts: see
+ * `./still-capture`).
+ *
+ * `texture` must have been created with COPY_SRC usage — a texture that will be read back has to
+ * declare it at creation, and there is no way to add it afterwards.
+ */
+declare function readTexturePixels(shared: WebgpuReadbackDevice, texture: GPUTexture, width: number, height: number): Promise<Uint8Array>;
+//#endregion
+//#region src/webgpu-textures.d.ts
+/** Device-scoped texture allocation and upload primitives. Hosts own decoding and cache keys. */
+declare const WEBGPU_UPLOAD_TEXTURE_USAGE: number;
+interface WebgpuTextureUpload {
+  readonly texture: GPUTexture;
+  readonly width: number;
+  readonly height: number;
+}
+declare function createWebgpuRgbaTexture(device: GPUDevice, width: number, height: number, label?: string): WebgpuTextureUpload;
+declare function uploadWebgpuRgba(device: GPUDevice, target: WebgpuTextureUpload, pixels: Uint8Array | Uint8ClampedArray): void;
+/** Upload a host-decoded external image. The host decides its source and crop. */
+declare function uploadWebgpuExternalImage(device: GPUDevice, target: WebgpuTextureUpload, source: GPUCopyExternalImageSourceInfo): void;
+declare function createWebgpuSampler(device: GPUDevice, opts: {
+  readonly nearest: boolean;
+  readonly repeat: boolean;
+}): GPUSampler;
+declare function destroyWebgpuTexture(texture: GPUTexture): void;
+//#endregion
+//#region src/webgpu.d.ts
+/**
+ * Explicit WebGPU execution entry point.
+ *
+ * Callers supply their device and presentation surface; this
+ * package never creates a canvas, queries the DOM, fetches images, or schedules
+ * animation frames.
+ */
+/** Configure a caller-supplied WebGPU presentation context for premultiplied output. */
+declare function configureWebgpuSurface(context: GPUCanvasContext, device: GPUDevice, format: GPUTextureFormat): void;
+//#endregion
+export { ADDITIVE_BLEND, ADDITIVE_RESOLVE_WGSL, BUFFER_USAGE, INSTANCE_STRIDE_BYTES, PARTICLE_FS_ADDITIVE_ENTRY, PARTICLE_FS_ENTRY, PARTICLE_VERTEX_BUFFERS, PARTICLE_VS_ENTRY, PARTICLE_WGSL, PREMULTIPLIED_BLEND, PackedParamValue, RESOLVE_FS_ENTRY, RESOLVE_VS_ENTRY, SHADER_STAGE, ShaderUniformLayout, ShaderUniformValues, UNIFORM_SLOT_BYTES, UniformRing, UniformRingOptions, UniformStaging, WEBGPU_UPLOAD_TEXTURE_USAGE, WebgpuParticleDrawOptions, WebgpuParticleRenderer, WebgpuParticleRendererOptions, WebgpuParticleSurface, WebgpuParticleSurfaceState, WebgpuParticleTexture, WebgpuReadbackDevice, WebgpuShaderDraw, WebgpuShaderExecutor, WebgpuTextureUpload, __resetPipelineErrorForTest, __resetWebgpuParticleProgramForTest, compileModule, configureWebgpuSurface, createPipeline, createUniformRing, createUniformStaging, createWebgpuParticleRenderer, createWebgpuRgbaTexture, createWebgpuSampler, createWebgpuShaderBindGroup, createWebgpuShaderBindGroupLayout, createWebgpuShaderUniformBuffer, destroyWebgpuTexture, lastPipelineError, packShaderUniforms, peekWebgpuParticleRenderer, readTexturePixels, uniformBindGroupLayout, uploadWebgpuExternalImage, uploadWebgpuRgba };
+//# sourceMappingURL=webgpu.d.mts.map

package/dist/webgpu.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgpu.d.mts","names":[],"sources":["../src/webgpu-pipeline.ts","../src/particles-webgpu.ts","../src/shader-webgpu.ts","../src/webgpu-pack-uniforms.ts","../src/webgpu-readback.ts","../src/webgpu-textures.ts","../src/webgpu.ts"],"mappings":"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"}