rapid-render 0.1.21 → 1.0.0

package/dist/webgl/glshader.d.ts

@@ -1,38 +1,120 @@
-import { IAttribute, ShaderType } from "../interface";
-import Rapid from "../render";
-import { Uniform } from "./uniform";
-import RenderRegion from "../regions/region";
-declare class GLShader {
+import { Region } from '../region/region';
+import { Rapid } from '../render';
+export type WebGLContext = WebGL2RenderingContext;
+export interface IAttribute {
+    name: string;
+    size: number;
+    type?: number;
+    normalized?: boolean;
+    stride: number;
+    offset?: number;
+    /** 0 = per-vertex (default), 1 = per-instance */
+    divisor?: number;
+}
+/** All value types accepted by setUniform / setUniforms */
+export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number] | Float32Array | number[] | Int32Array;
+/**
+ * Wraps a WebGL shader program.
+ * Parses attribute/uniform locations and types from GLSL source automatically.
+ */
+export declare class GLShader {
+    program: WebGLProgram;
     attributeLoc: Record<string, number>;
     uniformLoc: Record<string, WebGLUniformLocation>;
-    program: WebGLProgram;
-    textureUnitNum: number;
-    private attributes;
+    isCustom: boolean;
+    /** Padding in pixels this shader needs beyond the sprite bounds (for outline/glow effects) */
+    padding: number;
+    /** GLSL type for each uniform, parsed from source */
+    private uniformType;
+    /** Whether the uniform is an array (e.g. sampler2D uTextures[8]) */
+    private uniformIsArray;
     private gl;
-    constructor(rapid: Rapid, vs: string, fs: string, attributes?: IAttribute[], textureUnitNum?: number);
+    shaderId: number;
+    readonly vao: WebGLVertexArrayObject;
+    constructor(gl: WebGLContext, vs: string, fs: string, attributes?: IAttribute[]);
+    /** Switch GPU to use this shader program */
+    use(): void;
+    /** Bind this shader's VAO (start recording or replaying attribute state) */
+    bindVAO(): void;
+    /** Unbind VAO (finish recording) */
+    unbindVAO(): void;
     /**
-     * Set the uniform of this shader
-     * @param uniforms
-     * @param usedTextureUnit How many texture units have been used
+     * Set a single uniform by name. Type is inferred from the parsed GLSL source.
+     * @example
+     *   shader.setUniform("uTime", 1.5);
+     *   shader.setUniform("uColor", [1, 0, 0, 1]);
+     *   shader.setUniform("uMVP", mat4array);
      */
-    setUniforms(uniform: Uniform, region: RenderRegion): void;
-    private getUniform;
+    setUniform(name: string, value: UniformValue): void;
     /**
-     * use this shader
+     * Batch-set uniforms via a plain value map.
+     * @example
+     *   shader.setUniforms({
+     *     uTime:       1.5,
+     *     uResolution: [800, 600],
+     *     uMVP:        mat4,
+     *   });
      */
-    use(): void;
+    setUniforms(uniforms: Record<string, UniformValue>): void;
+    /**
+     * Bind a single vertex attribute pointer.
+     * The VBO must already be bound before calling this.
+     */
+    setAttribute(attr: IAttribute): void;
+    /** Bind all vertex attribute pointers at once */
+    setAttributes(attrs: IAttribute[]): void;
+    /** Free GPU resources */
+    destroy(): void;
+    /** Parse attribute/uniform names and GLSL types from raw shader source */
     private parseShader;
+}
+export default GLShader;
+/**
+ * A wrapper for creating and managing custom shaders across multiple rendering regions.
+ */
+export declare class CustomGlShader {
+    /** Custom vertex shader code */
+    vs: string;
+    /** Custom fragment shader code */
+    fs: string;
+    /** Map of compiled GLShader instances per region key */
+    glshader: Map<string, GLShader>;
+    /** Currently stored uniform values */
+    uniforms: Record<string, UniformValue>;
+    /** Set of region keys that need uniform updates */
+    uniformDirty: Set<string>;
+    /** Map of textures to be bound to this shader */
+    uniformTextures: Record<string, WebGLTexture>;
+    /** Number of texture units reserved by this custom shader */
+    usedTextureUnitNum: number;
+    /** Padding in pixels this shader needs beyond the sprite bounds (for outline/glow effects) */
+    padding: number;
+    rapid: Rapid;
+    constructor(rapid: Rapid, vs: string, fs: string, usedTextureUnitNum?: number, uniforms?: Record<string, UniformValue>);
+    /**
+     * Updates uniform values or textures for the custom shader.
+     * @param uniforms Map of uniform values or WebGL textures to apply.
+     */
+    setUniforms(uniforms: Record<string, UniformValue | WebGLTexture>): void;
     /**
-     * Set vertex attribute in glsl shader
-     * @param element
+     * Sets the padding (in pixels) for this shader and propagates to all compiled GLShaders.
+     * Must be called before the first draw call if set after construction.
+     * @param pixels - Number of pixels to expand the quad on each side.
      */
-    setAttribute(element: IAttribute): void;
+    setPadding(pixels: number): this;
     /**
-     * Set vertex attributes in glsl shader
-     * @param elements
+     * Applies current uniforms and texture unit mappings to the region-specific shader.
+     * @param key The region key.
+     * @param textureUniforms Map of texture uniform names to assigned texture unit indices.
      */
-    setAttributes(elements: IAttribute[]): void;
-    updateAttributes(): void;
-    static createCostumShader(rapid: Rapid, vs: string, fs: string, type: ShaderType, textureUnitNum?: number): GLShader;
+    applyUniform(key: string, textureUniforms: Record<string, number>): void;
+    /**
+     * Retrieves or compiles a customized GLShader for a specific region.
+     * @param region The Region requesting the shader.
+     * @param key The region key.
+     * @param baseVS The base vertex shader template.
+     * @param baseFS The base fragment shader template.
+     * @returns The combined and compiled GLShader.
+     */
+    getGLShader(region: Region, key: string, baseVS?: string, baseFS?: string): GLShader | null;
 }
-export default GLShader;

package/dist/webgl/utils.d.ts

@@ -1,10 +1,13 @@
-import { WebGLContext } from "../interface";
+import { Rapid, TextureFilterMode } from '../render';
+import { ITextOptions, TextureWrapMode } from '../texture';
+export type WebGLContext = WebGL2RenderingContext;
+export declare const supportsWebGL: (canvas: HTMLCanvasElement) => boolean;
 /**
- * get webgl rendering context
+ * get webgl2 rendering context
  * @param canvas
- * @returns webgl1 or webgl2
+ * @returns webgl2
  */
-export declare const getContext: (canvas: HTMLCanvasElement) => WebGLContext;
+export declare const getContext: (canvas: HTMLCanvasElement, antialias?: boolean, premultipliedAlpha?: boolean) => WebGLContext;
 /**
  * compile string to webgl shader
  * @param gl
@@ -21,17 +24,24 @@ export declare const compileShader: (gl: WebGLContext, source: string, type: num
  * @returns
  */
 export declare const createShaderProgram: (gl: WebGLContext, vsSource: string, fsSource: string) => WebGLProgram;
+export declare function setTextureWrapMode(gl: WebGLRenderingContext | WebGL2RenderingContext, wrapMode: TextureWrapMode): void;
+export declare function setTextureFilterMode(gl: WebGLRenderingContext | WebGL2RenderingContext, filterMode: TextureFilterMode): void;
+export interface ICreateTextureOptions extends ITextOptions {
+    onlySize?: boolean;
+}
 /**
  * Creates a WebGL texture either from an image source or as a blank texture
  * @param gl - The WebGL rendering context
  * @param source - The image source or dimensions for a blank texture
- * @param antialias - Whether to enable antialiasing
+ * @param filterMode - texture filter mode
  * @returns A WebGL texture
  */
-export declare function createTexture(gl: WebGLContext, source: TexImageSource | {
+export declare function createTexture(render: Rapid, source: TexImageSource | {
     width: number;
     height: number;
-}, antialias: boolean, withSize?: boolean, flipY?: boolean, wrapMode?: 'repeat' | 'mirror' | 'clamp'): WebGLTexture;
-export declare function generateFragShader(fs: string, max: number): string;
+}, options: ICreateTextureOptions): WebGLTexture;
+export declare function generateShader(fs: string, max: number): string;
 export declare const FLOAT = 5126;
 export declare const UNSIGNED_BYTE = 5121;
+export declare function vertexAttribDivisor(gl: WebGLContext, index: number, divisor: number): void;
+export declare function drawArraysInstanced(gl: WebGLContext, mode: number, first: number, count: number, instanceCount: number): void;

package/package.json

@@ -1,38 +1,36 @@
-{
-  "name": "rapid-render",
-  "version": "0.1.21",
-  "type": "module",
-  "files": [
-    "dist"
-  ],
-  "main": "./dist/rapid.umd.cjs",
-  "module": "./dist/rapid.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    "types": "./dist/index.d.ts",
-    "import": "./dist/rapid.js",
-    "require": "./dist/rapid.umd.cjs"
-  },
-  "scripts": {
-    "dev:build": "rollup -c rollup.config.dev.js -w",
-    "dev:serve": "node ./scripts/dev-server.js",
-    "dev": "concurrently \"npm run dev:build\" \"npm run dev:serve\"",
-    "build": "rollup -c rollup.config.prod.js && tsc",
-    "docs": "typedoc"
-  },
-  "devDependencies": {
-    "express": "^4.18.2",
-    "rollup": "^4.12.0",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-string": "^3.0.0",
-    "rollup-plugin-terser": "^7.0.2",
-    "rollup-plugin-typescript2": "^0.36.0",
-    "tslib": "^2.6.2",
-    "typedoc-theme-category-nav": "^0.0.3",
-    "typescript": "^5.3.3"
-  },
-  "dependencies": {
-    "concurrently": "^9.1.2",
-    "typedoc": "^0.28.3"
-  }
-}
+{
+  "name": "rapid-render",
+  "private": false,
+  "version": "1.0.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "index.d.ts"
+  ],
+  "main": "./dist/rapid.umd.cjs",
+  "module": "./dist/rapid.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/rapid.js",
+    "require": "./dist/rapid.umd.cjs"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "docs": "typedoc",
+    "example:dev": "vite --config example/vite.config.ts",
+    "example:build": "vite build --config example/vite.config.ts"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.17",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@types/stats.js": "^0.17.4",
+    "highlight.js": "^11.11.1",
+    "stats.js": "^0.17.0",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}

package/dist/depth.d.ts

@@ -1,8 +0,0 @@
-declare class DepthScaler {
-    private max;
-    private min;
-    constructor();
-    getDepth(depth?: number): number | undefined;
-}
-declare const _default: DepthScaler;
-export default _default;

package/dist/input.d.ts

@@ -1,60 +0,0 @@
-import { Vec2 } from "./math";
-import Rapid from "./render";
-import { Entity } from "./utils";
-export declare class InputManager {
-    rapid: Rapid;
-    canvas: HTMLCanvasElement;
-    mousePosition: Vec2;
-    private keysDown;
-    private keysDownLastFrame;
-    private buttonsDown;
-    private buttonsDownLastFrame;
-    constructor(rapid: Rapid);
-    /**
-     * 附加所有必要的事件监听器
-     * @private
-     */
-    private attachEventListeners;
-    updateNextFrame(): void;
-    /**
-     * 检查某个按键当前是否被按下 (持续检测)
-     * @param key `event.code` 的值, e.g., "KeyW", "Space"
-     */
-    isKeyDown(key: string): boolean;
-    /**
-     * 检查某个按键当前是否是松开状态
-     * @param key `event.code` 的值
-     */
-    isKeyUp(key: string): boolean;
-    /**
-     * 检查某个按键是否在当前帧“刚刚被按下” (单次触发)
-     * @param key `event.code` 的值
-     */
-    wasKeyPressed(key: string): boolean;
-    /**
-     * 检查某个按键是否在当前帧“刚刚被松开” (单次触发)
-     * @param key `event.code` 的值
-     */
-    wasKeyReleased(key: string): boolean;
-    /**
-     * 检查某个鼠标按钮当前是否被按下 (持续检测)
-     * @param button 鼠标按钮编号
-     */
-    isButtonDown(button: number): boolean;
-    /**
-     * 检查某个鼠标按钮当前是否是松开状态
-     * @param button 鼠标按钮编号
-     */
-    isButtonUp(button: number): boolean;
-    /**
-     * 检查某个鼠标按钮是否在当前帧“刚刚被按下” (单次触发)
-     * @param button 鼠标按钮编号
-     */
-    wasButtonPressed(button: number): boolean;
-    /**
-     * 检查某个鼠标按钮是否在当前帧“刚刚被松开” (单次触发)
-     * @param button 鼠标按钮编号
-     */
-    wasButtonReleased(button: number): boolean;
-    getMouseLocal(entity: Entity): Vec2;
-}

package/dist/interface.d.ts

@@ -1,334 +0,0 @@
-import { Color, Vec2 } from "./math";
-import { Texture } from "./texture";
-import { TileSet } from "./tilemap";
-import GLShader from "./webgl/glshader";
-import { Uniform } from "./webgl/uniform";
-/**
- * @ignore
- */
-export type WebGLContext = WebGL2RenderingContext | WebGLRenderingContext;
-/**
- * @ignore
- */
-export interface IMathStruct<T> {
-    clone(obj: T): T;
-    copy(obj: T): void;
-    equal(obj: T): boolean;
-}
-export declare enum ScaleRadio {
-    KEEP = "keep",
-    KEEP_H = "keep_h",
-    KEEP_W = "keep_w",
-    IGNORE = "ignore",
-    EXPAND = "expand"
-}
-export interface IRapidOptions {
-    canvas: HTMLCanvasElement;
-    width?: number;
-    height?: number;
-    backgroundColor?: Color;
-    antialias?: boolean;
-    devicePixelRatio?: number;
-    scaleEnable?: boolean;
-    scaleRadio?: ScaleRadio;
-}
-export interface IAttribute {
-    name: string;
-    size: number;
-    type: number;
-    normalized?: boolean;
-    stride: number;
-    offset?: number;
-}
-export interface IEntityTransformOptions {
-    position?: Vec2;
-    scale?: Vec2 | number;
-    rotation?: number;
-    x?: number;
-    y?: number;
-    tags: string[];
-}
-export interface ITransformOptions {
-    restoreTransform?: boolean;
-    saveTransform?: boolean;
-    position?: Vec2;
-    scale?: Vec2 | number;
-    rotation?: number;
-    x?: number;
-    y?: number;
-    offset?: Vec2;
-    offsetX?: number;
-    offsetY?: number;
-    origin?: Vec2 | number;
-    afterSave?(): unknown;
-    beforRestore?(): unknown;
-}
-export interface ISpriteRenderOptions extends ITransformOptions, IShaderRenderOptions {
-    color?: Color;
-    texture?: Texture;
-    offset?: Vec2;
-    flipX?: boolean;
-    flipY?: boolean;
-}
-export interface ITextTextureOptions {
-    /**
-     * The text string to be rendered.
-     */
-    text?: string;
-    /**
-     * The font size for the text.
-     * Default is 16.
-     */
-    fontSize?: number;
-    /**
-     * The font family for the text.
-     * Default is 'Arial'.
-     */
-    fontFamily?: string;
-    /**
-     * The color of the text.
-     * Default is '#000000' (black).
-     */
-    color?: string;
-    /**
-     * The alignment of the text.
-     * Possible values: 'left', 'right', 'center', 'start', 'end'.
-     * Default is 'left'.
-     */
-    textAlign?: CanvasTextAlign;
-    /**
-     * The baseline of the text.
-     * Possible values: 'top', 'hanging', 'middle', 'alphabetic', 'ideographic', 'bottom'.
-     * Default is 'top'.
-     */
-    textBaseline?: CanvasTextBaseline;
-}
-export interface ILineStyleOptions extends IGraphicRenderOptions {
-    width?: number;
-    closed?: boolean;
-    roundCap?: boolean;
-    textureMode?: LineTextureMode;
-    points: Vec2[];
-}
-export declare enum LineTextureMode {
-    STRETCH = "stretch",
-    REPEAT = "repeat"
-}
-export declare enum TextureWrapMode {
-    REPEAT = "repeat",
-    CLAMP = "clamp",
-    MIRROR = "mirror"
-}
-export interface IRenderLineOptions extends ILineStyleOptions, ITransformOptions {
-}
-export interface IGraphicRenderOptions extends ITransformOptions, IShaderRenderOptions {
-    color?: Color | Color[];
-    drawType?: number;
-    uv?: Vec2[];
-    texture?: Texture;
-}
-export interface IPolygonGraphicRenderOptions extends IGraphicRenderOptions {
-    points: Vec2[];
-}
-export interface ICircleRenderOptions extends IGraphicRenderOptions {
-    radius: number;
-    segments?: number;
-}
-export interface IRectRenderOptions extends IGraphicRenderOptions {
-    width: number;
-    height: number;
-}
-export declare enum MaskType {
-    Include = "normal",
-    Exclude = "inverse"
-}
-export type UniformType = Record<string, number | Array<any> | boolean | Texture>;
-export type Images = ImageBitmap | ImageData | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | OffscreenCanvas;
-export interface IRegisterTileOptions extends ISpriteRenderOptions {
-    texture: Texture;
-    offsetX?: number;
-    offsetY?: number;
-    ySortOffset?: number;
-}
-export interface YSortCallback {
-    ySort: number;
-    render?: () => void;
-    renderSprite?: ISpriteRenderOptions;
-}
-export interface ILayerRenderOptions extends ITransformOptions {
-    error?: number | Vec2;
-    errorX?: number;
-    errorY?: number;
-    ySortCallback?: Array<YSortCallback>;
-    shape?: TilemapShape;
-    tileSet: TileSet;
-    eachTile?: (tileId: string | number, mapX: number, mapY: number) => ISpriteRenderOptions | undefined | void;
-}
-export interface IShaderRenderOptions {
-    shader?: GLShader;
-    uniforms?: Uniform;
-}
-export declare enum TilemapShape {
-    SQUARE = "square",
-    ISOMETRIC = "isometric"
-}
-export declare enum ShaderType {
-    SPRITE = "sprite",
-    GRAPHIC = "graphic"
-}
-export declare enum BlendMode {
-    Additive = "additive",
-    Subtractive = "subtractive",
-    Mix = "mix"
-}
-/**
- * Interface for light rendering options
- */
-export interface ILightRenderOptions {
-    /** Position of the light source */
-    lightSource: Vec2;
-    /** Array of vertex arrays for occlusion objects, each occlusion object is defined by a set of vertices */
-    occlusion: Vec2[][];
-    /** Base projection length that controls shadow length */
-    baseProjectionLength?: number;
-    /** Type of mask to apply */
-    type?: MaskType;
-}
-export interface ICameraOptions extends ITransformOptions {
-    center?: boolean;
-}
-/**
- * Defines particle emitter shape types
- */
-export declare enum ParticleShape {
-    /**
-     * Point emitter, emits particles from a single point
-     */
-    POINT = "point",
-    /**
-     * Circle emitter, emits particles randomly from a circular area
-     */
-    CIRCLE = "circle",
-    /**
-     * Rectangle emitter, emits particles randomly from a rectangular area
-     */
-    RECT = "rect"
-}
-/**
- * Defines particle attribute animation
- * @template T Attribute type, can be number, vector or color
- */
-export interface ParticleAttribute<T extends number | Vec2 | Color> {
-    /**
-     * Damping coefficient, controls attribute decay rate over time
-     */
-    damping?: number;
-    /**
-     * Initial attribute value
-     */
-    start: T;
-    /**
-     * Final attribute value, uses initial value if not specified
-     */
-    end?: T;
-    /**
-     * Attribute change rate, automatically calculated from start and end if not specified
-     */
-    delta?: T;
-}
-/**
- * Particle system configuration options
- */
-export interface IParticleOptions extends ITransformOptions, IShaderRenderOptions {
-    /**
-     * Particle texture, can be a single texture, array of textures, or weighted texture array
-     */
-    texture: Texture | Texture[] | [Texture, number][];
-    /**
-     * Particle emission rate (particles per second)
-     */
-    emitRate?: number;
-    /**
-     * Emission time interval in seconds
-     */
-    emitTime?: number;
-    /**
-     * Maximum number of particles limit
-     */
-    maxParticles?: number;
-    /**
-     * Particle lifetime in seconds, can be fixed value or range
-     */
-    life?: number | [number, number];
-    /**
-     * Particle animation properties collection
-     */
-    animation: {
-        /**
-         * Velocity vector, controls particle movement direction and speed
-         */
-        velocity?: ParticleAttribute<Vec2>;
-        /**
-         * Acceleration vector, controls particle velocity changes
-         */
-        acceleration?: ParticleAttribute<Vec2>;
-        /**
-         * Speed scalar, used in combination with rotation direction
-         */
-        speed?: ParticleAttribute<number>;
-        /**
-         * Scale factor, controls particle size
-         */
-        scale?: ParticleAttribute<number>;
-        /**
-         * Rotation angle (in radians)
-         */
-        rotation?: ParticleAttribute<number>;
-        /**
-         * Color and transparency
-         */
-        color?: ParticleAttribute<Color>;
-    };
-    /**
-     * Emitter shape
-     */
-    emitShape?: ParticleShape;
-    /**
-     * Circular emitter radius
-     */
-    emitRadius?: number;
-    /**
-     * Rectangular emitter dimensions
-     */
-    emitRect?: {
-        width: number;
-        height: number;
-    };
-    /**
-     * Whether to use local coordinate system, true means particles are relative to emitter position,
-     * false means using global coordinates
-     */
-    localSpace?: boolean;
-}
-/**
- * Particle attribute data types
- */
-export type ParticleAttributeTypes = number | Vec2 | Color;
-/**
- * Particle attribute runtime data
- * @template T Attribute type
- */
-export type ParticleAttributeData<T extends ParticleAttributeTypes> = {
-    /**
-     * Attribute change rate per second
-     */
-    delta?: T;
-    /**
-     * Current attribute value
-     */
-    value: T;
-    /**
-     * Damping coefficient
-     */
-    damping?: number;
-};

package/dist/light.d.ts

@@ -1,7 +0,0 @@
-import { Vec2 } from "./math";
-import Rapid from "./render";
-export declare class LightManager {
-    render: Rapid;
-    constructor(render: Rapid);
-    createLightShadowMaskPolygon(occlusion: Vec2[][], lightSource: Vec2, baseProjectionLength?: number): Vec2[][];
-}

package/dist/log.d.ts

@@ -1,2 +0,0 @@
-declare const warn: (text: string) => void;
-export default warn;