@pixagram/renderart 0.2.2 → 0.3.0

package/README.md

@@ -4,9 +4,15 @@ High-performance pixel art rendering engines with GPU (WebGL2) and CPU (WASM) su
 
 ## Features
 
-- **CRT Effect** (2-32x) - Classic CRT display simulation
-- **HEX Upscaling** (2-32x) - Hexagonal grid transformation
-- **XBRZ Scaling** (2-6x) - Edge-preserving pixel art scaling
+- **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
+- 🔄 **Auto-initialization** - WASM loads automatically on first use
 
 ## Installation
 
@@ -14,70 +20,115 @@ High-performance pixel art rendering engines with GPU (WebGL2) and CPU (WASM) su
 npm install @pixagram/renderart
 ```
 
-## Quick Start
+## ⚠️ Building from Source (Required)
 
-### GPU-Only (Simplest - No WASM needed)
+The package includes placeholder WASM. You **must** build the actual WASM module:
 
-```typescript
-import { CrtGpuRenderer } from '@pixagram/renderart';
+```bash
+# Prerequisites: Rust + wasm-pack
+# Install wasm-pack: https://rustwasm.github.io/wasm-pack/installer/
 
-const crt = CrtGpuRenderer.create();
-const result = crt.render(imageData, { scale: 3 });
+cd node_modules/@pixagram/renderart
+npm run build:wasm
+```
 
-// Use the result
-ctx.putImageData(new ImageData(result.data, result.width, result.height), 0, 0);
+Or build everything:
+```bash
+npm run build
 ```
 
-### With CPU Fallback (Auto WASM loading)
+## Quick Start
 
 ```typescript
-import { RenderArt, setWasmUrl } from '@pixagram/renderart';
+import { RenderArt } from '@pixagram/renderart';
 
-// Configure WASM path (copy renderart_wasm.wasm to your public folder)
-setWasmUrl('/wasm/renderart_wasm.wasm');
+// Create renderer (auto-initializes WASM)
+const renderer = await RenderArt.create();
 
-const renderer = RenderArt.create();
+// Get your image data
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 
-// GPU when available, auto-loads WASM for CPU fallback
-const result = await renderer.crt.render(imageData, { scale: 3 });
+// Apply CRT effect
+const crtResult = await renderer.crt.render(imageData, { scale: 3 });
 
-// XBRZ is CPU-only (auto-loads WASM on first use)
+// Apply HEX effect
+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);
 ```
 
-### Pre-load WASM
+### GPU-Only Mode (Sync, No WASM)
 
 ```typescript
-import { initWasm, setWasmUrl } from '@pixagram/renderart';
+import { RenderArt } from '@pixagram/renderart';
 
-// Pre-load WASM for faster first CPU render
-setWasmUrl('/wasm/renderart_wasm.wasm');
-await initWasm();
+// Create GPU-only renderer (no WASM loading)
+const renderer = RenderArt.createGpuOnly();
+
+// Synchronous rendering
+const result = renderer.crt.renderSync(imageData, { scale: 3 });
 ```
 
-## WASM Setup
+### Direct Renderer Usage
 
-1. Build the WASM module:
-   ```bash
-   cd node_modules/@pixagram/renderart
-   npm run build:wasm
-   ```
+```typescript
+import { CrtGpuRenderer } from '@pixagram/renderart';
 
-2. Copy `wasm/renderart_wasm.wasm` to your public folder
+// Use GPU renderer directly (no WASM needed)
+const crt = CrtGpuRenderer.create();
+const result = crt.render(imageData, { scale: 3 });
+crt.dispose();
+```
 
-3. Configure the path:
-   ```typescript
-   import { setWasmUrl } from '@pixagram/renderart';
-   setWasmUrl('/your/path/renderart_wasm.wasm');
-   ```
+## Webpack Configuration
+
+For webpack 5, add to your webpack.config.js:
+
+```javascript
+module.exports = {
+  experiments: {
+    asyncWebAssembly: true,
+  },
+  module: {
+    rules: [
+      {
+        test: /\.wasm$/,
+        type: 'webassembly/async',
+      },
+    ],
+  },
+};
+```
 
 ## API Reference
 
-### CRT Options
+### RenderArt (Unified API)
 
 ```typescript
-{
-  scale: 3,              // 2-32
+// With CPU fallback (auto-loads WASM)
+const renderer = await RenderArt.create();
+
+// GPU-only mode
+const renderer = RenderArt.createGpuOnly();
+
+// Access capabilities
+console.log(renderer.capabilities);
+// { gpu: true, cpu: true, maxTextureSize: 16384, recommendedBackend: 'gpu' }
+
+// Cleanup
+renderer.dispose();
+```
+
+### CRT Engine
+
+```typescript
+// Async with auto backend selection
+const result = await renderer.crt.render(imageData, {
+  scale: 3,              // 2-32 (default: 3)
   warpX: 0.015,          // Horizontal curvature
   warpY: 0.02,           // Vertical curvature
   scanHardness: -4.0,    // Scanline sharpness
@@ -87,59 +138,85 @@ await initWasm();
   enableScanlines: true,
   enableMask: true,
   backend: 'auto',       // 'gpu', 'cpu', or 'auto'
-}
+});
+
+// With preset
+const result = await renderer.crt.render(imageData, 'authentic');
+// Presets: 'default', 'authentic', 'subtle', 'flat'
+
+// Sync GPU-only
+const result = renderer.crt.renderSync(imageData, { scale: 3 });
 ```
 
-### HEX Options
+### HEX Engine
 
 ```typescript
-{
-  scale: 16,                    // 2-32
+const result = await renderer.hex.render(imageData, {
+  scale: 16,                    // 2-32 (default: 16)
   orientation: 'flat-top',      // 'flat-top' or 'pointy-top'
-  drawBorders: false,
+  drawBorders: true,
   borderColor: '#282828',
   borderThickness: 1,
   backgroundColor: 'transparent',
-  backend: 'auto',
-}
+});
+
+// Presets: 'default', 'bordered', 'pointy'
+const result = await renderer.hex.render(imageData, 'bordered');
+
+// Get output dimensions
+const dims = renderer.hex.getDimensions(64, 64, { scale: 16 });
 ```
 
-### XBRZ Options
+### XBRZ Engine (CPU Only)
 
 ```typescript
-{
-  scale: 4,                          // 2-6
+const result = await renderer.xbrz.render(imageData, {
+  scale: 4,                          // 2-6 (default: 2)
   luminanceWeight: 1.0,
   equalColorTolerance: 30,
   dominantDirectionThreshold: 4.4,
   steepDirectionThreshold: 2.2,
-}
+});
+
+// Presets: 'default', 'sharp', 'smooth'
+const result = await renderer.xbrz.render(imageData, 'sharp');
 ```
 
-## Presets
+## Backend Support
 
-```typescript
-// 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
-```
+| Engine | GPU (WebGL2) | CPU (WASM) |
+|--------|--------------|------------|
+| CRT    | ✅ Primary   | ✅ Fallback |
+| HEX    | ✅ Primary   | ✅ Fallback |
+| XBRZ   | ❌ N/A       | ✅ Only     |
+
+## Browser Support
+
+- Chrome 79+
+- Firefox 75+
+- Safari 15+
+- Edge 79+
+
+## Development
 
-## Backend Selection
+```bash
+# Clone and install
+git clone https://github.com/pixagram/renderart.git
+cd renderart
+npm install
+
+# Build WASM (requires Rust + wasm-pack)
+npm run build:wasm
+
+# Build TypeScript
+npm run build:ts
 
-| Engine | GPU | CPU |
-|--------|-----|-----|
-| CRT    | ✅  | ✅  |
-| HEX    | ✅  | ✅  |
-| XBRZ   | ❌  | ✅  |
+# Full build
+npm run build
+
+# Run tests
+npm test
+```
 
 ## License
 

package/dist/index.d.mts

@@ -190,56 +190,68 @@ declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
 /**
  * WASM Module Loader
  *
- * Auto-initializes WASM from URL. Works with any bundler.
+ * Handles loading and initialization of the Rust WASM module.
+ * Auto-initializes on first use.
  */
 
 /**
- * Configure WASM loading path
- * Call this before using any CPU renderer if you need a custom path.
+ * Initialize WASM module (auto-called on first use)
+ * Can be called manually to pre-load WASM.
  *
- * @param url - URL to the renderart_wasm_bg.wasm file
- *
- * @example
- * ```typescript
- * setWasmUrl('/static/wasm/renderart_wasm_bg.wasm');
- * ```
- */
-declare function setWasmUrl(url: string): void;
-/**
- * Initialize WASM module
- * Called automatically on first CPU renderer use.
- * Can be called manually for preloading.
+ * @param wasmUrl - Optional URL to the .wasm file.
  */
-declare function initWasm(customUrl?: string): Promise<void>;
+declare function initWasm(wasmUrl?: string): Promise<void>;
 /** Check if WASM is loaded */
 declare function isWasmLoaded(): boolean;
-/** CRT CPU Renderer using WASM */
+/** Check if WASM loading failed */
+declare function hasWasmError(): boolean;
+/** Get WASM loading error if any */
+declare function getWasmError(): Error | null;
+/** CRT CPU Renderer using WASM (auto-initializes) */
 declare class CrtCpuRenderer {
-    private ready;
-    /** Create and initialize renderer (auto-loads WASM) */
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<CrtCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** 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 */
+/** HEX CPU Renderer using WASM (auto-initializes) */
 declare class HexCpuRenderer {
-    private ready;
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<HexCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** 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 */
+/** XBRZ CPU Renderer using WASM (auto-initializes) */
 declare class XbrzCpuRenderer {
-    private ready;
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<XbrzCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** Check if renderer is ready */
     isReady(): boolean;
+    /** Render xBRZ scaling */
     render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
+    /** Dispose resources */
     dispose(): void;
 }
 /** XBRZ presets */
@@ -312,4 +324,4 @@ declare class RenderArt {
     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, hexGetDimensions, initWasm, isWasmLoaded, setWasmUrl };
+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, getWasmError, hasWasmError, hexGetDimensions, initWasm, isWasmLoaded };

package/dist/index.d.ts

@@ -190,56 +190,68 @@ declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
 /**
  * WASM Module Loader
  *
- * Auto-initializes WASM from URL. Works with any bundler.
+ * Handles loading and initialization of the Rust WASM module.
+ * Auto-initializes on first use.
  */
 
 /**
- * Configure WASM loading path
- * Call this before using any CPU renderer if you need a custom path.
+ * Initialize WASM module (auto-called on first use)
+ * Can be called manually to pre-load WASM.
  *
- * @param url - URL to the renderart_wasm_bg.wasm file
- *
- * @example
- * ```typescript
- * setWasmUrl('/static/wasm/renderart_wasm_bg.wasm');
- * ```
- */
-declare function setWasmUrl(url: string): void;
-/**
- * Initialize WASM module
- * Called automatically on first CPU renderer use.
- * Can be called manually for preloading.
+ * @param wasmUrl - Optional URL to the .wasm file.
  */
-declare function initWasm(customUrl?: string): Promise<void>;
+declare function initWasm(wasmUrl?: string): Promise<void>;
 /** Check if WASM is loaded */
 declare function isWasmLoaded(): boolean;
-/** CRT CPU Renderer using WASM */
+/** Check if WASM loading failed */
+declare function hasWasmError(): boolean;
+/** Get WASM loading error if any */
+declare function getWasmError(): Error | null;
+/** CRT CPU Renderer using WASM (auto-initializes) */
 declare class CrtCpuRenderer {
-    private ready;
-    /** Create and initialize renderer (auto-loads WASM) */
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<CrtCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** 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 */
+/** HEX CPU Renderer using WASM (auto-initializes) */
 declare class HexCpuRenderer {
-    private ready;
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<HexCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** 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 */
+/** XBRZ CPU Renderer using WASM (auto-initializes) */
 declare class XbrzCpuRenderer {
-    private ready;
+    private initialized;
+    /** Create and initialize renderer */
     static create(): Promise<XbrzCpuRenderer>;
+    /** Initialize (loads WASM if needed) */
+    init(): Promise<void>;
+    /** Check if renderer is ready */
     isReady(): boolean;
+    /** Render xBRZ scaling */
     render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
+    /** Dispose resources */
     dispose(): void;
 }
 /** XBRZ presets */
@@ -312,4 +324,4 @@ declare class RenderArt {
     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, hexGetDimensions, initWasm, isWasmLoaded, setWasmUrl };
+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, getWasmError, hasWasmError, hexGetDimensions, initWasm, isWasmLoaded };