rapid-render 1.0.22 → 1.0.24

package/README.md

@@ -35,18 +35,6 @@ If you want Pixi-level rendering without letting your renderer dictate how your
 
 Particles, Light & Shadow, Custom Shaders, Lines, Masks, Render textures, Sprites, Custom Geometry, Filters and more. all from one focused WebGL renderer. Yet it is only **22.5 kB gzipped**.
 
-## Architecture Recipes
-
-Rapid.js handles only the rendering layer, leaving your game architecture entirely in your hands.
-
-Rapid.js is frame-stateless, making it easy to build games with different architectures. Below are minimal, working implementations of several popular architectures built on Rapid.js, each in **around 100 lines** of JavaScript.
-
-- **Architecture recipes**  
-  [Game Object](recipes/game-object.js) · [Component](recipes/component.js) · [Display List](recipes/display-list.js) · [ECS Integration](recipes/ecs-integration.js) · [Immediate Mode](recipes/immediate-mode.js)
-
-- **Game-engine-style recipes**  
-[Kaplay-like](recipes/game-engine/kaplay-like.js) · [Pixi-like](recipes/game-engine/pixi-like.js) · [Phaser-like](recipes/game-engine/phaser-like.js) · [Excalibur-like](recipes/game-engine/excalibur-like.js) · [LittleJS-like](recipes/game-engine/littlejs-like.js) · [p5-like](recipes/game-engine/p5-like.js)
-
 ## Install
 
 ```bash
@@ -113,19 +101,15 @@ stack.restore(); // 1.root
 rapid.drawSprite(ui);
 ```
 
-## Reuse and Update Matrix Subtrees
+## Use Saved World Matrices
 
-Use `customMatrix` to render with any matrix in the hierarchy (even after its stack scope has been popped).
-
-When you modify a node's local matrix, call `updateMatrixSubtree()` to automatically recalculate that node and all affected descendant world matrices, without rebuilding the entire matrix hierarchy.
+`save()` returns the current `parent`, `local`, and `world` matrix IDs. The IDs can be used with `customMatrix` after their stack scope has been restored, as long as they belong to the current frame.
 
 ```ts
 rapid.clear();
 
 const stack = rapid.matrixStack;
-const matrix = rapid.matrix;
-
-// Build a transform hierarchy.
+// Build the hierarchy for this frame.
 const world = stack.save();
 stack.translate(200, 200);
 
@@ -135,15 +119,8 @@ stack.translate(80, 0);
 stack.restore(); // enemyNode
 stack.restore(); // world
 
-// Both nodes have been popped, but their matrices remain available.
-// Move the world node later in the same frame.
-matrix.identity(world.local);
-matrix.translate(world.local, 100, 100);
-
-// Recalculate only `world` and its descendants.
-stack.updateMatrixSubtree(world);
-
-// Render using the stored matrix of the popped child node.
+// The stack has been restored, but enemyNode.world is still available during
+// this frame. Build the hierarchy again next frame with the latest game state.
 rapid.drawSprite({
   texture: enemy,
   customMatrix: enemyNode.world,
@@ -152,6 +129,8 @@ rapid.drawSprite({
 rapid.flush();
 ```
 
+`MatrixStack` is immediate-mode: rebuild transform hierarchies each frame. For retained scene graphs, keep transforms in your own game objects and feed them into the stack while traversing the scene.
+
 With this flexible matrix stack, you can build your own architecture with minimal friction. It doesn't care how you organize your game logic. You can use ECS, scene graphs, components, or any hybrid approach you prefer.
 
 For more information about matrix transformations, see the [Transformations](https://nightre.github.io/Rapid.js/docs.html#transformations).

package/dist/color.d.ts

@@ -14,7 +14,7 @@ export declare class Color {
      * @param a - The alpha component (0-255).
      */
     constructor(r: number, g: number, b: number, a?: number);
-    setClearColor(gl: WebGL2RenderingContext): void;
+    setClearColor(gl: WebGL2RenderingContext, premultipliedUint32?: boolean): void;
     /**
      * Gets the red component.
      */

package/dist/draw.d.ts

@@ -23,8 +23,8 @@ export interface IDrawParticleBatchOptions extends IDisplayOptions {
     rotation?: ArrayLike<number> | number;
     color?: ArrayLike<Color> | ArrayLike<number> | number;
     count?: number;
-    scaleX?: ArrayLike<number>;
-    scaleY?: ArrayLike<number>;
+    scaleX?: ArrayLike<number> | number;
+    scaleY?: ArrayLike<number> | number;
     originX?: number;
     originY?: number;
     flipX?: boolean;

package/dist/extensions/light.d.ts

@@ -8,6 +8,7 @@ import { Region } from '../region/region';
 export declare const MAX_LIGHTS = 8;
 export declare class LightShader extends CustomGlShader {
     constructor(rapid: Rapid, vs?: string, fs?: string, usedTextureUnitNum?: number, uniforms?: Record<string, UniformValue>);
+    beforePreCompile(): void;
     getGLShader(region: Region, key: string, baseVS: string, baseFS: string): import('..').GLShader | null;
 }
 export type LightMatrix = number | MatrixSaveState;

package/dist/extensions/particle.d.ts

@@ -170,7 +170,7 @@ export declare class ParticleEmitter {
      * Renders all live particles.
      * In local-space mode the emitter's own transform is applied around the batch.
      */
-    render(): void;
+    render(customMatrix?: number): void;
     /** Returns `true` if the emitter is running or still has live particles. */
     isActive(): boolean;
     /**

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export * from './extensions/particle';
 export * from './extensions/light';
 export * from './line';
 export * from './draw';
+export * from './viewport';

package/dist/matrix-engine.d.ts

@@ -20,13 +20,18 @@ export interface ITransformOptions {
  * Matrices are stored flat in a dynamic Float32Array to improve memory locality and cache performance.
  */
 export declare class MatrixStore {
-    /** Total number of matrices currently allocated in the store. */
+    /** Number of matrix slots created, including released slots available for reuse. */
     matrixCount: number;
     /** The dynamic buffer used to hold matrix data. */
     buffer: DynamicArrayBuffer;
     /** The raw floating-point data of all matrices. */
     data: Float32Array;
+    /** Per-matrix allocation flags: 1 for live matrices, 0 for released matrices. */
+    freeFlag: DynamicArrayBuffer;
+    /** Stack of released matrix indices available for reuse. */
+    freeMatrixStack: DynamicArrayBuffer;
     temporary: number;
+    identityMatrix: number;
     /**
      * Creates a new MatrixStore.
      * @param capacity - The initial capacity of the matrix store (default is 10).
@@ -42,6 +47,8 @@ export declare class MatrixStore {
      * @returns The index of the newly allocated matrix.
      */
     allocDirty(): number;
+    /** Releases a matrix index so it can be reused by a later allocation. */
+    free(index: number): void;
     /**
      * Resets the store, clearing all allocated matrices.
      */
@@ -203,11 +210,13 @@ export declare class MatrixStore {
     setMatrix(index: number, f: Float32Array | number[]): void;
     multiplyAffineInPlace(index: number, a: number, b: number, c: number, dValue: number, tx: number, ty: number): void;
     multiplyAffine(indexIn: number, indexOut: number, a: number, b: number, c: number, dValue: number, tx: number, ty: number): void;
+    clampBounds(index: number, viewWidth: number, viewHeight: number, limitLeft?: number, limitRight?: number, limitTop?: number, limitBottom?: number): void;
+    applyTransform(transform: ITransformOptions, width?: number, height?: number): number[];
 }
 export interface MatrixSaveState {
     world: number;
     local: number;
-    step: number;
+    parent: number;
 }
 /**
  * A highly performant MatrixStack useful for hierarchal scene graphs.
@@ -216,18 +225,9 @@ export interface MatrixSaveState {
 export declare class MatrixStack {
     /** The underlying store for matrices. */
     matrix: MatrixStore;
-    /** The current step or depth in the transformation hierarchy. */
-    step: number;
     /** Internal stack maintaining structural information. */
     stack: DynamicArrayBuffer;
-    /** Records the world matrices generated at each step. */
-    stepWorldM: DynamicArrayBuffer;
-    /** Records actions (push/pop) taken during the traversal. */
-    stepAction: DynamicArrayBuffer;
-    /** Records the parent world matrix for each step (used by updateMatrixSubtree). */
-    stepParentM: DynamicArrayBuffer;
-    stepClose: DynamicArrayBuffer;
-    stepStack: DynamicArrayBuffer;
+    currStack: DynamicArrayBuffer;
     /** The index of the current local matrix in the matrix store. */
     curLocalM: number;
     /** The index of the current world matrix in the matrix store. */
@@ -240,28 +240,29 @@ export declare class MatrixStack {
     /**
      * Saves the current matrix state and pushes it onto the stack.
      * Equivalent to context.save().
-     * @returns The current step counter before saving.
+     * Provided matrix IDs are used directly and recycled by reset() unless retained.
+     * @param matrixWorld Optional world matrix ID from this store; defaults to parent * local.
+     * @param matrixLocal Optional local matrix ID from this store; defaults to identity.
+     * @returns Matrix IDs for the saved parent, local, and world transforms.
      */
-    save(): MatrixSaveState;
+    save(matrixWorld?: number, matrixLocal?: number): MatrixSaveState;
     /**
      * Restores the matrix state from the top of the stack.
      * Equivalent to context.restore().
      */
     restore(): void;
     restoreAll(): void;
-    getStep(step: number | {
-        step: number;
-    }): number;
-    private walkSubtree;
-    getParent(step: number | {
-        step: number;
-    }): number;
-    getChildren(step: number | {
-        step: number;
-    }): number[];
-    updateMatrixSubtree(step: number | {
-        step: number;
-    }): void;
+    /**
+     * Removes a matrix from the current and previous frame recycle queues so
+     * it remains valid across `reset()` calls.
+     *
+     * Passing a `MatrixSaveState` retains its `local` and `world` matrices;
+     * `parent` is not retained because it belongs to the parent stack state.
+     * Retained matrices must eventually be released with `matrix.free()`.
+     *
+     * @param matrix A matrix ID or the state returned by `save()`.
+     */
+    retainMatrix(matrix: number | MatrixSaveState): void;
     /**
      * Translates the current local and world matrices by x and y.
      * @param x - Translation along the x-axis.
@@ -361,9 +362,5 @@ export declare class MatrixStack {
         x: number;
         y: number;
     };
-    /**
-     * Applies a transform options object to the current matrix state.
-     * Optionally saves the matrix first
-     */
-    applyTransform(transform: ITransformOptions, width?: number, height?: number, customMatrix?: number): void;
+    applyTransform(transform: ITransformOptions, width?: number, height?: number, customMatrix?: number, worldMatrix?: number, localMatrix?: number): void;
 }