sparcoon 0.0.1

package/dist/instancedParticle/shared.js

@@ -0,0 +1,123 @@
+import { Texture, Vector2, Vector3, Vector4, Matrix3, Matrix4 } from 'three';
+import { FXColor } from '../color/FXColor.js';
+
+const GLSL_TYPE_INFO_FLOAT = Object.freeze({
+    glslTypeName: "float",
+    bufferSize: 1,
+    instantiable: true,
+});
+const GLSL_TYPE_INFO_SAMPLER2D = Object.freeze({
+    glslTypeName: "sampler2D",
+    bufferSize: -1,
+    instantiable: false,
+});
+const GLSL_TYPE_INFO_VEC2 = Object.freeze({
+    glslTypeName: "vec2",
+    bufferSize: 2,
+    instantiable: true,
+});
+const GLSL_TYPE_INFO_VEC3 = Object.freeze({
+    glslTypeName: "vec3",
+    bufferSize: 3,
+    instantiable: true,
+});
+const GLSL_TYPE_INFO_VEC4 = Object.freeze({
+    glslTypeName: "vec4",
+    bufferSize: 4,
+    instantiable: true,
+});
+const GLSL_TYPE_INFO_MAT3 = Object.freeze({
+    glslTypeName: "mat3",
+    bufferSize: 9,
+    instantiable: true,
+});
+const GLSL_TYPE_INFO_MAT4 = Object.freeze({
+    glslTypeName: "mat4",
+    bufferSize: 16,
+    instantiable: true,
+});
+function resolveGLSLTypeInfo(value) {
+    if (typeof value === "string") {
+        switch (value) {
+            case "number":
+                return GLSL_TYPE_INFO_FLOAT;
+            case "Texture":
+                return GLSL_TYPE_INFO_SAMPLER2D;
+            case "UIColor":
+                return GLSL_TYPE_INFO_VEC4;
+            case "Vector2":
+                return GLSL_TYPE_INFO_VEC2;
+            case "Vector3":
+                return GLSL_TYPE_INFO_VEC3;
+            case "Vector4":
+                return GLSL_TYPE_INFO_VEC4;
+            case "Matrix3":
+                return GLSL_TYPE_INFO_MAT3;
+            case "Matrix4":
+                return GLSL_TYPE_INFO_MAT4;
+            default:
+                throw new Error(`resolveGLSLTypeInfo.value: unsupported property type name`);
+        }
+    }
+    if (typeof value === "function") {
+        if (value === Number) {
+            return GLSL_TYPE_INFO_FLOAT;
+        }
+        if (value === Texture) {
+            return GLSL_TYPE_INFO_SAMPLER2D;
+        }
+        if (value === FXColor) {
+            return GLSL_TYPE_INFO_VEC4;
+        }
+        if (value === Vector2) {
+            return GLSL_TYPE_INFO_VEC2;
+        }
+        if (value === Vector3) {
+            return GLSL_TYPE_INFO_VEC3;
+        }
+        if (value === Vector4) {
+            return GLSL_TYPE_INFO_VEC4;
+        }
+        if (value === Matrix3) {
+            return GLSL_TYPE_INFO_MAT3;
+        }
+        if (value === Matrix4) {
+            return GLSL_TYPE_INFO_MAT4;
+        }
+        throw new Error(`resolveGLSLTypeInfo.value: unsupported property type constructor`);
+    }
+    if (typeof value === "number") {
+        return GLSL_TYPE_INFO_FLOAT;
+    }
+    if (value instanceof Texture) {
+        return GLSL_TYPE_INFO_SAMPLER2D;
+    }
+    if (value instanceof FXColor) {
+        return GLSL_TYPE_INFO_VEC4;
+    }
+    if (value instanceof Vector2) {
+        return GLSL_TYPE_INFO_VEC2;
+    }
+    if (value instanceof Vector3) {
+        return GLSL_TYPE_INFO_VEC3;
+    }
+    if (value instanceof Vector4) {
+        return GLSL_TYPE_INFO_VEC4;
+    }
+    if (value instanceof Matrix3) {
+        return GLSL_TYPE_INFO_MAT3;
+    }
+    if (value instanceof Matrix4) {
+        return GLSL_TYPE_INFO_MAT4;
+    }
+    throw new Error(`resolveGLSLTypeInfo.value: unsupported property type`);
+}
+function resolvePropertyUniform(name, material) {
+    const uniform = material.uniforms[`p_${name}`];
+    if (uniform === undefined) {
+        throw new Error(`resolvePropertyUniform.name: unknown uniform`);
+    }
+    return uniform;
+}
+
+export { resolveGLSLTypeInfo, resolvePropertyUniform };

package/dist/miscellaneous/FXTransparencyMode.d.ts

@@ -0,0 +1,7 @@
+/** Transparency rendering modes */
+export declare enum FXTransparencyMode {
+    /** Dithered transparency. Good performance. */
+    HASH = 0,
+    /** Alpha blending. Best quality. */
+    BLEND = 1
+}

package/dist/miscellaneous/asserts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validates value is finite number within safe range.
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is not finite or exceeds safe range
+ */
+export declare function assertValidNumber(value: number, subject: string): void;
+/**
+ * Validates value is positive (>= EPSILON).
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is invalid or below EPSILON
+ */
+export declare function assertValidPositiveNumber(value: number, subject: string): void;
+/**
+ * Validates value is non-negative (>= 0).
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is invalid or negative
+ */
+export declare function assertValidNonNegativeNumber(value: number, subject: string): void;

package/dist/miscellaneous/asserts.js

@@ -0,0 +1,48 @@
+import { EPSILON } from './math.js';
+
+/**
+ * Validates value is finite number within safe range.
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is not finite or exceeds safe range
+ */
+function assertValidNumber(value, subject) {
+    if (process.env.NODE_ENV !== "production") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`${subject}: value must be a finite number`);
+        }
+        if (Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+            throw new Error(`${subject}: value exceeds maximum safe integer range`);
+        }
+    }
+}
+/**
+ * Validates value is positive (>= EPSILON).
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is invalid or below EPSILON
+ */
+function assertValidPositiveNumber(value, subject) {
+    if (process.env.NODE_ENV !== "production") {
+        assertValidNumber(value, subject);
+        if (value < EPSILON) {
+            throw new Error(`${subject}: value must be greater than or equal to ${EPSILON}`);
+        }
+    }
+}
+/**
+ * Validates value is non-negative (>= 0).
+ * @param value Number to validate
+ * @param subject Value name for error messages
+ * @throws If value is invalid or negative
+ */
+function assertValidNonNegativeNumber(value, subject) {
+    if (process.env.NODE_ENV !== "production") {
+        assertValidNumber(value, subject);
+        if (value < 0) {
+            throw new Error(`${subject}: value must be greater than or equal to 0`);
+        }
+    }
+}
+
+export { assertValidNonNegativeNumber, assertValidNumber, assertValidPositiveNumber };

package/dist/miscellaneous/math.d.ts

@@ -0,0 +1,8 @@
+export declare const EPSILON = 0.000001;
+export interface Vector3Like {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export declare function srgbToLinear(color: number): number;
+export declare function linearToSRGB(color: number): number;

package/dist/miscellaneous/math.js

@@ -0,0 +1,11 @@
+const EPSILON = 1e-6;
+function srgbToLinear(color) {
+    return color < 0.04045
+        ? color * 0.0773993808
+        : Math.pow(color * 0.9478672986 + 0.0521327014, 2.4);
+}
+function linearToSRGB(color) {
+    return color < 0.0031308 ? color * 12.92 : 1.055 * Math.pow(color, 0.41666) - 0.055;
+}
+
+export { EPSILON, linearToSRGB, srgbToLinear };

package/dist/miscellaneous/miscellaneous.d.ts

@@ -0,0 +1,33 @@
+import type { Vector3Tuple } from "three";
+import { DataTexture } from "three";
+import type { FXColor } from "../color/FXColor";
+import type { Vector3Like } from "../miscellaneous/math";
+import type { FXTextureConfig } from "../miscellaneous/texture/FXTextureView.Internal";
+export interface FXRange {
+    min: number;
+    max: number;
+}
+export type FXRangeConfig = FXRange | [number, number, number] | number;
+export type FXVector3Config = Vector3Like | Vector3Tuple | number;
+export type FXAspectConfig = number | FXTextureConfig;
+export declare function resolveFXRangeConfig(config: FXRangeConfig): FXRange;
+export declare function resolveFXVector2Config(config: FXVector3Config): Vector3Like;
+export declare function resolveAspect(config: number | FXTextureConfig): number;
+export declare function generateNoise3D(x: number, y: number, z: number): number;
+export declare function buildGradientTexture(colors: FXColor[]): DataTexture;
+export declare const BUILTIN_OFFSET_POSITION_X = 0;
+export declare const BUILTIN_OFFSET_POSITION_Y = 1;
+export declare const BUILTIN_OFFSET_POSITION_Z = 2;
+export declare const BUILTIN_OFFSET_VELOCITY_X = 3;
+export declare const BUILTIN_OFFSET_VELOCITY_Y = 4;
+export declare const BUILTIN_OFFSET_VELOCITY_Z = 5;
+export declare const BUILTIN_OFFSET_SCALE_X = 6;
+export declare const BUILTIN_OFFSET_SCALE_Y = 7;
+export declare const BUILTIN_OFFSET_SCALE_Z = 8;
+export declare const BUILTIN_OFFSET_ROTATION = 9;
+export declare const BUILTIN_OFFSET_TORQUE = 10;
+export declare const BUILTIN_OFFSET_LIFETIME = 11;
+export declare const BUILTIN_OFFSET_AGE = 12;
+export declare const BUILTIN_OFFSET_RANDOM_A = 13;
+export declare const BUILTIN_OFFSET_RANDOM_B = 14;
+export declare const BUILTIN_OFFSET_RANDOM_C = 15;

package/dist/miscellaneous/miscellaneous.js

@@ -0,0 +1,66 @@
+import { Texture, DataTexture, RGBAFormat, UnsignedByteType, UVMapping, ClampToEdgeWrapping, LinearFilter, SRGBColorSpace } from 'three';
+
+function resolveFXRangeConfig(config) {
+    if (typeof config === "number") {
+        return { min: config, max: config };
+    }
+    if (Array.isArray(config)) {
+        return { min: config[0], max: config[1] };
+    }
+    return config;
+}
+function resolveFXVector2Config(config) {
+    if (typeof config === "number") {
+        return { x: config, y: config, z: config };
+    }
+    if (Array.isArray(config)) {
+        return { x: config[0], y: config[1], z: config[2] };
+    }
+    return config;
+}
+function resolveAspect(config) {
+    if (typeof config === "number") {
+        return config;
+    }
+    if (config instanceof Texture) {
+        return config.image.naturalWidth / config.image.naturalHeight;
+    }
+    return config.sourceSize.w / config.sourceSize.h;
+}
+function generateNoise3D(x, y, z) {
+    const noise = Math.sin(x * 12.9898 + y * 78.233 + z * 37.719) * 43758.5453123;
+    return (noise - Math.floor(noise)) * 2 - 1;
+}
+function buildGradientTexture(colors) {
+    const width = colors.length;
+    const height = 1;
+    const data = new Uint8Array(width * height * 4);
+    for (let i = 0; i < width; i++) {
+        const color = colors[i];
+        const index = i * 4;
+        data[index] = Math.round(color.r * 255);
+        data[index + 1] = Math.round(color.g * 255);
+        data[index + 2] = Math.round(color.b * 255);
+        data[index + 3] = Math.round(color.a * 255);
+    }
+    const texture = new DataTexture(data, width, height, RGBAFormat, UnsignedByteType, UVMapping, ClampToEdgeWrapping, ClampToEdgeWrapping, LinearFilter, LinearFilter, 1, SRGBColorSpace);
+    texture.needsUpdate = true;
+    return texture;
+}
+const BUILTIN_OFFSET_POSITION_X = 0;
+const BUILTIN_OFFSET_POSITION_Y = 1;
+const BUILTIN_OFFSET_POSITION_Z = 2;
+const BUILTIN_OFFSET_VELOCITY_X = 3;
+const BUILTIN_OFFSET_VELOCITY_Y = 4;
+const BUILTIN_OFFSET_VELOCITY_Z = 5;
+const BUILTIN_OFFSET_SCALE_X = 6;
+const BUILTIN_OFFSET_SCALE_Y = 7;
+const BUILTIN_OFFSET_ROTATION = 9;
+const BUILTIN_OFFSET_TORQUE = 10;
+const BUILTIN_OFFSET_LIFETIME = 11;
+const BUILTIN_OFFSET_AGE = 12;
+const BUILTIN_OFFSET_RANDOM_A = 13;
+const BUILTIN_OFFSET_RANDOM_B = 14;
+const BUILTIN_OFFSET_RANDOM_C = 15;
+
+export { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z, buildGradientTexture, generateNoise3D, resolveAspect, resolveFXRangeConfig, resolveFXVector2Config };

package/dist/miscellaneous/texture/FXTextureView.Internal.d.ts

@@ -0,0 +1,49 @@
+import { Texture } from "three";
+export declare const TEXTURE_DEFAULT_TEXTURE: Texture;
+export declare const TEXTURE_DEFAULT_SIZE = 2;
+/** Rectangle coordinates and dimensions in atlas */
+export interface FXTextureRect {
+    /** X coordinate in pixels */
+    x: number;
+    /** Y coordinate in pixels */
+    y: number;
+    /** Width in pixels */
+    w: number;
+    /** Height in pixels */
+    h: number;
+}
+/** Size dimensions */
+export interface FXTextureSize {
+    /** Width in pixels */
+    w: number;
+    /** Height in pixels */
+    h: number;
+}
+/** Transparent padding around visible content */
+export interface FXTextureTrim {
+    /** Left padding in world units */
+    left: number;
+    /** Right padding in world units */
+    right: number;
+    /** Top padding in world units */
+    top: number;
+    /** Bottom padding in world units */
+    bottom: number;
+}
+/** Configuration for texture atlas sprite */
+export interface FXTextureAtlasConfig {
+    /** Source texture atlas */
+    texture: Texture;
+    /** Rectangle in atlas containing sprite */
+    frame: FXTextureRect;
+    /** Whether sprite is rotated 90 degrees clockwise */
+    rotated?: boolean;
+    /** Position and size within original image before trimming */
+    spriteSourceSize: FXTextureRect;
+    /** Original image dimensions before trimming */
+    sourceSize: FXTextureSize;
+    /** Scale factor for resolution independence */
+    scale?: number;
+}
+/** Texture configuration from direct texture or atlas sprite */
+export type FXTextureConfig = Texture | FXTextureAtlasConfig;

package/dist/miscellaneous/texture/FXTextureView.Internal.js

@@ -0,0 +1,6 @@
+import { Texture } from 'three';
+
+const TEXTURE_DEFAULT_TEXTURE = new Texture();
+const TEXTURE_DEFAULT_SIZE = 2;
+
+export { TEXTURE_DEFAULT_SIZE, TEXTURE_DEFAULT_TEXTURE };

package/dist/miscellaneous/texture/FXTextureView.d.ts

@@ -0,0 +1,72 @@
+import type { FerrsignView3 } from "ferrsign";
+import { Matrix3, Texture, Vector2 } from "three";
+import type { FXTextureConfig } from "./FXTextureView.Internal";
+/** Wrapper for Three.js texture with atlas and trim support. Does not own the underlying texture; user must dispose it. */
+export declare class FXTextureView {
+    private textureInternal;
+    private sourceWidth;
+    private sourceHeight;
+    private frameX;
+    private frameY;
+    private frameWidth;
+    private frameHeight;
+    private rotatedInternal;
+    private scaleInternal;
+    private trimLeft;
+    private trimRight;
+    private trimTop;
+    private trimBottom;
+    private textureDirtyInternal;
+    private uvTransformDirtyInternal;
+    private trimDirtyInternal;
+    private readonly signalDiminsionsChangedInternal;
+    /** @param config Texture or atlas configuration */
+    constructor(config?: FXTextureConfig);
+    /** Original width before trimming in world units */
+    get width(): number;
+    /** Original height before trimming in world units */
+    get height(): number;
+    /** Visible width after trimming in world units */
+    get trimmedWidth(): number;
+    /** Visible height after trimming in world units */
+    get trimmedHeight(): number;
+    /** Underlying Three.js texture */
+    get texture(): Texture;
+    /** Whether sprite is rotated in atlas */
+    get rotated(): boolean;
+    /** Scale factor for resolution independence */
+    get scale(): number;
+    /** Transparent padding around visible content */
+    get trim(): Readonly<{
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    }>;
+    get textureDirty(): boolean;
+    /** Whether UV transform inputs changed since last check */
+    get uvTransformDirty(): boolean;
+    /** Whether trim values changed since last check */
+    get trimDirty(): boolean;
+    get signalDiminsionsChanged(): FerrsignView3<number, number, FXTextureView>;
+    setTextureDirtyFalse(): void;
+    /**
+     * Calculates UV transform matrix for shader sampling.
+     * @param result Matrix to store result in
+     * @returns UV transform matrix
+     */
+    calculateUVTransform(result?: Matrix3): Matrix3;
+    /**
+     * Gets original dimensions before trimming.
+     * @param result Vector to store result in
+     * @returns Width and height in world units
+     */
+    getResolution(result?: Vector2): Vector2;
+    /**
+     * Replaces texture with new configuration.
+     * @param config Texture or atlas configuration
+     */
+    set(config: FXTextureConfig): void;
+    private setFromTexture;
+    private setFromAtlasConfig;
+}