@solidrt/flux-types 0.0.42 → 0.0.43

package/gui/audio.d.ts

@@ -1,50 +1,85 @@
 // Sound playback (gui-enabled runtime only). The imperative primitive; `play`
-// decodes and starts a clip in one call, while `load` decodes once so a clip can
-// be replayed cheaply. Handles carry a `stop()` bound to just that voice, so the
-// raw track id never leaves the runtime.
+// decodes and starts a clip in one call, while `load`/`loadPcm`/`stream` yield
+// a Clip that starts cheap overlapping Playbacks. Handles carry controls bound
+// to just that clip or playback, so raw ids never leave the runtime.
 
 declare module "flux:audio" {
-  /** Options for {@link play} and {@link LoadedSound.play}. */
+  /** Options for {@link play} and {@link Clip.play}. */
   type PlayOptions = {
     /** Repeat the clip until stopped. Defaults to false. */
     loop?: boolean
     /** Volume scale, 1.0 leaves the clip unchanged. Defaults to 1.0. */
     gain?: number
+    /**
+     * Stereo position in [-1, 1] (clamped), -1 = left, 0 = center, 1 = right,
+     * equal-power law. Omitted means unspatialized: no stereo processing at
+     * all, which for a mono clip is about 3 dB louder than `pan: 0`.
+     */
+    pan?: number
   }
 
-  /** A playing voice with controls bound to it. */
-  type SoundHandle = {
-    /** Stop this voice. A no-op if it already finished. */
+  /** One playing instance of a clip, with live controls bound to it. */
+  type Playback = {
+    /** Stop this playback. A no-op if it already finished. */
     stop(): void
+    /**
+     * Change the volume while playing. A finite number >= 0; 1.0 is the clip's
+     * own level. A no-op after the playback finished.
+     */
+    setGain(gain: number): void
+    /**
+     * Move the stereo position while playing (see {@link PlayOptions.pan}).
+     * A no-op after the playback finished.
+     */
+    setPan(pan: number): void
+    /** Whether playback finished, naturally or via {@link stop}. */
+    ended(): boolean
   }
 
-  /** A decoded clip that can be replayed without re-decoding. */
-  type LoadedSound = {
-    /** Start a fresh overlapping voice for this clip. */
-    play(options?: PlayOptions): SoundHandle
-    /** Release the decoded clip. Voices already playing keep going. */
+  /** A loaded clip that can be played without re-decoding. */
+  type Clip = {
+    /** Start a fresh overlapping playback of this clip. */
+    play(options?: PlayOptions): Playback
+    /** Release the clip. Playbacks already running keep going. */
     unload(): void
   }
 
+  /** Options for {@link loadPcm}. */
+  type PcmOptions = {
+    /** Channel count, interleaved samples when 2. Defaults to 1 (mono). */
+    channels?: 1 | 2
+  }
+
   /**
    * Decode and start an encoded audio clip (Ogg/Vorbis or WAV). Returns
    * immediately; the sound plays on the mixer's own thread. Use {@link load} to
    * replay a clip repeatedly without decoding it each time.
    */
-  export function play(bytes: Uint8Array, options?: PlayOptions): SoundHandle
+  export function play(bytes: Uint8Array, options?: PlayOptions): Playback
   /**
    * Decode an encoded clip (Ogg/Vorbis or WAV) once and keep it in memory so it
    * can be replayed cheaply. Call `unload()` on the result when done.
    */
-  export function load(bytes: Uint8Array): LoadedSound
+  export function load(bytes: Uint8Array): Clip
+  /**
+   * Load raw PCM samples as a clip; no decoding, no container. The typed array
+   * is the sample format: Uint8Array = unsigned 8-bit, Int16Array = signed
+   * 16-bit, Float32Array = 32-bit float, all as laid out in memory. Samples are
+   * interleaved when `channels` is 2. Call `unload()` on the result when done.
+   */
+  export function loadPcm(
+    data: Uint8Array | Int16Array | Float32Array,
+    sampleRate: number,
+    options?: PcmOptions,
+  ): Clip
   /**
    * Open a clip for streaming: it is decoded on demand instead of loaded fully
    * into memory, so a large track needs little RAM. Takes a `file()` from
    * `flux:fs` (not a path), so the source rides the `file()` proxy override - a
    * dev-server-proxied file streams from the server. Play the result as a single
-   * voice; do not overlap a stream with itself. Call `unload()` when done.
+   * playback; do not overlap a stream with itself. Call `unload()` when done.
    */
-  export function stream(source: ReturnType<typeof import("flux:fs").file>): LoadedSound
+  export function stream(source: ReturnType<typeof import("flux:fs").file>): Clip
   /** Stop every playing sound. */
   export function stop(): void
 }

package/gui/gpu.d.ts

@@ -116,6 +116,20 @@ declare module "flux:gpu" {
    * {@link setShaderSize}).
    */
   export type LabelOption = { label?: string }
+  /**
+   * Pixel format of an uploaded texture, declared at creation and fixed for
+   * the id's lifetime (like the sampler state). "rgba8" (default) is 4 bytes
+   * per pixel. "r8" is the single-channel format - 1 byte per pixel - for
+   * palette-indexed or grayscale content: upload raw indices and look the
+   * color up in the shader, so palette effects are a palette-texture write
+   * instead of touching every pixel. Any width works (no 4-byte row padding;
+   * the engine uploads r8 at unpack alignment 1). A shader samples an r8
+   * texture as `(v, 0, 0, 1)` - read `.r`; displaying one via `<texture src>`
+   * shows that same red-channel reading. Shader/pipeline targets and
+   * readbacks stay RGBA8.
+   */
+  export type TextureFormat = "rgba8" | "r8"
+  export type TextureFormatOption = { format?: TextureFormat }
   /**
    * This device's hard ceilings, queried once at startup: process constants.
    * Every create and bind validates against them at the call site, so an
@@ -138,19 +152,22 @@ declare module "flux:gpu" {
     maxVertexAttribs: number
   }
   /**
-   * Create an immutable texture from an RGBA8 pixel buffer (exactly
-   * width*height*4 bytes). Returns the texture id.
+   * Create an immutable texture from a pixel buffer (exactly
+   * width*height*bytesPerPixel bytes: *4 for the default "rgba8" format, *1
+   * for "r8"). Returns the texture id.
    */
-  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & LabelOption): TextureId
+  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
   /**
    * 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).
+   * seed buffer must hold at least one frame (width*height bytes at the
+   * declared format's pixel size) and may hold more (uploadTexture selects a
+   * frame by offset).
    */
-  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & LabelOption): TextureId
+  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
   /**
-   * Replace a mutable texture's pixels. `data` may hold several frames; `offset`
-   * (default 0) selects which frame to upload.
+   * Replace a mutable texture's pixels; the frame size follows the format the
+   * id was created with. `data` may hold several frames; `offset` (default 0)
+   * selects which frame to upload.
    */
   export function uploadTexture(id: TextureId, data: Uint8Array, offset?: number): void
   /**
@@ -158,8 +175,9 @@ declare module "flux:gpu" {
    * resize): `<texture src>` references and shader sampler bindings keep
    * working, and shaders sampling the texture re-render. `data` seeds the new
    * contents and, like {@link createMutableTexture}, must hold at least one
-   * width*height*4 frame. Shader/pipeline target ids are rejected - resize
-   * those with {@link setShaderSize}.
+   * frame at the id's format (which survives the resize, like the sampler
+   * state). Shader/pipeline target ids are rejected - resize those with
+   * {@link setShaderSize}.
    */
   export function resizeTexture(id: TextureId, data: Uint8Array, width: number, height: number): void
   /**
@@ -202,8 +220,10 @@ declare module "flux:gpu" {
    * 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 createPipelineTexture}. A complete source may also declare
-   * `iResolution` as vec3 (the Shadertoy shape); it is then filled as
-   * `(w, h, 1.0)`.
+   * `iResolution` as vec3 (a common convention in ported shaders); it is
+   * then filled as `(w, h, 1.0)`. One naming trap: GLSL ES reserves `packed` as a keyword,
+   * so `vec4 packed = texture(...)` fails with a syntax error that does not
+   * name the identifier - pick another name.
    */
   export function createShaderTexture(
     fragmentSrc: string,

package/modules/wasm.d.ts

@@ -1,3 +1,8 @@
+// There is no `WebAssembly` global in flux; this module is the entire wasm
+// surface. Imports must be scalar-signature functions only (no imported
+// memory, globals or tables), which constrains the toolchain on the other
+// side: default emscripten output imports its memory and is rejected, while
+// `emcc -sSTANDALONE_WASM=1 --no-entry` produces a module that fits.
 declare module "flux:wasm" {
   /**
    * A scalar wasm value. i32/f32/f64 marshal as number; i64 marshals as BigInt
@@ -39,7 +44,8 @@ declare module "flux:wasm" {
     /**
      * Parse and validate a wasm binary (wat text bytes are also accepted).
      * Throws on invalid input or on an unsupported import (non-function, or
-     * non-scalar signature).
+     * non-scalar signature) - see the module note above for the emscripten
+     * flags that produce a compatible binary.
      */
     constructor(bytes: Uint8Array | ArrayBuffer)
     /**
@@ -75,13 +81,27 @@ declare module "flux:wasm" {
      */
     callIndirect(index: number, ...args: WasmValue[]): WasmValue | WasmValue[] | undefined
     /**
-     * The exported memory's current size in bytes, or `undefined` if the
-     * module exports no memory.
+     * The exported linear memory as an `ArrayBuffer` aliasing the instance's
+     * live bytes, or `undefined` if the module exports no memory. Reads and
+     * writes go straight to guest memory - no copy; a `Uint8Array` over it
+     * (`new Uint8Array(instance.memory, ptr, len)`) is the zero-copy way to
+     * hand guest bytes to e.g. `uploadTexture`. Follows the web's
+     * `WebAssembly.Memory.buffer` contract: the buffer stays valid until the
+     * guest grows its memory, which detaches it; read `memory` again for a
+     * fresh buffer over the moved storage.
+     */
+    readonly memory: ArrayBuffer | undefined
+    /**
+     * Copy `len` bytes out of the exported memory at `ptr`, as a fresh
+     * `Uint8Array`. One-shot convenience; for repeated or large reads use
+     * {@link memory} directly.
      */
-    readonly memorySize: number | undefined
-    /** Copy `len` bytes out of the exported memory at `ptr`. */
     readMemory(ptr: number, len: number): Uint8Array
-    /** Copy `bytes` into the exported memory at `ptr`. */
+    /**
+     * Copy `bytes` into the exported memory at `ptr`. The source may itself
+     * be a view over this instance's memory; overlapping ranges copy
+     * correctly.
+     */
     writeMemory(ptr: number, bytes: Uint8Array | ArrayBuffer): void
   }
 }

package/package.json

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