@pixagram/renderart 0.2.0 → 0.2.2

package/README.md

@@ -4,15 +4,9 @@ High-performance pixel art rendering engines with GPU (WebGL2) and CPU (WASM) su
 
 ## 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** in core bundle
+- **CRT Effect** (2-32x) - Classic CRT display simulation
+- **HEX Upscaling** (2-32x) - Hexagonal grid transformation
+- **XBRZ Scaling** (2-6x) - Edge-preserving pixel art scaling
 
 ## Installation
 
@@ -22,190 +16,130 @@ npm install @pixagram/renderart
 
 ## Quick Start
 
-### GPU-Only Mode (Simplest - No WASM)
+### GPU-Only (Simplest - No WASM needed)
 
 ```typescript
-import { RenderArt } from '@pixagram/renderart';
-
-// Create GPU-only renderer (no WASM loading required)
-const renderer = RenderArt.createGpuOnly();
-
-// Get your image data
-const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
-
-// Apply CRT effect (GPU)
-const crtResult = renderer.crt.renderSync(imageData, { scale: 3 });
+import { CrtGpuRenderer } from '@pixagram/renderart';
 
-// Apply HEX effect (GPU)
-const hexResult = renderer.hex.renderSync(imageData, { scale: 16 });
+const crt = CrtGpuRenderer.create();
+const result = crt.render(imageData, { scale: 3 });
 
 // Use the result
-ctx.putImageData(new ImageData(crtResult.data, crtResult.width, crtResult.height), 0, 0);
+ctx.putImageData(new ImageData(result.data, result.width, result.height), 0, 0);
 ```
 
-### With CPU Fallback (Requires WASM)
+### With CPU Fallback (Auto WASM loading)
 
 ```typescript
-import { RenderArt, initWasm } from '@pixagram/renderart';
-import init, * as wasm from '@pixagram/renderart/pkg/renderart_wasm.js';
+import { RenderArt, setWasmUrl } from '@pixagram/renderart';
 
-// Initialize WASM module first
-await initWasm(() => init(), wasm);
+// Configure WASM path (copy renderart_wasm.wasm to your public folder)
+setWasmUrl('/wasm/renderart_wasm.wasm');
 
-// Create renderer with CPU fallback
 const renderer = RenderArt.create();
 
-// Now all engines work, including XBRZ (CPU-only)
-const xbrzResult = renderer.xbrz.render(imageData, { scale: 4 });
+// GPU when available, auto-loads WASM for CPU fallback
+const result = await renderer.crt.render(imageData, { scale: 3 });
+
+// XBRZ is CPU-only (auto-loads WASM on first use)
+const xbrzResult = await renderer.xbrz.render(imageData, { scale: 4 });
 ```
 
-### Direct GPU Renderer Usage
+### Pre-load WASM
 
 ```typescript
-import { CrtGpuRenderer, HexGpuRenderer } from '@pixagram/renderart';
+import { initWasm, setWasmUrl } from '@pixagram/renderart';
 
-// Use GPU renderers directly (no WASM needed)
-const crt = CrtGpuRenderer.create();
-const result = crt.render(imageData, {
-  scale: 3,
-  warpX: 0.02,
-  scanOpacity: 0.6,
-});
-
-// Clean up
-crt.dispose();
+// Pre-load WASM for faster first CPU render
+setWasmUrl('/wasm/renderart_wasm.wasm');
+await initWasm();
 ```
 
-## API Reference
+## WASM Setup
 
-### RenderArt (Unified API)
+1. Build the WASM module:
+   ```bash
+   cd node_modules/@pixagram/renderart
+   npm run build:wasm
+   ```
 
-```typescript
-// GPU-only mode
-const renderer = RenderArt.createGpuOnly();
-
-// With CPU fallback (requires WASM init first)
-const renderer = RenderArt.create();
+2. Copy `wasm/renderart_wasm.wasm` to your public folder
 
-// Access capabilities
-console.log(renderer.capabilities);
-// { gpu: true, cpu: true, maxTextureSize: 16384, recommendedBackend: 'gpu' }
+3. Configure the path:
+   ```typescript
+   import { setWasmUrl } from '@pixagram/renderart';
+   setWasmUrl('/your/path/renderart_wasm.wasm');
+   ```
 
-// Cleanup
-renderer.dispose();
-```
+## API Reference
 
-### CRT Engine
+### CRT Options
 
 ```typescript
-// With options
-const result = renderer.crt.render(imageData, {
-  scale: 3,              // 2-32 (default: 3)
+{
+  scale: 3,              // 2-32
   warpX: 0.015,          // Horizontal curvature
   warpY: 0.02,           // Vertical curvature
   scanHardness: -4.0,    // Scanline sharpness
   scanOpacity: 0.5,      // Scanline intensity
   maskOpacity: 0.3,      // Shadow mask intensity
-  enableWarp: true,      // Enable barrel distortion
-  enableScanlines: true, // Enable scanlines
-  enableMask: true,      // Enable shadow mask
+  enableWarp: true,
+  enableScanlines: true,
+  enableMask: true,
   backend: 'auto',       // 'gpu', 'cpu', or 'auto'
-});
-
-// With preset
-const result = renderer.crt.render(imageData, 'authentic');
-// Presets: 'default', 'authentic', 'subtle', 'flat'
-
-// Synchronous GPU-only rendering
-const result = renderer.crt.renderSync(imageData, { scale: 3 });
+}
 ```
 
-### HEX Engine
+### HEX Options
 
 ```typescript
-// With options
-const result = renderer.hex.render(imageData, {
-  scale: 16,                    // 2-32 (default: 16)
+{
+  scale: 16,                    // 2-32
   orientation: 'flat-top',      // 'flat-top' or 'pointy-top'
-  drawBorders: true,            // Draw hexagon borders
-  borderColor: '#282828',       // Border color
-  borderThickness: 1,           // Border thickness
+  drawBorders: false,
+  borderColor: '#282828',
+  borderThickness: 1,
   backgroundColor: 'transparent',
   backend: 'auto',
-});
-
-// With preset
-const result = renderer.hex.render(imageData, 'bordered');
-// Presets: 'default', 'bordered', 'pointy'
-
-// Get output dimensions
-const dims = renderer.hex.getDimensions(64, 64, { scale: 16 });
+}
 ```
 
-### XBRZ Engine (CPU Only)
+### XBRZ Options
 
 ```typescript
-// Requires WASM initialization
-const result = renderer.xbrz.render(imageData, {
-  scale: 4,                          // 2-6 (default: 2)
+{
+  scale: 4,                          // 2-6
   luminanceWeight: 1.0,
   equalColorTolerance: 30,
   dominantDirectionThreshold: 4.4,
   steepDirectionThreshold: 2.2,
-});
-
-// With preset
-const result = renderer.xbrz.render(imageData, 'sharp');
-// Presets: 'default', 'sharp', 'smooth'
+}
 ```
 
-## Backend Selection
-
-| Engine | GPU (WebGL2) | CPU (WASM) |
-|--------|--------------|------------|
-| CRT    | ✅ Primary   | ✅ Fallback |
-| HEX    | ✅ Primary   | ✅ Fallback |
-| XBRZ   | ❌ N/A       | ✅ Only     |
-
-## WASM Loading with Custom Path
+## Presets
 
 ```typescript
-import { initWasm } from '@pixagram/renderart';
-import init, * as wasm from '@pixagram/renderart/pkg/renderart_wasm.js';
-
-// Load WASM from custom URL
-await initWasm(
-  () => init('/static/wasm/renderart_wasm_bg.wasm'),
-  wasm
-);
+// CRT presets
+renderer.crt.render(imageData, 'authentic');  // Strong CRT look
+renderer.crt.render(imageData, 'subtle');     // Light CRT effect
+renderer.crt.render(imageData, 'flat');       // No curvature
+
+// HEX presets
+renderer.hex.render(imageData, 'bordered');   // With borders
+renderer.hex.render(imageData, 'pointy');     // Pointy-top orientation
+
+// XBRZ presets
+renderer.xbrz.render(imageData, 'sharp');     // Sharp edges
+renderer.xbrz.render(imageData, 'smooth');    // Smoother output
 ```
 
-## Browser Support
-
-- Chrome 79+
-- Firefox 75+
-- Safari 15+
-- Edge 79+
-
-Requires:
-- WebGL2 for GPU rendering
-- WebAssembly for CPU rendering
-
-## Building from Source
-
-```bash
-# Install dependencies
-npm install
-
-# Build WASM module (requires Rust + wasm-pack)
-npm run build:wasm
-
-# Build TypeScript
-npm run build:ts
+## Backend Selection
 
-# Full build
-npm run build
-```
+| Engine | GPU | CPU |
+|--------|-----|-----|
+| CRT    | ✅  | ✅  |
+| HEX    | ✅  | ✅  |
+| XBRZ   | ❌  | ✅  |
 
 ## License
 

package/dist/index.d.mts

@@ -190,80 +190,56 @@ declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
 /**
  * WASM Module Loader
  *
- * Handles loading and initialization of the Rust WASM module.
- * Requires explicit initialization - does NOT auto-import WASM.
- *
- * @example
- * ```typescript
- * import { initWasm } from '@pixagram/renderart';
- * import init from '@pixagram/renderart/pkg/renderart_wasm.js';
- *
- * // Initialize with the WASM module
- * await initWasm(init);
- * ```
+ * Auto-initializes WASM from URL. Works with any bundler.
  */
 
 /**
- * Initialize WASM module
+ * Configure WASM loading path
+ * Call this before using any CPU renderer if you need a custom path.
  *
- * @param wasmInit - The init function from renderart_wasm.js
- * @param wasmUrl - Optional URL to the .wasm file (for custom loading)
+ * @param url - URL to the renderart_wasm_bg.wasm file
  *
  * @example
  * ```typescript
- * // Option 1: Let wasm-pack handle loading
- * import init, * as wasm from '@pixagram/renderart/pkg/renderart_wasm.js';
- * await initWasm(init, wasm);
- *
- * // Option 2: With custom WASM URL
- * import init, * as wasm from '@pixagram/renderart/pkg/renderart_wasm.js';
- * await initWasm(() => init('/path/to/renderart_wasm_bg.wasm'), wasm);
+ * setWasmUrl('/static/wasm/renderart_wasm_bg.wasm');
  * ```
  */
-declare function initWasm(wasmInit: () => Promise<void>, wasm: any): Promise<void>;
+declare function setWasmUrl(url: string): void;
+/**
+ * Initialize WASM module
+ * Called automatically on first CPU renderer use.
+ * Can be called manually for preloading.
+ */
+declare function initWasm(customUrl?: string): Promise<void>;
 /** Check if WASM is loaded */
 declare function isWasmLoaded(): boolean;
-/** Get the WASM module (throws if not initialized) */
-declare function getWasmModule(): any;
 /** CRT CPU Renderer using WASM */
 declare class CrtCpuRenderer {
     private ready;
-    /** Create renderer (WASM must be initialized first via initWasm) */
-    static create(): CrtCpuRenderer;
-    /** Check if renderer is ready */
+    /** Create and initialize renderer (auto-loads WASM) */
+    static create(): Promise<CrtCpuRenderer>;
     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 renderer (WASM must be initialized first via initWasm) */
-    static create(): HexCpuRenderer;
-    /** Check if renderer is ready */
+    static create(): Promise<HexCpuRenderer>;
     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 renderer (WASM must be initialized first via initWasm) */
-    static create(): XbrzCpuRenderer;
-    /** Check if renderer is ready */
+    static create(): Promise<XbrzCpuRenderer>;
     isReady(): boolean;
-    /** Render xBRZ scaling */
     render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
-    /** Dispose resources */
     dispose(): void;
 }
 /** XBRZ presets */
@@ -272,77 +248,47 @@ 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).
- *
- * GPU renderers work standalone. CPU renderers require WASM initialization.
- *
- * @example
- * ```typescript
- * // GPU-only (no WASM needed)
- * const renderer = RenderArt.createGpuOnly();
- * const result = renderer.crt.renderSync(imageData, { scale: 3 });
- *
- * // With CPU fallback (requires WASM init)
- * import init, * as wasm from '@pixagram/renderart/pkg/renderart_wasm.js';
- * await initWasm(init, wasm);
- * const renderer = RenderArt.create();
- * ```
+ * GPU renderers work standalone. CPU renderers auto-initialize WASM.
  */
 
-/** CRT rendering engine with GPU/CPU backend support */
+/** CRT rendering engine */
 declare class CrtEngine {
     private gpuRenderer;
     private cpuRenderer;
     private gpuAvailable;
-    private cpuAvailable;
-    constructor(gpuAvailable: boolean, cpuAvailable: boolean);
-    /** Initialize GPU renderer */
+    constructor(gpuAvailable: boolean);
     private ensureGpu;
-    /** Initialize CPU renderer */
     private ensureCpu;
     /** Render with automatic backend selection */
-    render(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
-    /** Render with preset */
-    render(input: ImageInput | ImageData, preset: CrtPreset, overrides?: Partial<CrtOptions>): ImageOutput;
+    render(input: ImageInput | ImageData, options?: CrtOptions): Promise<ImageOutput>;
+    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 */
+/** HEX rendering engine */
 declare class HexEngine {
     private gpuRenderer;
     private cpuRenderer;
     private gpuAvailable;
-    private cpuAvailable;
-    constructor(gpuAvailable: boolean, cpuAvailable: boolean);
+    constructor(gpuAvailable: boolean);
     private ensureGpu;
     private ensureCpu;
-    /** Render with automatic backend selection */
-    render(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
-    /** Render with preset */
-    render(input: ImageInput | ImageData, preset: HexPreset, overrides?: Partial<HexOptions>): ImageOutput;
-    /** Render synchronously (GPU only) */
+    render(input: ImageInput | ImageData, options?: HexOptions): Promise<ImageOutput>;
+    render(input: ImageInput | ImageData, preset: HexPreset, overrides?: Partial<HexOptions>): Promise<ImageOutput>;
     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) */
+/** XBRZ rendering engine (CPU only) */
 declare class XbrzEngine {
     private cpuRenderer;
-    private cpuAvailable;
-    constructor(cpuAvailable: boolean);
     private ensureCpu;
-    /** Render xBRZ scaling */
-    render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
-    /** Render with preset */
-    render(input: ImageInput | ImageData, preset: XbrzPreset, overrides?: Partial<XbrzOptions>): ImageOutput;
-    /** Get output dimensions */
+    render(input: ImageInput | ImageData, options?: XbrzOptions): Promise<ImageOutput>;
+    render(input: ImageInput | ImageData, preset: XbrzPreset, overrides?: Partial<XbrzOptions>): Promise<ImageOutput>;
     getDimensions(srcWidth: number, srcHeight: number, scale?: number): {
         width: number;
         height: number;
@@ -351,29 +297,19 @@ declare class XbrzEngine {
 }
 /** 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 RenderArt instance
-     * GPU renderers always available if WebGL2 supported.
-     * CPU renderers require WASM to be initialized via initWasm() first.
-     */
+    /** Create RenderArt instance */
     static create(): RenderArt;
-    /**
-     * Create GPU-only RenderArt instance (no WASM required)
-     * CPU fallback will not be available.
-     */
+    /** Create GPU-only instance */
     static createGpuOnly(): RenderArt;
-    /** Get renderer capabilities */
+    /** Pre-initialize WASM for faster first CPU render */
+    preloadWasm(wasmUrl?: string): Promise<void>;
     get capabilities(): RendererCapabilities;
-    /** Dispose all resources */
     dispose(): void;
 }
 
-export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, getWasmModule, hexGetDimensions, initWasm, isWasmLoaded };
+export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, hexGetDimensions, initWasm, isWasmLoaded, setWasmUrl };