rapid-render 0.1.111 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Nightre
+Copyright (c) 2026 夜均
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,72 +1,79 @@
+<p align="center">
+  <img src="./docs/image/logo_title.png" alt="Rapid" width="180" height="97" style="image-rendering: pixelated;">
+</p>
 
-# Rapid.js
+<p align="center">
+  A stateless, high-performance WebGL 2D renderer for browser games.
+</p>
 
-A highly efficient ([stress-test](https://nightre.github.io/Rapid.js/docs/examples.html)) and lightweight WebGL-based 2D rendering engine focused on rendering capabilities.
+<p align="center">
+  <a href="https://nightre.github.io/Rapid.js/">Website</a>
+  &middot;
+  <a href="https://nightre.github.io/Rapid.js/docs.html">Docs</a>
+  &middot;
+  <a href="https://nightre.github.io/Rapid.js/api/">API Reference</a>
+</p>
 
-### [Website](https://nightre.github.io/Rapid.js/docs/index.html)
+---
 
-#### [Document](https://nightre.github.io/Rapid.js/docs/docs.html) | [API Docs](https://nightre.github.io/Rapid.js/docs/api/index.html) | [Examples](https://nightre.github.io/Rapid.js/docs/examples.html)
+## What is Rapid?
 
-## Features
+Rapid is a focused WebGL 2D rendering engine for games and visual tools. lightweight at just **67 kB** (**~19.5 kB gzipped**) It handles the rendering layer while leaving your game architecture, update loop, and state management fully in your hands.
 
-* **Fast Rendering**
-* **TileMap** - YSort, isometric
-* **Graphics Drawing**
-* **Text Rendering**
-* **Line Drawing** - line texture
-* **Custom Shaders**
-* **Mask**
-* **Frame Buffer Object**
+> The documentation and demos are still being written.
 
-> [!WARNING]  
-> This project is a work in progress! Expect bugs, report issues, and feel free to contribute.
+## Highlights
 
-## Install
+- **Automatic batching**  
+  Rapid automatically batches compatible draw work. Multi-texture batching binds different textures into a single draw call, eliminating manual grouping.
 
-```bash
-npm i rapid-render
-```
+- **Powerful custom shaders**  
+  Add sprite and geometry effects through shader hooks while still using Rapid's normal renderer, transforms, textures, and draw APIs.
 
-Or via CDN:
+- **Flexible transforms**  
+  Compose motion, hierarchy, camera behavior, and local drawing with multiple transform styles backed by a fast matrix engine.
 
-```html
-<script src="https://unpkg.com/rapid-render/dist/rapid.umd.cjs"></script>
-```
+- **A complete 2D toolkit**  
+  Draw sprites, lines, masks, particles, render textures, text, and custom geometry from one compact WebGL renderer.
 
-## Quick Start
+## Install
 
-```js
-import { Rapid, Color, Vec2 } from "rapid-render"
-
-// Initialize
-const rapid = new Rapid({
-    canvas: document.getElementById("gameCanvas"),
-    backgroundColor: Color.fromHex("E6F0FF")
-})
-
-// Render example
-rapid.render(() => {
-    rapid.renderRect({ 
-        offset: new Vec2(100, 100), 
-        width: 50, 
-        height: 50, 
-        color: Color.Red 
-    })
-})
+```bash
+npm install rapid-render
 ```
 
-For more examples and detailed documentation, visit our [website](https://nightre.github.io/Rapid.js/docs/index.html).
+## Quick Start
 
-## Roadmap
+```ts
+import { Rapid, Color } from "rapid-render";
+
+const canvas = document.querySelector("canvas")!;
+const rapid = new Rapid({canvas});
+
+rapid.clear();
+rapid.drawRect({
+   x: 40,
+   y: 40,
+   width: 160,
+   height: 96,
+   color: new Color(84, 184, 234),
+});
+rapid.flush();
+```
 
-* Light System 🚧 (In Progress)
-* Nodejs Support
+## Benchmark
 
-## Contributing
+Performance Comparison: Rapid vs. Other Renderers and Game Engines
 
-Issues and PRs are welcome!
+<p align="center">
+  <a href="https://nightre.github.io/Rapid.js/benchmark/">
+    <img src="./docs/benchmark/benchmark.png" alt="Benchmark Result">
+    <img src="./docs/benchmark/benchmark2.png" alt="Benchmark Result">
+  </a>
+</p>
 
-## Screen shot
+<p align="center">
+  🎮 <strong><a href="https://nightre.github.io/Rapid.js/benchmark/">Run Interactive Benchmark Live &rarr;</a></strong>
+</p>
 
-![1](./screenshot/1.gif)
-![2](./screenshot/2.gif)
+Tested on **NVIDIA GeForce RTX 4070 Laptop GPU** (Chrome / WebGL 2.0)

package/dist/buffer.d.ts

@@ -0,0 +1,153 @@
+import { WebGLContext } from './webgl/utils';
+/**
+ * Defines the type of the underlying array buffer elements.
+ */
+export declare enum ArrayType {
+    Float32 = 0,
+    Uint32 = 1,
+    Uint16 = 2
+}
+type TypedArrayConstructor = Float32ArrayConstructor | Uint32ArrayConstructor | Uint16ArrayConstructor;
+/**
+ * A dynamic array buffer that can grow in size automatically when elements are added.
+ * It allocates an ArrayBuffer and provides typed array views to manipulate the data.
+ */
+export declare class DynamicArrayBuffer {
+    /** The number of elements currently used in the buffer. */
+    usedElemNum: number;
+    /** The main typed array view corresponding to the specified ArrayType. */
+    typedArray: Float32Array | Uint32Array | Uint16Array;
+    private arrayType;
+    /** The maximum number of elements the buffer can currently hold without resizing. */
+    protected maxElemNum: number;
+    /** The number of bytes per element based on the `ArrayType`. */
+    readonly bytePerElem: number;
+    private arraybuffer;
+    /** `Uint32Array` view of the underlying memory buffer. */
+    uint32?: Uint32Array;
+    /** `Float32Array` view of the underlying memory buffer. */
+    float32?: Float32Array;
+    /** `Uint16Array` view of the underlying memory buffer. */
+    uint16?: Uint16Array;
+    /**
+     * Initializes a new dynamic array buffer.
+     * @param arrayType - The type of elements this buffer will store primarily.
+     */
+    constructor(arrayType: ArrayType);
+    /**
+     * Returns the typed array constructor for the corresponding `ArrayType`.
+     * @param arrayType - The type of the array.
+     * @returns The typed array constructor.
+     * @throws Dispatches an error if the specified type is unsupported.
+     */
+    getArrayType(arrayType: ArrayType): TypedArrayConstructor;
+    /**
+     * Updates the typed array views when the internal array buffer gets reallocated.
+     */
+    updateTypedArray(): void;
+    /**
+     * Resets the element usage count to zero. The underlying memory capacity is preserved.
+     */
+    clear(): void;
+    /**
+     * Checks if the buffer has enough space for additional elements and resizes the buffer if necessary.
+     * @param size - The number of new elements that need to be accommodated.
+     * @returns `true` if the buffer was resized, `false` otherwise.
+     */
+    resize(size?: number): boolean;
+    /**
+     * Reallocates the underlying array buffer to a new size and copies existing data.
+     * @param size - The new maximum number of elements.
+     */
+    protected setMaxSize(size?: number): void;
+    /**
+     * Appends a new 32-bit unsigned integer element to the buffer.
+     * @param value - The item to add.
+     */
+    pushUint32(value: number): void;
+    /**
+     * Appends a new 32-bit floating point element to the buffer.
+     * @param value - The item to add.
+     */
+    pushFloat32(value: number): void;
+    /**
+     * Appends an element to the buffer, using the primary typed array view.
+     * @param value - The item to add.
+     */
+    push(value: number): void;
+    /**
+     * Removes and returns the last element in the buffer.
+     * @returns The removed element or undefined if the buffer is empty.
+     */
+    pop(): number;
+    /**
+     * Returns the last element pushed to the buffer without removing it.
+     * @returns The last element.
+     */
+    top(): number;
+    /**
+     * Gets the value of the element at the specified index.
+     * @param index - The index of the element to retrieve.
+     * @returns The requested element.
+     */
+    get(index: number): number;
+    /**
+     * Returns a constrained view of the primary typed array up to the specified range.
+     * If `end` is omitted, returns the whole reallocated buffer slice.
+     * @param begin - The starting index (inclusive). Defaults to 0.
+     * @param end - The ending index (exclusive). Optional.
+     * @returns A subarray corresponding to the specified range.
+     */
+    getArray(begin?: number, end?: number): Float32Array | Uint32Array | Uint16Array;
+    /**
+     * The number of elements currently stored in the buffer.
+     */
+    get length(): number;
+    /**
+     * Resets the buffer's used element count, effectively emptying it.
+     * Same behavior as `clear`.
+     */
+    reset(): void;
+}
+/**
+ * A specialized dynamic buffer intended for WebGL operations.
+ */
+export declare class WebglBufferArray extends DynamicArrayBuffer {
+    /** The actual WebGLBuffer object maintained by this instance. */
+    buffer: WebGLBuffer;
+    /** The related WebGL rendering context. */
+    gl: WebGLContext;
+    /** Signifies whether the buffer has been updated and requires resyncing to the GPU. */
+    protected dirty: boolean;
+    /** The WebGL buffer type, e.g., gl.ARRAY_BUFFER. */
+    readonly type: number;
+    /** Size of the allocated buffer block on the GPU side, bounded in elements count. */
+    private webglBufferSize;
+    /** Usage hint for WebGL, e.g., gl.DYNAMIC_DRAW. */
+    readonly usage: number;
+    /**
+     * Initializes a new WebGL dynamic buffer.
+     * @param gl - The active WebGL rendering context state.
+     * @param arrayType - Type of the underlying data elements to bind.
+     * @param type - Determines the type of WebGLBuffer (defaults to gl.ARRAY_BUFFER).
+     * @param usage - Determines the data usage pattern (defaults to gl.DYNAMIC_DRAW).
+     */
+    constructor(gl: WebGLContext, arrayType: ArrayType, type?: number, usage?: number);
+    /**
+     * Flags the buffer as dirty, marking it for future data synchronization.
+     */
+    makeDirty(): void;
+    /**
+     * Clears CPU side data usage and marks buffer as synced to stop needless updates.
+     */
+    clear(): void;
+    /**
+     * Binds this buffer object tracking it as the current bound buffer to the GPU.
+     */
+    bindBuffer(): void;
+    /**
+     * Uploads the local buffer data to the GPU memory synchronously.
+     */
+    bufferData(): void;
+}
+export {};

package/dist/color.d.ts

@@ -0,0 +1,144 @@
+export declare class Color {
+    private _r;
+    private _g;
+    private _b;
+    private _a;
+    uint32: number;
+    premultipliedUint32: number;
+    private static clampByte;
+    /**
+     * Creates an instance of Color.
+     * @param r - The red component (0-255).
+     * @param g - The green component (0-255).
+     * @param b - The blue component (0-255).
+     * @param a - The alpha component (0-255).
+     */
+    constructor(r: number, g: number, b: number, a?: number);
+    setClearColor(gl: WebGL2RenderingContext): void;
+    /**
+     * Gets the red component.
+     */
+    get r(): number;
+    /**
+     * Sets the red component and updates the uint32 representation.
+     * @param value - The new red component (0-255).
+     */
+    set r(value: number);
+    /**
+     * Gets the green component.
+     */
+    get g(): number;
+    /**
+     * Sets the green component and updates the uint32 representation.
+     * @param value - The new green component (0-255).
+     */
+    set g(value: number);
+    /**
+     * Gets the blue component.
+     */
+    get b(): number;
+    /**
+     * Sets the blue component and updates the uint32 representation.
+     * @param value - The new blue component (0-255).
+     */
+    set b(value: number);
+    /**
+     * Gets the alpha component.
+     */
+    get a(): number;
+    /**
+     * Sets the alpha component and updates the uint32 representation.
+     * @param value - The new alpha component (0-255).
+     */
+    set a(value: number);
+    /**
+     * Updates the uint32 representation of the color.
+     * @private
+     */
+    private updateUint;
+    reset(): void;
+    /**
+     * Sets the RGBA values of the color and updates the uint32 representation.
+     * @param r - The red component (0-255).
+     * @param g - The green component (0-255).
+     * @param b - The blue component (0-255).
+     * @param a - The alpha component (0-255).
+     */
+    setRGBA(r: number, g: number, b: number, a: number): void;
+    setHSL(h: number, s: number, l: number): Color;
+    toHex(): string;
+    /**
+     * Copies the RGBA values from another color.
+     * @param color - The color to copy from.
+     */
+    copy(color: Color): void;
+    /**
+     * Clone the current color
+     * @returns A new `Color` instance with the same RGBA values.
+     */
+    clone(): Color;
+    /**
+     * Converts the color to a hexadecimal string representation (e.g., '#RRGGBBAA').
+     * @param includeAlpha - Whether to include the alpha channel in the hex string.
+     * @returns The hexadecimal string representation of the color.
+     */
+    toHexString(includeAlpha?: boolean): string;
+    /**
+     * Checks if the current color is equal to another color.
+     * @param color - The color to compare with.
+     * @returns True if the colors are equal, otherwise false.
+     */
+    equal(color: Color): boolean;
+    equals(color: Color): boolean;
+    /**
+     * Creates a Color instance from normalized float components (0–1 range).
+     * Use this instead of `new Color()` when working with shader-style 0.0–1.0 values.
+     * @param r - Red channel (0.0–1.0)
+     * @param g - Green channel (0.0–1.0)
+     * @param b - Blue channel (0.0–1.0)
+     * @param a - Alpha channel (0.0–1.0), defaults to 1.0
+     * @returns A new Color instance with components scaled to 0–255.
+     * @example
+     * Color.fromNorm(0.9, 0.87, 0.55, 0.1) // moon glow
+     */
+    static FromHSL(h: number, s: number, l: number): Color;
+    static FromRGB(r: number, g: number, b: number): Color;
+    static fromNorm(r: number, g: number, b: number, a?: number): Color;
+    /**
+     * Creates a Color instance from a hexadecimal color string.
+     * @param hexString - The hexadecimal color string, e.g., '#RRGGBB' or '#RRGGBBAA'.
+     * @returns A new Color instance.
+     */
+    static fromHex(hexString: string): Color;
+    /**
+     * Adds the components of another color to this color, clamping the result to 255.
+     * @param color - The color to add.
+     * @returns A new Color instance with the result of the addition.
+     */
+    add(color: Color): Color;
+    /**
+     * Subtracts the components of another color from this color, clamping the result to 0.
+     * @param color - The color to subtract.
+     * @returns A new Color instance with the result of the subtraction.
+     */
+    subtract(color: Color): Color;
+    divide(color: Color | number): Color;
+    multiply(color: Color | number): Color;
+    clamp(): void;
+    static Red: Color;
+    static Green: Color;
+    static Blue: Color;
+    static Yellow: Color;
+    static Purple: Color;
+    static Orange: Color;
+    static Pink: Color;
+    static Gray: Color;
+    static Brown: Color;
+    static Cyan: Color;
+    static Magenta: Color;
+    static Lime: Color;
+    static White: Color;
+    static Black: Color;
+    static Transparent: Color;
+    static TRANSPARENT: Color;
+}

package/dist/draw.d.ts

@@ -0,0 +1,83 @@
+import { Color } from './color';
+import { ITransformOptions } from './matrix-engine';
+import { Vec2 } from './math';
+import { Texture } from './texture';
+import { default as GLShader, CustomGlShader } from './webgl/glshader';
+import { ILineRenderOptions } from './line';
+import { Rapid } from './render';
+export type DrawShader = GLShader | CustomGlShader;
+export type DrawPoint = Vec2 | {
+    x: number;
+    y: number;
+};
+export interface IDrawOptions extends ITransformOptions {
+    shader?: DrawShader;
+    customMatrix?: number;
+}
+export interface IDrawParticleOptions {
+    shader?: DrawShader;
+    texture: Texture;
+    color?: Color;
+    flipX?: boolean;
+    flipY?: boolean;
+    x?: number;
+    y?: number;
+    position?: Vec2;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    isRotated?: boolean;
+}
+export interface IDrawParticleBatchOptions {
+    shader?: DrawShader;
+    texture: Texture;
+    x: Array<number>;
+    y: Array<number>;
+    rotation: Array<number>;
+    color: Array<Color>;
+    count?: number;
+    scaleX?: number;
+    scaleY?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    isRotated?: boolean;
+}
+export interface ISpriteOptions extends IDrawOptions {
+    texture: Texture;
+    color?: Color;
+    flipX?: boolean;
+    flipY?: boolean;
+    padding?: number;
+}
+export interface IGraphicOptions extends IDrawOptions {
+    points: DrawPoint[];
+    color?: Color | Color[];
+    drawMode?: number;
+    uv?: DrawPoint[];
+    texture?: Texture;
+}
+export interface IMaskImageOptions extends IDrawOptions {
+    texture: Texture;
+}
+export interface ILineOptions extends ILineRenderOptions, IDrawOptions {
+}
+export interface IRectOptions extends IDrawOptions {
+    width: number;
+    height: number;
+    color?: Color;
+    texture?: Texture;
+}
+export interface ICircleOptions extends IDrawOptions {
+    radius: number;
+    color?: Color;
+    segments?: number;
+}
+export declare const drawSpriteRaw: (rapid: Rapid, options: ISpriteOptions) => void;
+export declare const drawSprite: (rapid: Rapid, options: ISpriteOptions) => void;
+export declare const drawParticle: (rapid: Rapid, options: IDrawParticleOptions) => void;
+export declare const drawParticles: (rapid: Rapid, options: IDrawParticleBatchOptions) => void;
+export declare const drawGraphic: (rapid: Rapid, options: IGraphicOptions) => void;
+export declare const drawLine: (rapid: Rapid, options: ILineOptions) => void;
+export declare const drawMaskImage: (rapid: Rapid, options: IMaskImageOptions) => void;
+export declare const drawRect: (rapid: Rapid, options: IRectOptions) => void;
+export declare const drawCircle: (rapid: Rapid, options: ICircleOptions) => void;

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-import Rapid from "./render";
-import GLShader from "./webgl/glshader";
-import { Text } from "./texture";
-import { TileMapRender, TileSet } from "./tilemap";
-import { Uniform } from "./webgl/uniform";
-import { spriteAttributes, graphicAttributes } from "./regions/attributes";
-export { Text, Rapid, GLShader, TileMapRender, TileSet, Uniform, graphicAttributes, spriteAttributes, };
-export * from "./math";
-export * from "./interface";
-export * from "./texture";
-export * from "./render";
+export * from './buffer';
+export * from './color';
+export * from './matrix-engine';
+export * from './render';
+export * from './draw';
+export * from './texture';
+export * from './webgl/glshader';
+export * from './region/region';
+export * from './region/spriteRegion';
+export * from './region/graphicRegion';
+export * from './math';
+export * from './particle';
+export { LineTextureMode, type ILineRenderOptions } from './line';

package/dist/line.d.ts

@@ -1,5 +1,19 @@
-import { ILineRenderOptions } from "./interface";
-import { Vec2 } from "./math";
+import { Color } from './color';
+import { Vec2 } from './math';
+import { Texture } from './texture';
+export declare enum LineTextureMode {
+    STRETCH = 0,
+    REPEAT = 1
+}
+export interface ILineRenderOptions {
+    points: Vec2[];
+    width?: number;
+    closed?: boolean;
+    roundCap?: boolean;
+    textureMode?: LineTextureMode;
+    texture?: Texture;
+    color?: Color;
+}
 /**
  * @ignore
  */