@solidrt/flux-types 0.0.39 → 0.0.40

package/gui/gpu.d.ts

@@ -7,19 +7,54 @@
 // Layering: compileShader/linkProgram are the raw GL primitives (complete
 // sources, explicit header opt-in); createShader/createPipeline are fused
 // conveniences (compile + link + target in one call, curated preamble).
+//
+// Sampling is a per-texture property declared at creation: every create path
+// accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
+// defaults linear + clamp for every origin). The state follows the id
+// everywhere it is sampled - shader passes and `<texture>` display alike -
+// and survives id-stable resizes. It cannot be changed after creation. No
+// mipmaps exist.
+//
+// Compositing several targets is a render-tree job, not a shader one: stack
+// `<texture>` elements and set their `blendMode` (the full Skia set, e.g.
+// "plus" for an additive pass over a base pass) instead of writing a pass that
+// samples both. WITHIN one pipeline draw, `blend: "add"` accumulates
+// overlapping geometry additively; anything else (a fragment target, or a
+// pipeline without the option) draws with GL blending disabled and overwrites.
 
 declare module "flux:gpu" {
+  /**
+   * Shader uniform values by name. A number drives a scalar uniform (`float`,
+   * or `int`/`bool`, truncated); a flat number array drives a typed uniform
+   * whose declared GLSL type sets the expected length: 2/3/4 for
+   * `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`. Dispatch follows the
+   * shader's own declaration; a value whose length does not fit it is skipped
+   * with a runtime warning, as is a name with no active uniform.
+   */
+  export type ShaderParams = Record<string, number | number[]>
+  /** Magnification/minification filter; "linear" (default) or hard-pixel "nearest". */
+  export type FilterMode = "linear" | "nearest"
+  /** Sampling outside 0..1: "clamp" (default, extend edge pixels) or "repeat" (tile). */
+  export type WrapMode = "clamp" | "repeat"
+  /**
+   * Per-texture sampling, declared at creation and fixed for the id's
+   * lifetime. Applies wherever the texture is sampled: shader/pipeline
+   * sampler2D inputs AND `<texture src>` display (a "nearest" texture
+   * upscales with hard pixels on screen - the pixel-art path). `wrap` only
+   * matters to shaders sampling outside 0..1; the display draw never tiles.
+   */
+  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode }
   /**
    * Create an immutable texture from an RGBA8 pixel buffer (exactly
    * width*height*4 bytes). Returns the texture id.
    */
-  export function createTexture(data: Uint8Array, width: number, height: number): number
+  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions): number
   /**
    * Create a texture intended to be updated later via {@link uploadTexture}. The
    * seed buffer must hold at least one frame (width*height*4 bytes) and may hold
    * more (uploadTexture selects a frame by offset).
    */
-  export function createMutableTexture(data: Uint8Array, width: number, height: number): number
+  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions): number
   /**
    * Replace a mutable texture's pixels. `data` may hold several frames; `offset`
    * (default 0) selects which frame to upload.
@@ -45,19 +80,35 @@ declare module "flux:gpu" {
   export function destroyTexture(id: number): void
   /**
    * Compile a GLSL ES fragment shader into an offscreen texture of the given
-   * size. `params` sets float uniforms by name; `textures` binds sampler2D
-   * uniforms to texture ids. Returns the resulting texture id. The fused
+   * size. `params` sets uniforms by name (see {@link ShaderParams} for the
+   * value shapes); `textures` binds sampler2D uniforms to texture ids - any
+   * texture id, including another shader/pipeline target's output. Bound
+   * targets are live dependencies: when a source re-renders (its params,
+   * geometry, or data change), every target sampling it re-renders too,
+   * transitively through chains, before the next frame or readback - no
+   * per-frame uniform write is needed to keep a chain current. Returns the resulting texture id. The fused
    * convenience: one call compiles a program and creates a target over it,
    * and the program lives and dies with the target. To share one compile
    * across targets (or hold a program with no target yet), use the raw layer:
    * {@link compileShader} + {@link linkProgram} + {@link createShaderTarget}.
+   *
+   * The preamble (`#version 300 es`, precision, `vUV`, `iResolution`, `iTime`,
+   * `fragColor`) is injected only into sources that do not declare their own
+   * `#version` line. A source that starts with `#version 300 es` is compiled
+   * exactly as written, so a shader with its own uniform names (a port from
+   * elsewhere) needs no rewriting and no drop to the raw layer. The built-in
+   * vertex stage still supplies `vUV` to a complete source; declare
+   * `in vec2 vUV;` yourself to read it. Same rule on {@link createPipeline}.
+   * A complete source may also declare `iResolution` as vec3 (the Shadertoy
+   * shape); it is then filled as `(w, h, 1.0)`.
    */
   export function createShader(
     fragmentSrc: string,
     width: number,
     height: number,
-    params?: Record<string, number>,
+    params?: ShaderParams,
     textures?: Record<string, number>,
+    opts?: SamplerOptions,
   ): number
   /**
    * Compile a single shader stage from raw GLSL ES: the primitive under
@@ -108,15 +159,17 @@ declare module "flux:gpu" {
     width: number,
     height: number,
     opts?: {
-      params?: Record<string, number>
+      params?: ShaderParams
       textures?: Record<string, number>
       attributes?: VertexAttribute[]
       buffer?: number
       topology?: Topology
       vertexCount?: number
       depth?: boolean
+      depthWrite?: boolean
+      blend?: BlendMode
       clearColor?: [number, number, number, number]
-    },
+    } & SamplerOptions,
   ): number
   /**
    * Destroy a linked program by id. Targets created from it are unaffected:
@@ -125,16 +178,20 @@ declare module "flux:gpu" {
    * immediately.
    */
   export function destroyProgram(id: number): void
-  /** Update a shader texture's float uniforms by name and re-render it. */
-  export function setShaderParams(id: number, params: Record<string, number>): void
+  /**
+   * Update a shader texture's uniforms by name and re-render it (see
+   * {@link ShaderParams} for the value shapes).
+   */
+  export function setShaderParams(id: number, params: ShaderParams): void
   /**
    * Rebind a shader texture's sampler2D inputs by uniform name and re-render
    * it with its last-applied params - the sampler analog of
    * {@link setShaderParams}. Bindings not named keep their current source, so
    * a single input can be retargeted (post-process source swap, ping-pong
    * between two data textures) without recompiling the shader. Throws if the
-   * shader or a source texture id is unknown, or a sampler would source the
-   * shader's own target.
+   * shader or a source texture id is unknown, or a binding would create a
+   * sampling cycle among targets (binding a shader's own target is the
+   * shortest case).
    */
   export function setShaderTextures(id: number, textures: Record<string, number>): void
   /**
@@ -146,6 +203,17 @@ declare module "flux:gpu" {
   export function setShaderSize(id: number, width: number, height: number): void
 
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
+  /**
+   * Blending for a pipeline's own draw. "none" (default) overwrites:
+   * overlapping geometry resolves by depth or draw order. "add" accumulates
+   * (glBlendFunc(ONE, ONE)): order-independent, so geometry needs no sorting
+   * - the additive half of translucency (point splats, glow passes). A
+   * depth-tested additive pass usually pairs with `depthWrite: false`; with
+   * writes on, unsorted geometry depth-rejects its own later fragments and
+   * accumulation becomes draw-order-dependent. That pairing is the app's to
+   * state - neither option implies the other.
+   */
+  export type BlendMode = "none" | "add"
   /**
    * One float attribute of an interleaved vertex. The attribute list's order
    * defines the byte layout; locations are resolved by name against the
@@ -161,8 +229,13 @@ declare module "flux:gpu" {
    * `buffer` (a {@link createBuffer} id); omit both for attributeless
    * rendering via gl_VertexID. `vertexCount` defaults to the whole buffer
    * (buffer size / vertex stride). With `depth: true` the pipeline gets a
-   * private depth buffer, cleared and tested on every render. The target is
-   * cleared to `clearColor` (default transparent black) before each draw.
+   * private depth buffer, cleared and tested on every render; `depthWrite:
+   * false` (requires `depth: true`) keeps the test but stops the draw from
+   * writing depth. `blend` sets the draw's own blending (see
+   * {@link BlendMode}); an additive pass over a depth buffer is
+   * `{ depth: true, blend: "add", depthWrite: false }`, stated explicitly.
+   * The target is cleared to `clearColor` (default transparent black) before
+   * each draw.
    * Returns a texture id: display it with `<texture src>`, drive uniforms via
    * the `params` prop or {@link setShaderParams}, destroy with
    * {@link destroyTexture}.
@@ -173,15 +246,17 @@ declare module "flux:gpu" {
     width: number,
     height: number,
     opts?: {
-      params?: Record<string, number>
+      params?: ShaderParams
       textures?: Record<string, number>
       attributes?: VertexAttribute[]
       buffer?: number
       topology?: Topology
       vertexCount?: number
       depth?: boolean
+      depthWrite?: boolean
+      blend?: BlendMode
       clearColor?: [number, number, number, number]
-    },
+    } & SamplerOptions,
   ): number
 
   /**
@@ -206,7 +281,12 @@ declare module "flux:gpu" {
   /**
    * Capture a render-tree node's subtree into a new GPU texture, resolving once
    * it has been rendered on the next paint pass. The node must be attached to
-   * the live tree (a detached node is never painted, so its capture rejects).
+   * the live tree (an unmounted node is never painted, so its capture rejects)
+   * and paint a non-zero box. A laid-out node captures its layout box. A `d-*`
+   * node has no layout box - that is what detached means - so it captures its
+   * painted box instead: its own `w`/`h` when set, else the nearest laid-out
+   * ancestor's box (the same box the render tree reports for it), with its
+   * `x`/`y` paint offset mapped to the texture origin.
    * Rendered at the current display scale, so `width`/`height` are the texture's
    * actual pixel dimensions (ceil(logicalSize * displayScale)), not logical
    * points. Each call returns an independent id you must {@link destroyTexture}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",