@pixagram/renderart 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pixagram SA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -0,0 +1,196 @@
+# @pixagram/renderart
+
+High-performance pixel art rendering engines with GPU (WebGL2) and CPU (WASM) support.
+
+## Features
+
+- **CRT Effect** (2-32x) - Classic CRT display simulation with barrel distortion, scanlines, and shadow mask
+- **HEX Upscaling** (2-32x) - Transform pixel art into hexagonal grid representations
+- **XBRZ Scaling** (2-6x) - Edge-preserving pixel art scaling algorithm
+
+All engines support:
+- ⚡ **GPU acceleration** via WebGL2 (CRT, HEX)
+- 🦀 **CPU fallback** via Rust/WASM (all engines)
+- 🎨 **Customizable presets** and fine-grained options
+- 📦 **Zero dependencies** - everything bundled
+
+## Installation
+
+```bash
+npm install @pixagram/renderart
+```
+
+## Quick Start
+
+```typescript
+import { RenderArt } from '@pixagram/renderart';
+
+// Initialize (loads WASM if needed)
+const renderer = await RenderArt.create();
+
+// Get your image data
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+
+// Apply CRT effect
+const crtResult = await renderer.crt.render(imageData, { scale: 3 });
+
+// Apply hexagonal transformation
+const hexResult = await renderer.hex.render(imageData, { scale: 16 });
+
+// Apply xBRZ scaling
+const xbrzResult = await renderer.xbrz.render(imageData, { scale: 4 });
+
+// Use the result
+ctx.putImageData(new ImageData(crtResult.data, crtResult.width, crtResult.height), 0, 0);
+```
+
+## API Reference
+
+### RenderArt
+
+Main class providing access to all rendering engines.
+
+```typescript
+const renderer = await RenderArt.create();
+
+// Access capabilities
+console.log(renderer.capabilities);
+// { gpu: true, cpu: true, maxTextureSize: 16384, recommendedBackend: 'gpu' }
+
+// Cleanup when done
+renderer.dispose();
+```
+
+### CRT Engine
+
+```typescript
+// With options
+const result = await renderer.crt.render(imageData, {
+  scale: 3,              // 2-32 (default: 3)
+  warpX: 0.015,          // Horizontal curvature (default: 0.015)
+  warpY: 0.02,           // Vertical curvature (default: 0.02)
+  scanHardness: -4.0,    // Scanline sharpness (default: -4.0)
+  scanOpacity: 0.5,      // Scanline intensity (default: 0.5)
+  maskOpacity: 0.3,      // Shadow mask intensity (default: 0.3)
+  enableWarp: true,      // Enable barrel distortion
+  enableScanlines: true, // Enable scanlines
+  enableMask: true,      // Enable shadow mask
+  backend: 'auto',       // 'gpu', 'cpu', or 'auto'
+});
+
+// With preset
+const result = await renderer.crt.render(imageData, 'authentic');
+// Presets: 'default', 'authentic', 'subtle', 'flat'
+
+// Synchronous GPU-only rendering
+const result = renderer.crt.renderSync(imageData, { scale: 3 });
+```
+
+### HEX Engine
+
+```typescript
+// With options
+const result = await renderer.hex.render(imageData, {
+  scale: 16,                    // 2-32 (default: 16)
+  orientation: 'flat-top',      // 'flat-top' or 'pointy-top'
+  drawBorders: true,            // Draw hexagon borders
+  borderColor: '#282828',       // Border color (CSS or 0xRRGGBBAA)
+  borderThickness: 1,           // Border thickness in pixels
+  backgroundColor: 'transparent', // Background color
+  backend: 'auto',
+});
+
+// With preset
+const result = await renderer.hex.render(imageData, 'bordered');
+// Presets: 'default', 'bordered', 'pointy'
+
+// Get output dimensions
+const dims = renderer.hex.getDimensions(64, 64, { scale: 16 });
+// { width: 123, height: 134 }
+```
+
+### XBRZ Engine
+
+```typescript
+// With options
+const result = await renderer.xbrz.render(imageData, {
+  scale: 4,                          // 2-6 (default: 2)
+  luminanceWeight: 1.0,              // Edge detection weight
+  equalColorTolerance: 30,           // Color matching tolerance
+  dominantDirectionThreshold: 4.4,   // Edge direction threshold
+  steepDirectionThreshold: 2.2,      // Steep edge threshold
+});
+
+// With preset
+const result = await renderer.xbrz.render(imageData, 'sharp');
+// Presets: 'default', 'sharp', 'smooth'
+
+// Get output dimensions
+const dims = renderer.xbrz.getDimensions(64, 64, 4);
+// { width: 256, height: 256 }
+```
+
+## Backend Selection
+
+Each engine automatically selects the best available backend:
+
+| Engine | GPU (WebGL2) | CPU (WASM) |
+|--------|--------------|------------|
+| CRT    | ✅ Primary   | ✅ Fallback |
+| HEX    | ✅ Primary   | ✅ Fallback |
+| XBRZ   | ❌ N/A       | ✅ Only     |
+
+Force a specific backend:
+```typescript
+// Force GPU
+const result = await renderer.crt.render(imageData, { backend: 'gpu' });
+
+// Force CPU
+const result = await renderer.crt.render(imageData, { backend: 'cpu' });
+```
+
+## Browser Support
+
+- Chrome 79+
+- Firefox 75+
+- Safari 15+
+- Edge 79+
+
+Requires:
+- WebGL2 for GPU rendering
+- WebAssembly for CPU rendering
+
+## Performance Tips
+
+1. **Reuse the renderer instance** - initialization is expensive
+2. **Use GPU when available** - significantly faster for CRT and HEX
+3. **Choose appropriate scale** - larger scales need more GPU memory
+4. **Consider XBRZ scale limits** - 2-6x only, higher factors use more CPU
+
+## Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build WASM module
+npm run build:wasm
+
+# Build TypeScript
+npm run build:ts
+
+# Full build
+npm run build
+
+# Run tests
+npm test
+```
+
+Requirements:
+- Node.js 16+
+- Rust toolchain
+- wasm-pack
+
+## License
+
+MIT © Pixagram SA

package/dist/index.d.mts

@@ -0,0 +1,331 @@
+/**
+ * Common types for RenderArt module
+ */
+/** RGBA pixel data as Uint8ClampedArray or Uint8Array */
+type PixelData = Uint8ClampedArray | Uint8Array;
+/** Input image data structure */
+interface ImageInput {
+    /** Raw RGBA pixel data */
+    data: PixelData;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+}
+/** Output image data structure */
+interface ImageOutput {
+    /** Raw RGBA pixel data */
+    data: Uint8ClampedArray;
+    /** Output width in pixels */
+    width: number;
+    /** Output height in pixels */
+    height: number;
+}
+/** Rendering backend type */
+type Backend = 'gpu' | 'cpu' | 'auto';
+/** CRT effect configuration */
+interface CrtOptions {
+    /** Scale factor (2-32, default: 3) */
+    scale?: number;
+    /** Horizontal warp intensity (0.0-0.1, default: 0.015) */
+    warpX?: number;
+    /** Vertical warp intensity (0.0-0.1, default: 0.02) */
+    warpY?: number;
+    /** Scanline hardness (-10 to 0, default: -4) */
+    scanHardness?: number;
+    /** Scanline opacity (0.0-1.0, default: 0.5) */
+    scanOpacity?: number;
+    /** Shadow mask opacity (0.0-1.0, default: 0.3) */
+    maskOpacity?: number;
+    /** Enable barrel distortion (default: true) */
+    enableWarp?: boolean;
+    /** Enable scanlines (default: true) */
+    enableScanlines?: boolean;
+    /** Enable shadow mask (default: true) */
+    enableMask?: boolean;
+    /** Rendering backend (default: 'auto') */
+    backend?: Backend;
+}
+/** CRT preset names */
+type CrtPreset = 'default' | 'authentic' | 'subtle' | 'flat';
+/** Hexagon orientation */
+type HexOrientation = 'flat-top' | 'pointy-top';
+/** Hexagonal upscaling configuration */
+interface HexOptions {
+    /** Scale factor (2-32, default: 16) */
+    scale?: number;
+    /** Hexagon orientation (default: 'flat-top') */
+    orientation?: HexOrientation;
+    /** Draw hexagon borders (default: false) */
+    drawBorders?: boolean;
+    /** Border color as CSS color or 0xRRGGBBAA (default: '#282828') */
+    borderColor?: string | number;
+    /** Border thickness in pixels (default: 1) */
+    borderThickness?: number;
+    /** Background color (default: 'transparent') */
+    backgroundColor?: string | number;
+    /** Rendering backend (default: 'auto') */
+    backend?: Backend;
+}
+/** HEX preset names */
+type HexPreset = 'default' | 'bordered' | 'pointy';
+/** xBRZ scaling configuration */
+interface XbrzOptions {
+    /** Scale factor (2-6, default: 2) */
+    scale?: number;
+    /** Luminance weight for edge detection (0.0-1.0, default: 1.0) */
+    luminanceWeight?: number;
+    /** Equal color tolerance (0-50, default: 30) */
+    equalColorTolerance?: number;
+    /** Dominant direction threshold (3.5-6.0, default: 4.4) */
+    dominantDirectionThreshold?: number;
+    /** Steep direction threshold (2.0-3.0, default: 2.2) */
+    steepDirectionThreshold?: number;
+}
+/** XBRZ preset names */
+type XbrzPreset = 'default' | 'sharp' | 'smooth';
+/** Renderer capabilities */
+interface RendererCapabilities {
+    /** WebGL2 GPU rendering available */
+    gpu: boolean;
+    /** WASM CPU rendering available */
+    cpu: boolean;
+    /** Maximum texture size (GPU) */
+    maxTextureSize: number;
+    /** Recommended backend for current device */
+    recommendedBackend: Backend;
+}
+/** Render statistics */
+interface RenderStats {
+    /** Rendering time in milliseconds */
+    renderTimeMs: number;
+    /** Backend used for rendering */
+    backend: Backend;
+    /** Input dimensions */
+    inputSize: {
+        width: number;
+        height: number;
+    };
+    /** Output dimensions */
+    outputSize: {
+        width: number;
+        height: number;
+    };
+}
+/** Common renderer interface */
+interface Renderer<TOptions> {
+    /** Render image with options */
+    render(input: ImageInput | ImageData, options?: TOptions): ImageOutput;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Dispose resources */
+    dispose(): void;
+}
+
+/**
+ * CRT GPU Renderer using WebGL2
+ *
+ * High-performance CRT effect rendering using fragment shaders.
+ */
+
+/** CRT GPU Renderer */
+declare class CrtGpuRenderer implements Renderer<CrtOptions> {
+    private gl;
+    private canvas;
+    private program;
+    private texture;
+    private uniforms;
+    private initialized;
+    private currentCanvasSize;
+    private currentTexSize;
+    /** Create a new CRT GPU renderer */
+    static create(): CrtGpuRenderer;
+    private init;
+    private createShader;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Render CRT effect */
+    render(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
+    /** Dispose resources */
+    dispose(): void;
+}
+/** CRT presets */
+declare const CRT_PRESETS: Record<string, Partial<CrtOptions>>;
+
+/**
+ * Hexagonal GPU Renderer using WebGL2
+ *
+ * High-performance hexagonal pixel grid transformation using fragment shaders.
+ */
+
+/** Calculate output dimensions for hex rendering */
+declare function hexGetDimensions(srcWidth: number, srcHeight: number, scale: number, orientation?: HexOrientation): {
+    width: number;
+    height: number;
+};
+/** HEX GPU Renderer */
+declare class HexGpuRenderer implements Renderer<HexOptions> {
+    private gl;
+    private canvas;
+    private program;
+    private texture;
+    private uniforms;
+    private initialized;
+    private currentCanvasSize;
+    private currentTexSize;
+    /** Create a new HEX GPU renderer */
+    static create(): HexGpuRenderer;
+    private init;
+    private createShader;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Render hexagonal effect */
+    render(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
+    /** Dispose resources */
+    dispose(): void;
+}
+/** HEX presets */
+declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
+
+/**
+ * WASM Module Loader
+ *
+ * Handles loading and initialization of the Rust WASM module.
+ */
+
+/** Load WASM module */
+declare function loadWasm(): Promise<any>;
+/** Check if WASM is loaded */
+declare function isWasmLoaded(): boolean;
+/** CRT CPU Renderer using WASM */
+declare class CrtCpuRenderer {
+    private ready;
+    /** Create and initialize renderer */
+    static create(): Promise<CrtCpuRenderer>;
+    private init;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Render CRT effect */
+    render(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
+    /** Dispose resources */
+    dispose(): void;
+}
+/** HEX CPU Renderer using WASM */
+declare class HexCpuRenderer {
+    private ready;
+    /** Create and initialize renderer */
+    static create(): Promise<HexCpuRenderer>;
+    private init;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Render hexagonal effect */
+    render(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
+    /** Get output dimensions */
+    getDimensions(srcWidth: number, srcHeight: number, scale: number, orientation?: HexOrientation): {
+        width: number;
+        height: number;
+    };
+    /** Dispose resources */
+    dispose(): void;
+}
+/** XBRZ CPU Renderer using WASM */
+declare class XbrzCpuRenderer {
+    private ready;
+    /** Create and initialize renderer */
+    static create(): Promise<XbrzCpuRenderer>;
+    private init;
+    /** Check if renderer is ready */
+    isReady(): boolean;
+    /** Render xBRZ scaling */
+    render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
+    /** Dispose resources */
+    dispose(): void;
+}
+/** XBRZ presets */
+declare const XBRZ_PRESETS: Record<string, Partial<XbrzOptions>>;
+
+/**
+ * RenderArt - Unified Pixel Art Rendering Engine
+ *
+ * Provides a unified API for all rendering engines (CRT, HEX, XBRZ)
+ * with automatic backend selection (GPU/CPU).
+ */
+
+/** CRT rendering engine with GPU/CPU backend support */
+declare class CrtEngine {
+    private gpuRenderer;
+    private cpuRenderer;
+    private gpuAvailable;
+    private cpuAvailable;
+    constructor(gpuAvailable: boolean, cpuAvailable: boolean);
+    /** Initialize GPU renderer */
+    private ensureGpu;
+    /** Initialize CPU renderer */
+    private ensureCpu;
+    /** Render with automatic backend selection */
+    render(input: ImageInput | ImageData, options?: CrtOptions): Promise<ImageOutput>;
+    /** Render with preset */
+    render(input: ImageInput | ImageData, preset: CrtPreset, overrides?: Partial<CrtOptions>): Promise<ImageOutput>;
+    /** Render synchronously (GPU only) */
+    renderSync(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
+    /** Dispose resources */
+    dispose(): void;
+}
+/** HEX rendering engine with GPU/CPU backend support */
+declare class HexEngine {
+    private gpuRenderer;
+    private cpuRenderer;
+    private gpuAvailable;
+    private cpuAvailable;
+    constructor(gpuAvailable: boolean, cpuAvailable: boolean);
+    private ensureGpu;
+    private ensureCpu;
+    /** Render with automatic backend selection */
+    render(input: ImageInput | ImageData, options?: HexOptions): Promise<ImageOutput>;
+    /** Render with preset */
+    render(input: ImageInput | ImageData, preset: HexPreset, overrides?: Partial<HexOptions>): Promise<ImageOutput>;
+    /** Render synchronously (GPU only) */
+    renderSync(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
+    /** Get output dimensions */
+    getDimensions(srcWidth: number, srcHeight: number, options?: HexOptions): {
+        width: number;
+        height: number;
+    };
+    dispose(): void;
+}
+/** XBRZ rendering engine (CPU only - algorithm too complex for efficient GPU) */
+declare class XbrzEngine {
+    private cpuRenderer;
+    private cpuAvailable;
+    constructor(cpuAvailable: boolean);
+    private ensureCpu;
+    /** Render xBRZ scaling */
+    render(input: ImageInput | ImageData, options?: XbrzOptions): Promise<ImageOutput>;
+    /** Render with preset */
+    render(input: ImageInput | ImageData, preset: XbrzPreset, overrides?: Partial<XbrzOptions>): Promise<ImageOutput>;
+    /** Get output dimensions */
+    getDimensions(srcWidth: number, srcHeight: number, scale?: number): {
+        width: number;
+        height: number;
+    };
+    dispose(): void;
+}
+/** RenderArt - Unified Pixel Art Rendering Engine */
+declare class RenderArt {
+    /** CRT effect renderer */
+    readonly crt: CrtEngine;
+    /** Hexagonal pixel renderer */
+    readonly hex: HexEngine;
+    /** xBRZ scaling renderer */
+    readonly xbrz: XbrzEngine;
+    private _capabilities;
+    private constructor();
+    /** Create and initialize RenderArt instance */
+    static create(): Promise<RenderArt>;
+    /** Get renderer capabilities */
+    get capabilities(): RendererCapabilities;
+    /** Dispose all resources */
+    dispose(): void;
+}
+
+export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, type XbrzOptions, type XbrzPreset, hexGetDimensions, isWasmLoaded, loadWasm };