@solidrt/flux-types 0.0.44 → 0.0.45

package/gui/gpu.d.ts

@@ -7,11 +7,14 @@
 // ids (-> destroyRenderPipeline).
 // Layering: compileShader/linkProgram are the raw GL primitives (complete
 // sources, explicit header opt-in); createRenderPipeline pairs a program with
-// draw state (topology, blend, depth, vertex layout - how it draws);
+// draw state (topology, blend, cull, depth, vertex layout - how it draws);
 // createShaderTarget builds a texture-backed target over a pipeline (size,
-// buffer, uniforms, clear - where it draws). createShaderTexture/
-// createPipelineTexture are fused conveniences (compile + link + pipeline +
-// target in one call, curated preamble) - named for what they return.
+// buffer, uniforms, clear - where it draws); createDrawTarget holds an
+// ordered, mutable LIST of such draws in one target (addDraw/removeDraw +
+// per-entry setters, sharing one depth buffer) - the multi-pass render pass.
+// createShaderTexture/createPipelineTexture are fused conveniences (compile +
+// link + pipeline + target in one call, curated preamble) - named for what
+// they return.
 //
 // Sampling is a per-texture property declared at creation: every create path
 // accepts `{ filter?, wrap? }` ("linear"/"nearest", "clamp"/"repeat";
@@ -81,6 +84,13 @@ declare module "flux:gpu" {
   export type ProgramId = number & { readonly __program: unique symbol }
   /** The render-pipeline id space ({@link createRenderPipeline}); see {@link TextureId} for the brand model. */
   export type RenderPipelineId = number & { readonly __renderPipeline: unique symbol }
+  /**
+   * A draw-entry handle on a draw target ({@link addDraw}); see
+   * {@link TextureId} for the brand model. Target-scoped and stable: an id
+   * keeps naming its entry across other adds and removes (never an index),
+   * and a removed entry's id errors from then on rather than aliasing.
+   */
+  export type DrawId = number & { readonly __draw: unique symbol }
   /**
    * Shader uniform values by name. A number drives a scalar uniform (`float`,
    * or `int`/`bool`, truncated); a flat number array drives a typed uniform
@@ -273,19 +283,36 @@ declare module "flux:gpu" {
    * (its own id space, like programs and buffers - not a texture id): the
    * pipeline state object of every modern GPU API. The pipeline owns HOW its
    * targets draw - `attributes` (the interleaved vertex layout; omit for
-   * attributeless rendering via gl_VertexID), `topology`, `blend`, `depth`,
-   * `depthWrite` (`false` requires `depth: true`) - while each target brings
-   * its own size, buffer, uniforms, and clear. Creating a pipeline compiles
-   * nothing, and many pipelines may share one program. The vocabulary is
-   * validated here, so a bad word throws at this call site. Free with
+   * attributeless rendering via gl_VertexID), `instanceAttributes` (the
+   * per-instance layout, fetched from each entry's `instanceBuffer` - see
+   * the option's doc), `topology`, `blend`, `cull`, `depth`, `depthWrite`
+   * (`false` requires `depth: true`) - while each target brings its own
+   * size, buffers, uniforms, and clear. Both layouts share one attribute
+   * namespace (each name is one `in` of the vertex stage), so a name in
+   * both lists throws. Creating a pipeline compiles nothing, and many
+   * pipelines may share one program. The vocabulary is validated here, so a
+   * bad word throws at this call site. Free with
    * {@link destroyRenderPipeline}; the program is yours and outlives it.
    */
   export function createRenderPipeline(
     program: ProgramId,
     opts?: {
       attributes?: VertexAttribute[]
+      /**
+       * One interleaved record per INSTANCE (WebGPU's `stepMode:
+       * "instance"`): these attributes read from the entry's
+       * `instanceBuffer` and advance per instance instead of per vertex, so
+       * every vertex of instance N sees record N - real per-instance state
+       * (offsets, colors, a packed transform) with no `gl_InstanceID`
+       * arithmetic. Declaring any makes `instanceBuffer` required on every
+       * entry drawn with this pipeline. A mat4 per instance is its four
+       * vec4 columns, reassembled in the shader (attributes have no matrix
+       * formats, as in WebGPU).
+       */
+      instanceAttributes?: VertexAttribute[]
       topology?: Topology
       blend?: BlendMode
+      cull?: CullMode
       depth?: boolean
       depthWrite?: boolean
     } & LabelOption,
@@ -305,13 +332,15 @@ declare module "flux:gpu" {
    * {@link setShaderSize}, destroy with {@link destroyTexture}). Many targets
    * may share one pipeline, and creating a target compiles nothing. `buffer`
    * supplies the concrete vertex buffer the pipeline's attribute layout
-   * describes (required when the pipeline declares attributes); the
-   * {@link DrawRange} keys pick what is drawn from it - `vertexCount`
+   * describes (required when the pipeline declares attributes), and
+   * `instanceBuffer` the per-instance records its `instanceAttributes`
+   * describe (required exactly when it declares any); the
+   * {@link DrawRange} keys pick what is drawn from them - `vertexCount`
    * defaults to the rest of the buffer from `firstVertex` on,
-   * `instanceCount` repeats the range - and a vertex fetch past the
-   * buffer's end throws here. A fullscreen pass over an attributeless
-   * pipeline is `vertexCount: 3` with a covering-triangle vertex stage.
-   * Draw-state keys
+   * `instanceCount` to one instance per instance-buffer record (1 without
+   * one) - and a fetch past either buffer's end throws here. A fullscreen
+   * pass over an attributeless pipeline is `vertexCount: 3` with a
+   * covering-triangle vertex stage. Draw-state keys
    * (`attributes`, `topology`, `blend`, `depth`, `depthWrite`) belong to the
    * pipeline and throw here. `params` and `textures` are validated against
    * the pipeline's program (see {@link ShaderParams}).
@@ -341,10 +370,11 @@ declare module "flux:gpu" {
     opts?: {
       textures?: Record<string, TextureId>
       buffer?: BufferId
+      instanceBuffer?: BufferId
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
-    } & DrawRange &
+    } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
   ): TextureId
@@ -398,24 +428,75 @@ declare module "flux:gpu" {
    */
   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
-   * vertex shader's `in` declarations.
+   * Face culling for a pipeline's draws. "none" (default) rasters both faces
+   * - the two-sided fallback open surfaces need. "back" discards faces wound
+   * away from the camera, halving a closed mesh's fragment work; "front"
+   * discards the other set (shadow and inside-out tricks). The winding rule
+   * is WebGPU's, fixed: counter-clockwise AS DISPLAYED (screen coordinates,
+   * y down) = front. Measured after every flip, so it just works: a mesh
+   * exported counter-clockwise-front for a y-up world, drawn through a
+   * standard right-handed camera (looking down -z) with the usual y
+   * negation for display, culls correctly with "back". If "back" shows you
+   * the mesh's inside anyway, the winding reaching the screen is mirrored -
+   * either the exporter winds clockwise, or the hand-rolled projection is
+   * left-handed (the classic: camera looking toward +z without mirroring
+   * x). Fix the rig, flip the exporter, or use "front".
+   */
+  export type CullMode = "none" | "back" | "front"
+  /**
+   * One float attribute of an interleaved record - a vertex of `attributes`
+   * or an instance record of `instanceAttributes`. The list's order defines
+   * the byte layout; locations are resolved by name against the vertex
+   * shader's `in` declarations.
    */
   export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
   /**
    * A pipeline target's draw as data, WebGPU-style: `firstVertex` +
    * `vertexCount` pick the vertex range `[firstVertex, firstVertex +
    * vertexCount)` of the buffer, `instanceCount` draws that range as N
-   * instances (`glDrawArraysInstanced`) told apart by `gl_InstanceID`. All
-   * keys optional: at create, `firstVertex` defaults to 0, `vertexCount` to
-   * the rest of the buffer and `instanceCount` to 1 (the plain draw); in
-   * {@link setDraw}, absent keys keep their current value. `instanceCount: 0`
-   * draws nothing - a cheap off switch. Two GL facts worth knowing:
-   * `gl_VertexID` includes `firstVertex` (as in WebGPU), and `gl_InstanceID`
-   * always counts from 0 - ES 3.0 has no base instance.
+   * instances (`glDrawArraysInstanced`) told apart by `gl_InstanceID` (and
+   * by their `instanceAttributes` records, when the pipeline declares any).
+   * All keys optional: at create, `firstVertex` defaults to 0, `vertexCount`
+   * to the rest of the buffer, and `instanceCount` to one instance per
+   * record of the entry's `instanceBuffer` - 1 without one, the plain draw;
+   * in {@link setDraw}, absent keys keep their current value.
+   * `instanceCount: 0` draws nothing - a cheap off switch. With an instance
+   * buffer bound, `instanceCount` is bounds-checked against it like every
+   * fetch (instances 0..N-1 each read one record). Two GL facts worth
+   * knowing: `gl_VertexID` includes `firstVertex` (as in WebGPU), and
+   * `gl_InstanceID` always counts from 0 - ES 3.0 has no base instance.
    */
   export type DrawRange = { firstVertex?: number; vertexCount?: number; instanceCount?: number }
+  /**
+   * The element type of an index buffer: "uint16" halves index bandwidth and
+   * addresses meshes up to 65535 vertices, "uint32" covers the rest -
+   * WebGPU's two formats exactly.
+   */
+  export type IndexFormat = "uint16" | "uint32"
+  /**
+   * An entry's index binding: any {@link createBuffer} buffer plus its
+   * element type (the buffer is typeless bytes, so the format must be
+   * declared - as WebGPU does at setIndexBuffer). One buffer kind serves
+   * both roles; there is no separate index-buffer create. With a binding
+   * present the draw is `glDrawElements`: vertices are fetched through the
+   * index VALUES, so shared vertices are stored (and shaded) once, and the
+   * range speaks {@link IndexRange} instead of {@link DrawRange}. The
+   * index-buffer fetch is bounds-checked like every range; the index values
+   * themselves are not checked against the vertex buffer (that would mean
+   * reading them back) - an out-of-range index is the same undefined fetch
+   * raw GL gives you.
+   */
+  export type IndexBinding = { indexBuffer: BufferId; indexFormat: IndexFormat }
+  /**
+   * The index-counted spelling of a draw range, for indexed entries
+   * (WebGPU's drawIndexed vocabulary): `firstIndex` + `indexCount` pick the
+   * range of the INDEX buffer, `instanceCount` as in {@link DrawRange}.
+   * Same defaults and merge rules; the vertex-named keys throw on an
+   * indexed entry (and these throw on a plain one), so a range never
+   * silently counts the wrong thing. `gl_VertexID` reads the index value;
+   * there is no base vertex (ES 3.0, like ES 3.0's missing base instance).
+   */
+  export type IndexRange = { firstIndex?: number; indexCount?: number; instanceCount?: number }
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
@@ -426,11 +507,14 @@ declare module "flux:gpu" {
    * row of the target and +1 the bottom, so camera-up geometry must negate y
    * (or fold the flip into its projection) to display up. `attributes`
    * describes one interleaved vertex in `buffer` (a {@link createBuffer} id);
-   * omit both for attributeless rendering via gl_VertexID. The
-   * {@link DrawRange} keys pick what is drawn: `vertexCount` defaults to the
-   * rest of the buffer from `firstVertex` on, `instanceCount` draws the
-   * range as N instances told apart by `gl_InstanceID`; a vertex fetch past
-   * the buffer's end throws. With
+   * omit both for attributeless rendering via gl_VertexID.
+   * `instanceAttributes` describes one per-instance record in
+   * `instanceBuffer` (see {@link createRenderPipeline}; declare both or
+   * neither). The {@link DrawRange} keys pick what is drawn: `vertexCount`
+   * defaults to the rest of the buffer from `firstVertex` on,
+   * `instanceCount` draws the range as N instances told apart by
+   * `gl_InstanceID` and defaults to one per instance-buffer record; a fetch
+   * past either buffer's end throws. With
    * `depth: true` the pipeline gets a 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
@@ -455,14 +539,18 @@ declare module "flux:gpu" {
       textures?: Record<string, TextureId>
       attributes?: VertexAttribute[]
       buffer?: BufferId
+      /** See {@link createRenderPipeline}'s `instanceAttributes`. */
+      instanceAttributes?: VertexAttribute[]
+      instanceBuffer?: BufferId
       topology?: Topology
       depth?: boolean
       depthWrite?: boolean
       blend?: BlendMode
+      cull?: CullMode
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
-    } & DrawRange &
+    } & (DrawRange | (IndexBinding & IndexRange)) &
       SamplerOptions &
       LabelOption,
   ): TextureId
@@ -496,9 +584,118 @@ declare module "flux:gpu" {
    * buffer size) - the out-of-bounds draw GL itself never checks; a target
    * without vertex fetch (attributeless) accepts any non-negative range.
    * (On a manual target nothing renders here; the range applies at its next
-   * {@link renderTarget}.)
+   * {@link renderTarget}.) An indexed target takes the {@link IndexRange}
+   * spelling instead, bounds-checked against its index buffer; the pair
+   * that does not match the target's mode throws.
+   */
+  export function setDraw(id: TextureId, draw: DrawRange | IndexRange): void
+  /**
+   * Create a draw target: a render target whose contents are an ordered,
+   * mutable LIST of draws - one render clears once, then executes every
+   * entry in list order into the same storage. The multi-pass shape of every
+   * 3D API (N meshes, N pipelines, one shared depth buffer), retained: where
+   * WebGPU re-encodes a render pass every frame, this target holds the pass
+   * as state and re-renders on demand. Entries are added and removed at any
+   * time ({@link addDraw}/{@link removeDraw}) and updated per entry
+   * ({@link setDrawParams}, {@link setDrawTextures}, {@link setDrawRange}).
+   *
+   * `depth: true` gives the target its own depth storage, shared by every
+   * entry and cleared once per render - this is what makes cross-entry
+   * occlusion work. It is the storage half of the depth story; whether an
+   * entry tests/writes depth is its pipeline's `depth`/`depthWrite` state,
+   * and adding a depth-testing pipeline to a target without storage throws.
+   *
+   * The render contract is unchanged: the list is input data like params, so
+   * "render twice = render once" still holds and the default `render:
+   * "auto"` target re-renders exactly when its entries or their inputs
+   * change - a static scene costs zero passes, however many entries it
+   * holds, and one render is ONE pass however many entries it draws.
+   * `render: "manual"` and `loadOp: "load"` compose exactly as on
+   * {@link createShaderTarget}. With no entries a render is the clear alone.
+   * Returns a texture id (display, resize, destroy like any target; entries
+   * die with it).
+   */
+  export function createDrawTarget(
+    width: number,
+    height: number,
+    opts?: {
+      depth?: boolean
+      clearColor?: [number, number, number, number]
+      render?: "auto" | "manual"
+      loadOp?: "clear" | "load"
+    } & SamplerOptions &
+      LabelOption,
+  ): TextureId
+  /**
+   * Append a draw entry to a draw target: `pipeline` draws `opts.buffer`
+   * (required when the pipeline declares attributes) with its own `params`
+   * and `textures`, last in list order - the same per-entry shape
+   * {@link createShaderTarget} takes, addressed to one entry of the list.
+   * Returns the entry's {@link DrawId}, the handle every per-entry update
+   * takes. Everything validates here at the call site: unknown ids, depth
+   * compatibility (see {@link createDrawTarget}), uniform names and arities,
+   * the vertex-fetch bound, per-entry texture-unit count, and sampling
+   * cycles. List order is draw order - later entries land over earlier ones
+   * where depth does not decide - so painter-style layering is append order,
+   * and per-entry `params` is where per-object state (a model matrix) lives.
+   * `before` inserts the entry immediately before an existing one instead
+   * of appending (it must name a live entry); for wholesale reordering use
+   * {@link setDrawOrder}. An {@link IndexBinding} makes the entry draw
+   * indexed - real meshes share most vertices, and indexing stores and
+   * shades each one once - with the range in {@link IndexRange} spelling.
+   * `instanceBuffer` supplies the per-instance records the pipeline's
+   * `instanceAttributes` describe (required exactly when it declares any);
+   * `instanceCount` then defaults to one instance per record.
+   */
+  export function addDraw(
+    target: TextureId,
+    pipeline: RenderPipelineId,
+    params?: ShaderParams | null,
+    opts?: {
+      textures?: Record<string, TextureId>
+      buffer?: BufferId
+      instanceBuffer?: BufferId
+      before?: DrawId
+    } & (DrawRange | (IndexBinding & IndexRange)),
+  ): DrawId
+  /**
+   * Remove a draw entry from a draw target. Remaining entries keep their
+   * order and ids; the removed id errors from then on (ids are never
+   * reused). The entry's pipeline and buffer are yours and unaffected.
+   */
+  export function removeDraw(target: TextureId, draw: DrawId): void
+  /**
+   * Update one draw entry's uniforms by name: {@link setShaderParams}
+   * addressed to a single entry, same merge and validation contract. The
+   * per-object hot path - a moved mesh is one setDrawParams with its new
+   * model matrix.
+   */
+  export function setDrawParams(target: TextureId, draw: DrawId, params: ShaderParams): void
+  /**
+   * Rebind one draw entry's sampler2D inputs by uniform name:
+   * {@link setShaderTextures} addressed to a single entry, same merge,
+   * validation, and cycle rules. Entries bind independently - two entries
+   * may bind the same uniform name to different sources.
+   */
+  export function setDrawTextures(target: TextureId, draw: DrawId, textures: Record<string, TextureId>): void
+  /**
+   * Update one draw entry's draw range: {@link setDraw} addressed to a
+   * single entry, same partial merge, bounds validation, and vocabulary
+   * rule (an indexed entry speaks {@link IndexRange}).
+   */
+  export function setDrawRange(target: TextureId, draw: DrawId, update: DrawRange | IndexRange): void
+  /**
+   * Reorder a draw target's list. `order` must name every current entry
+   * exactly once - a full permutation of the live {@link DrawId}s; a
+   * missing, duplicate, or unknown id throws, naming the problem. List
+   * order is draw order, which makes this the sorting verb: sort opaque
+   * entries front-to-back (early depth rejection) and transparent ones
+   * back-to-front, and re-issue the order when the camera moves. Entry
+   * state (params, textures, ranges) rides along untouched; ids are
+   * unaffected. Like every draw-list write it re-renders an auto target
+   * once at the next flush, and folds silently on a manual one.
    */
-  export function setDraw(id: TextureId, draw: DrawRange): void
+  export function setDrawOrder(target: TextureId, order: DrawId[]): void
   /**
    * Render a `render: "manual"` target once, now. Renders land in call order
    * relative to every other GPU call: a `setShaderParams`/`writeBuffer`

package/package.json

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