vireglass 2.1.0 → 2.3.0

package/dist/web/index.d.cts

@@ -43,6 +43,42 @@ type VireGlassSceneDrawer = (ctx: CanvasRenderingContext2D, width: number, heigh
  *  on a phone, and an element of the same size looked completely different on the lab bench
  *  than on a device. */
 density: number) => void;
+/** The target a `VireGlassBackdropPass` must finish its frame in — the FBO wraps `contentTexture`
+ *  itself, so drawing into it needs no readback: the very texture the lens samples gets the pixels
+ *  directly. */
+type VireGlassBackdropTarget = {
+    /** Owned by the renderer — the FBO wrapping `contentTexture` itself, recreated on `resize` and
+     *  freed in `destroy`. The pass must not delete it, and must not hold onto it past the call:
+     *  the object may be gone or pointing at a different texture by the next `render()`. */
+    framebuffer: WebGLFramebuffer;
+    width: number;
+    height: number;
+};
+/**
+ * Alternative to `scene`: draws the backdrop with a GPU pass, in this same WebGL2 context, straight
+ * into the texture the lens samples — no offscreen 2D canvas, no `texSubImage2D` readback. The
+ * renderer doesn't know or care what's drawn; a fluid sim, a video frame, anything that ends up as
+ * pixels.
+ *
+ * ORIENTATION CONTRACT. `contentTexture` carries the same layout the `scene` path has always
+ * produced: uploaded from a 2D canvas without a Y flip, so texel row 0 (`v≈0`) is the scene's TOP
+ * row (see `BLIT_FRAGMENT_SOURCE` below) — and that row sits at `gl_FragCoord.y = 0` in this FBO,
+ * the window-coordinate BOTTOM, not the top. A pass that copies an ordinary top-row-first image
+ * (one loaded the normal way, via `texImage2D` from a canvas or an `<img>`) straight across with
+ * `texture(src, gl_FragCoord.xy / vec2(target.width, target.height))` reproduces it correctly,
+ * with no flip of its own. A pass that instead treats INCREASING y as its own "up" — the natural
+ * convention for a physical simulation — must flip before this final write, or its top ends up
+ * stored as the scene's bottom and appears upside down once the lens samples it.
+ *
+ * The pass may render through as many of its own FBOs first as it likes (a multi-step simulation)
+ * and leave the GL context in whatever state suits it; it must finish by drawing into
+ * `target.framebuffer` at `viewport(0, 0, target.width, target.height)`. The renderer puts back
+ * every piece of state its own remaining steps depend on right after — framebuffer, viewport,
+ * blend, scissor, depth/stencil/cull, the vertex array binding, the active texture unit, and the
+ * `UNPACK_*` pixel-store flags used to upload `iconMask`/`colorLayer` — so the pass is free to
+ * change any of it without arranging its own cleanup.
+ */
+type VireGlassBackdropPass = (gl: WebGL2RenderingContext, target: VireGlassBackdropTarget) => void;
 /** One glass element in the frame. Each has its own material — that's how they're compared side by side. */
 type VireGlassPiece = {
     optics: VireGlassOptics;
@@ -83,7 +119,14 @@ type VireGlassRenderOptions = {
     density: number;
     debug: VireGlassDebugMode;
     pieces: readonly VireGlassPiece[];
-    scene: VireGlassSceneDrawer;
+    /** CPU-side backdrop: draws into an offscreen 2D canvas, uploaded via `texSubImage2D`. Exactly
+     *  one of `scene`/`backdrop` is required — `render()` throws if both or neither are given — see
+     *  `backdrop` for the GPU alternative. */
+    scene?: VireGlassSceneDrawer;
+    /** GPU-side backdrop: draws straight into the texture the lens samples, in this context, no
+     *  readback. Exactly one of `scene`/`backdrop` is required — see `VireGlassBackdropPass` for the
+     *  orientation contract it must honor. */
+    backdrop?: VireGlassBackdropPass | null;
     /** Canvas offset under stationary elements, device-px. */
     offsetX?: number;
     offsetY?: number;
@@ -116,8 +159,51 @@ type VireGlassRenderResult = {
 type VireGlassRenderer = {
     resize(widthPx: number, heightPx: number): void;
     render(options: VireGlassRenderOptions): VireGlassRenderResult;
+    /** GPU time of the last `render()` call, milliseconds, via
+     *  `EXT_disjoint_timer_query_webgl2`. `null` when the extension is unavailable or the sample
+     *  came back disjoint — never an error either way. */
+    getLastGpuMs(): number | null;
     destroy(): void;
 };
 declare function createVireGlassRenderer(canvas: HTMLCanvasElement): VireGlassRenderer;
 
-export { PROBE_GRID_HEIGHT, PROBE_GRID_WIDTH, type Probe, type ProbeRect, type ProbeStats, type VireGlassPiece, type VireGlassRenderOptions, type VireGlassRenderResult, type VireGlassRenderer, type VireGlassSceneDrawer, createProbe, createVireGlassRenderer };
+/** The same trick as in `scripts/check-glsl.mjs`: three vertices with no buffer, indexed by
+ *  `gl_VertexID`. One vertex shader works for EVERY pass of the pipeline, because each fragment
+ *  shader pulls its own coordinate from `gl_FragCoord`. */
+declare const FULLSCREEN_TRIANGLE_VERTEX_SOURCE = "#version 300 es\nconst vec2 VG_POS[3] = vec2[3](vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0));\nvoid main() {\n  gl_Position = vec4(VG_POS[gl_VertexID], 0.0, 1.0);\n}\n";
+declare function compileShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
+declare function createProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string): WebGLProgram;
+/** Draws the fullscreen triangle with the current program. No attributes — the vertices are
+ *  baked into the shader, so even a VAO isn't needed. */
+declare function drawFullscreenTriangle(gl: WebGL2RenderingContext): void;
+type TextureOptions = {
+    width: number;
+    height: number;
+    /** RGBA8 by default; the probe needs float when it needs more than 8 bits of precision. */
+    internalFormat?: number;
+    format?: number;
+    type?: number;
+    /** CLAMP_TO_EDGE by default. A simulation with a periodic domain (a tiling pattern, a torus)
+     *  wants REPEAT on its own textures instead — applied to both S and T, there's no case here
+     *  that wants them to differ. */
+    wrap?: number;
+};
+/**
+ * General-purpose texture allocator: LINEAR on MIN and MAG, no mipmaps, CLAMP_TO_EDGE by default.
+ * Used throughout `web/` for `contentTexture` and the probe's downsample buffer, and public so a
+ * `VireGlassBackdropPass` can build its own textures the same way. LINEAR rather than NEAREST
+ * because Skia's `.eval` is bilinear by default — NEAREST would break the disc gather into
+ * pixel-stepped bands (spec §4); a pass with different needs overrides `internalFormat`/`format`/
+ * `type`/`wrap` directly.
+ */
+declare function createTexture(gl: WebGL2RenderingContext, options: TextureOptions): WebGLTexture;
+type UniformValue = number | readonly number[];
+/** One cache per program: `getUniformLocation` is a name lookup, and every piece re-sets every
+ *  uniform every frame. */
+declare function locationCache(gl: WebGL2RenderingContext, program: WebGLProgram): (name: string) => WebGLUniformLocation | null;
+declare function setUniform(gl: WebGL2RenderingContext, loc: WebGLUniformLocation | null, value: UniformValue): void;
+declare function createFramebuffer(gl: WebGL2RenderingContext, texture: WebGLTexture): WebGLFramebuffer;
+/** The one texture unit any pipeline pass needs here — a bind with no extra slot bookkeeping. */
+declare function bindTextureAt(gl: WebGL2RenderingContext, unit: number, texture: WebGLTexture, program: WebGLProgram, uniformName: string): void;
+
+export { FULLSCREEN_TRIANGLE_VERTEX_SOURCE, PROBE_GRID_HEIGHT, PROBE_GRID_WIDTH, type Probe, type ProbeRect, type ProbeStats, type TextureOptions, type UniformValue, type VireGlassBackdropPass, type VireGlassBackdropTarget, type VireGlassPiece, type VireGlassRenderOptions, type VireGlassRenderResult, type VireGlassRenderer, type VireGlassSceneDrawer, bindTextureAt, compileShader, createFramebuffer, createProbe, createProgram, createTexture, createVireGlassRenderer, drawFullscreenTriangle, locationCache, setUniform };

package/dist/web/index.d.ts

@@ -43,6 +43,42 @@ type VireGlassSceneDrawer = (ctx: CanvasRenderingContext2D, width: number, heigh
  *  on a phone, and an element of the same size looked completely different on the lab bench
  *  than on a device. */
 density: number) => void;
+/** The target a `VireGlassBackdropPass` must finish its frame in — the FBO wraps `contentTexture`
+ *  itself, so drawing into it needs no readback: the very texture the lens samples gets the pixels
+ *  directly. */
+type VireGlassBackdropTarget = {
+    /** Owned by the renderer — the FBO wrapping `contentTexture` itself, recreated on `resize` and
+     *  freed in `destroy`. The pass must not delete it, and must not hold onto it past the call:
+     *  the object may be gone or pointing at a different texture by the next `render()`. */
+    framebuffer: WebGLFramebuffer;
+    width: number;
+    height: number;
+};
+/**
+ * Alternative to `scene`: draws the backdrop with a GPU pass, in this same WebGL2 context, straight
+ * into the texture the lens samples — no offscreen 2D canvas, no `texSubImage2D` readback. The
+ * renderer doesn't know or care what's drawn; a fluid sim, a video frame, anything that ends up as
+ * pixels.
+ *
+ * ORIENTATION CONTRACT. `contentTexture` carries the same layout the `scene` path has always
+ * produced: uploaded from a 2D canvas without a Y flip, so texel row 0 (`v≈0`) is the scene's TOP
+ * row (see `BLIT_FRAGMENT_SOURCE` below) — and that row sits at `gl_FragCoord.y = 0` in this FBO,
+ * the window-coordinate BOTTOM, not the top. A pass that copies an ordinary top-row-first image
+ * (one loaded the normal way, via `texImage2D` from a canvas or an `<img>`) straight across with
+ * `texture(src, gl_FragCoord.xy / vec2(target.width, target.height))` reproduces it correctly,
+ * with no flip of its own. A pass that instead treats INCREASING y as its own "up" — the natural
+ * convention for a physical simulation — must flip before this final write, or its top ends up
+ * stored as the scene's bottom and appears upside down once the lens samples it.
+ *
+ * The pass may render through as many of its own FBOs first as it likes (a multi-step simulation)
+ * and leave the GL context in whatever state suits it; it must finish by drawing into
+ * `target.framebuffer` at `viewport(0, 0, target.width, target.height)`. The renderer puts back
+ * every piece of state its own remaining steps depend on right after — framebuffer, viewport,
+ * blend, scissor, depth/stencil/cull, the vertex array binding, the active texture unit, and the
+ * `UNPACK_*` pixel-store flags used to upload `iconMask`/`colorLayer` — so the pass is free to
+ * change any of it without arranging its own cleanup.
+ */
+type VireGlassBackdropPass = (gl: WebGL2RenderingContext, target: VireGlassBackdropTarget) => void;
 /** One glass element in the frame. Each has its own material — that's how they're compared side by side. */
 type VireGlassPiece = {
     optics: VireGlassOptics;
@@ -83,7 +119,14 @@ type VireGlassRenderOptions = {
     density: number;
     debug: VireGlassDebugMode;
     pieces: readonly VireGlassPiece[];
-    scene: VireGlassSceneDrawer;
+    /** CPU-side backdrop: draws into an offscreen 2D canvas, uploaded via `texSubImage2D`. Exactly
+     *  one of `scene`/`backdrop` is required — `render()` throws if both or neither are given — see
+     *  `backdrop` for the GPU alternative. */
+    scene?: VireGlassSceneDrawer;
+    /** GPU-side backdrop: draws straight into the texture the lens samples, in this context, no
+     *  readback. Exactly one of `scene`/`backdrop` is required — see `VireGlassBackdropPass` for the
+     *  orientation contract it must honor. */
+    backdrop?: VireGlassBackdropPass | null;
     /** Canvas offset under stationary elements, device-px. */
     offsetX?: number;
     offsetY?: number;
@@ -116,8 +159,51 @@ type VireGlassRenderResult = {
 type VireGlassRenderer = {
     resize(widthPx: number, heightPx: number): void;
     render(options: VireGlassRenderOptions): VireGlassRenderResult;
+    /** GPU time of the last `render()` call, milliseconds, via
+     *  `EXT_disjoint_timer_query_webgl2`. `null` when the extension is unavailable or the sample
+     *  came back disjoint — never an error either way. */
+    getLastGpuMs(): number | null;
     destroy(): void;
 };
 declare function createVireGlassRenderer(canvas: HTMLCanvasElement): VireGlassRenderer;
 
-export { PROBE_GRID_HEIGHT, PROBE_GRID_WIDTH, type Probe, type ProbeRect, type ProbeStats, type VireGlassPiece, type VireGlassRenderOptions, type VireGlassRenderResult, type VireGlassRenderer, type VireGlassSceneDrawer, createProbe, createVireGlassRenderer };
+/** The same trick as in `scripts/check-glsl.mjs`: three vertices with no buffer, indexed by
+ *  `gl_VertexID`. One vertex shader works for EVERY pass of the pipeline, because each fragment
+ *  shader pulls its own coordinate from `gl_FragCoord`. */
+declare const FULLSCREEN_TRIANGLE_VERTEX_SOURCE = "#version 300 es\nconst vec2 VG_POS[3] = vec2[3](vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0));\nvoid main() {\n  gl_Position = vec4(VG_POS[gl_VertexID], 0.0, 1.0);\n}\n";
+declare function compileShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
+declare function createProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string): WebGLProgram;
+/** Draws the fullscreen triangle with the current program. No attributes — the vertices are
+ *  baked into the shader, so even a VAO isn't needed. */
+declare function drawFullscreenTriangle(gl: WebGL2RenderingContext): void;
+type TextureOptions = {
+    width: number;
+    height: number;
+    /** RGBA8 by default; the probe needs float when it needs more than 8 bits of precision. */
+    internalFormat?: number;
+    format?: number;
+    type?: number;
+    /** CLAMP_TO_EDGE by default. A simulation with a periodic domain (a tiling pattern, a torus)
+     *  wants REPEAT on its own textures instead — applied to both S and T, there's no case here
+     *  that wants them to differ. */
+    wrap?: number;
+};
+/**
+ * General-purpose texture allocator: LINEAR on MIN and MAG, no mipmaps, CLAMP_TO_EDGE by default.
+ * Used throughout `web/` for `contentTexture` and the probe's downsample buffer, and public so a
+ * `VireGlassBackdropPass` can build its own textures the same way. LINEAR rather than NEAREST
+ * because Skia's `.eval` is bilinear by default — NEAREST would break the disc gather into
+ * pixel-stepped bands (spec §4); a pass with different needs overrides `internalFormat`/`format`/
+ * `type`/`wrap` directly.
+ */
+declare function createTexture(gl: WebGL2RenderingContext, options: TextureOptions): WebGLTexture;
+type UniformValue = number | readonly number[];
+/** One cache per program: `getUniformLocation` is a name lookup, and every piece re-sets every
+ *  uniform every frame. */
+declare function locationCache(gl: WebGL2RenderingContext, program: WebGLProgram): (name: string) => WebGLUniformLocation | null;
+declare function setUniform(gl: WebGL2RenderingContext, loc: WebGLUniformLocation | null, value: UniformValue): void;
+declare function createFramebuffer(gl: WebGL2RenderingContext, texture: WebGLTexture): WebGLFramebuffer;
+/** The one texture unit any pipeline pass needs here — a bind with no extra slot bookkeeping. */
+declare function bindTextureAt(gl: WebGL2RenderingContext, unit: number, texture: WebGLTexture, program: WebGLProgram, uniformName: string): void;
+
+export { FULLSCREEN_TRIANGLE_VERTEX_SOURCE, PROBE_GRID_HEIGHT, PROBE_GRID_WIDTH, type Probe, type ProbeRect, type ProbeStats, type TextureOptions, type UniformValue, type VireGlassBackdropPass, type VireGlassBackdropTarget, type VireGlassPiece, type VireGlassRenderOptions, type VireGlassRenderResult, type VireGlassRenderer, type VireGlassSceneDrawer, bindTextureAt, compileShader, createFramebuffer, createProbe, createProgram, createTexture, createVireGlassRenderer, drawFullscreenTriangle, locationCache, setUniform };