@holoscript/core 1.0.0-alpha.2 → 2.0.0

package/src/traits/MaterialTrait.ts

@@ -0,0 +1,324 @@
+/**
+ * @holoscript/core Material Trait
+ *
+ * Enables advanced material and shader properties for photorealistic rendering
+ * Supports PBR (Physically Based Rendering) workflows
+ */
+
+export type MaterialType = 'pbr' | 'standard' | 'unlit' | 'transparent' | 'custom';
+export type TextureChannel = 'baseColor' | 'normalMap' | 'roughnessMap' | 'metallicMap' | 'ambientOcclusionMap' | 'emissionMap' | 'heightMap';
+
+/**
+ * Texture map configuration
+ */
+export interface TextureMap {
+  /** Texture path or URL */
+  path: string;
+  
+  /** Channel this texture maps to */
+  channel: TextureChannel;
+  
+  /** UV scale (tiling) */
+  scale?: { x: number; y: number };
+  
+  /** UV offset */
+  offset?: { x: number; y: number };
+  
+  /** Texture filtering: linear, nearest, anisotropic */
+  filter?: 'linear' | 'nearest' | 'anisotropic';
+  
+  /** Anisotropic level (1-16) */
+  anisotropy?: number;
+}
+
+/**
+ * PBR Material properties
+ */
+export interface PBRMaterial {
+  /** Base color in linear space [0-1] */
+  baseColor: { r: number; g: number; b: number; a?: number };
+  
+  /** Metallic value 0-1 */
+  metallic: number;
+  
+  /** Roughness value 0-1 */
+  roughness: number;
+  
+  /** Ambient occlusion 0-1 */
+  ambientOcclusion?: number;
+  
+  /** Emission color and intensity */
+  emission?: {
+    color: { r: number; g: number; b: number };
+    intensity: number;
+  };
+  
+  /** Normal map strength */
+  normalStrength?: number;
+  
+  /** Parallax/height map strength */
+  parallaxHeight?: number;
+  
+  /** Index of refraction for transmission */
+  ior?: number;
+  
+  /** Transmission amount for transparent materials */
+  transmission?: number;
+}
+
+/**
+ * Material configuration
+ */
+export interface MaterialConfig {
+  /** Material type */
+  type: MaterialType;
+  
+  /** Material name for reuse */
+  name?: string;
+  
+  /** PBR properties (for PBR materials) */
+  pbr?: PBRMaterial;
+  
+  /** Texture maps */
+  textures?: TextureMap[];
+  
+  /** Double-sided rendering */
+  doubleSided?: boolean;
+  
+  /** Blend mode for transparency */
+  blendMode?: 'opaque' | 'blend' | 'additive' | 'multiply';
+  
+  /** Custom shader code/reference */
+  customShader?: {
+    vertex?: string;
+    fragment?: string;
+    shaderLanguage?: 'glsl' | 'hlsl' | 'shadergraph';
+  };
+  
+  /** GPU memory optimization hints */
+  optimization?: {
+    /** Stream textures if needed */
+    streamTextures?: boolean;
+    
+    /** Compress textures */
+    compression?: 'none' | 'dxt' | 'astc' | 'basis';
+    
+    /** Instance this material */
+    instanced?: boolean;
+    
+    /** LOD bias for texture streaming */
+    lodBias?: number;
+  };
+}
+
+/**
+ * MaterialTrait - Enables photorealistic material rendering
+ */
+export class MaterialTrait {
+  private material: MaterialConfig;
+  private textureCache: Map<string, any> = new Map();
+
+  constructor(config: MaterialConfig) {
+    this.material = {
+      ...{ type: 'pbr' as const },
+      ...config,
+    };
+  }
+
+  /**
+   * Get material properties
+   */
+  public getMaterial(): MaterialConfig {
+    return { ...this.material };
+  }
+
+  /**
+   * Update material property
+   */
+  public setProperty<K extends keyof MaterialConfig>(key: K, value: MaterialConfig[K]): void {
+    this.material[key] = value;
+  }
+
+  /**
+   * Get PBR properties
+   */
+  public getPBRProperties(): PBRMaterial | undefined {
+    return this.material.pbr;
+  }
+
+  /**
+   * Update PBR material
+   */
+  public updatePBR(pbr: Partial<PBRMaterial>): void {
+    if (!this.material.pbr) {
+      this.material.pbr = {
+        baseColor: { r: 1, g: 1, b: 1 },
+        metallic: 0,
+        roughness: 0.5,
+      };
+    }
+    this.material.pbr = { ...this.material.pbr, ...pbr };
+  }
+
+  /**
+   * Add texture map
+   */
+  public addTexture(texture: TextureMap): void {
+    if (!this.material.textures) {
+      this.material.textures = [];
+    }
+    this.material.textures.push(texture);
+  }
+
+  /**
+   * Get all textures
+   */
+  public getTextures(): TextureMap[] {
+    return [...(this.material.textures || [])];
+  }
+
+  /**
+   * Clear texture cache (for memory optimization)
+   */
+  public clearTextureCache(): void {
+    this.textureCache.clear();
+  }
+
+  /**
+   * Get shader code if custom
+   */
+  public getCustomShader() {
+    return this.material.customShader;
+  }
+
+  /**
+   * Set custom shader
+   */
+  public setCustomShader(shader: MaterialConfig['customShader']): void {
+    this.material.customShader = shader;
+  }
+
+  /**
+   * Get optimization hints
+   */
+  public getOptimization(): MaterialConfig['optimization'] {
+    return this.material.optimization;
+  }
+
+  /**
+   * Enable/disable texture streaming
+   */
+  public setTextureStreaming(enabled: boolean): void {
+    if (!this.material.optimization) {
+      this.material.optimization = {};
+    }
+    this.material.optimization.streamTextures = enabled;
+  }
+
+  /**
+   * Set texture compression
+   */
+  public setCompression(compression: 'none' | 'dxt' | 'astc' | 'basis'): void {
+    if (!this.material.optimization) {
+      this.material.optimization = {};
+    }
+    this.material.optimization.compression = compression;
+  }
+
+  /**
+   * Enable material instancing for performance
+   */
+  public setInstanced(instanced: boolean): void {
+    if (!this.material.optimization) {
+      this.material.optimization = {};
+    }
+    this.material.optimization.instanced = instanced;
+  }
+
+  /**
+   * Dispose and cleanup
+   */
+  public dispose(): void {
+    this.textureCache.clear();
+  }
+}
+
+/**
+ * HoloScript+ @material trait factory
+ */
+export function createMaterialTrait(config: MaterialConfig): MaterialTrait {
+  return new MaterialTrait(config);
+}
+
+/**
+ * Preset materials for common use cases
+ */
+export const MATERIAL_PRESETS = {
+  /** Shiny metal */
+  chrome: (): MaterialConfig => ({
+    type: 'pbr',
+    pbr: {
+      baseColor: { r: 0.77, g: 0.77, b: 0.77 },
+      metallic: 1.0,
+      roughness: 0.1,
+    },
+  }),
+
+  /** Rough plastic */
+  plastic: (): MaterialConfig => ({
+    type: 'pbr',
+    pbr: {
+      baseColor: { r: 1, g: 1, b: 1 },
+      metallic: 0,
+      roughness: 0.8,
+    },
+  }),
+
+  /** Wood texture */
+  wood: (): MaterialConfig => ({
+    type: 'pbr',
+    pbr: {
+      baseColor: { r: 0.6, g: 0.4, b: 0.2 },
+      metallic: 0,
+      roughness: 0.4,
+    },
+  }),
+
+  /** Glass */
+  glass: (): MaterialConfig => ({
+    type: 'transparent',
+    blendMode: 'blend',
+    pbr: {
+      baseColor: { r: 1, g: 1, b: 1, a: 0.3 },
+      metallic: 0,
+      roughness: 0.0,
+      ior: 1.5,
+      transmission: 0.9,
+    },
+  }),
+
+  /** Emissive (glowing) */
+  emissive: (): MaterialConfig => ({
+    type: 'pbr',
+    pbr: {
+      baseColor: { r: 0, g: 1, b: 0 },
+      metallic: 0,
+      roughness: 1.0,
+      emission: {
+        color: { r: 0, g: 1, b: 0 },
+        intensity: 2.0,
+      },
+    },
+  }),
+
+  /** Skin material */
+  skin: (): MaterialConfig => ({
+    type: 'pbr',
+    pbr: {
+      baseColor: { r: 1, g: 0.8, b: 0.7 },
+      metallic: 0,
+      roughness: 0.5,
+      ambientOcclusion: 0.8,
+    },
+  }),
+};

package/src/traits/RenderingTrait.js

@@ -0,0 +1,356 @@
+/**
+ * @holoscript/core Rendering Trait
+ *
+ * Enables GPU optimization directives, level of detail management,
+ * and rendering performance tuning
+ */
+/**
+ * RenderingTrait - Manages GPU optimization and rendering performance
+ */
+export class RenderingTrait {
+    constructor(config) {
+        this.optimization = {
+            lodStrategy: 'automatic',
+            culling: {
+                mode: 'back',
+                frustum: true,
+                occlusion: true,
+            },
+            batching: {
+                static: true,
+                dynamic: true,
+                instancing: true,
+                maxInstanceCount: 1000,
+            },
+            textures: {
+                streaming: true,
+                compression: 'auto',
+                mipmaps: true,
+                maxResolution: 2048,
+            },
+            shaders: {
+                simplifiedShaders: true,
+                lodBias: 0,
+            },
+            targetGPUTier: 'high',
+            adaptiveQuality: true,
+            targetFrameRate: 60,
+            ...config,
+        };
+    }
+    /**
+     * Get rendering optimization config
+     */
+    getOptimization() {
+        return JSON.parse(JSON.stringify(this.optimization));
+    }
+    /**
+     * Update rendering configuration
+     */
+    updateOptimization(updates) {
+        this.optimization = { ...this.optimization, ...updates };
+    }
+    /**
+     * Setup LOD levels (3 levels is typical)
+     */
+    setupLODLevels(strategy = 'automatic') {
+        const levels = [
+            {
+                level: 0,
+                screenRelativeSize: 0.5,
+                polygonReduction: 1.0,
+                textureScale: 1.0,
+            },
+            {
+                level: 1,
+                screenRelativeSize: 0.25,
+                polygonReduction: 0.6,
+                disabledFeatures: ['specular'],
+                textureScale: 0.5,
+            },
+            {
+                level: 2,
+                screenRelativeSize: 0.1,
+                polygonReduction: 0.3,
+                disabledFeatures: ['specular', 'normals'],
+                textureScale: 0.25,
+            },
+        ];
+        this.optimization.lodStrategy = strategy;
+        this.optimization.lodLevels = levels;
+    }
+    /**
+     * Get LOD levels
+     */
+    getLODLevels() {
+        return [...(this.optimization.lodLevels || [])];
+    }
+    /**
+     * Configure culling
+     */
+    setCulling(config) {
+        this.optimization.culling = {
+            ...this.optimization.culling,
+            ...config,
+        };
+    }
+    /**
+     * Enable frustum culling
+     */
+    setFrustumCulling(enabled) {
+        if (!this.optimization.culling) {
+            this.optimization.culling = { mode: 'back' };
+        }
+        this.optimization.culling.frustum = enabled;
+    }
+    /**
+     * Enable occlusion culling
+     */
+    setOcclusionCulling(enabled, distance) {
+        if (!this.optimization.culling) {
+            this.optimization.culling = { mode: 'back' };
+        }
+        this.optimization.culling.occlusion = enabled;
+        if (distance) {
+            this.optimization.culling.occlusionDistance = distance;
+        }
+    }
+    /**
+     * Configure batching
+     */
+    setBatching(config) {
+        this.optimization.batching = {
+            ...this.optimization.batching,
+            ...config,
+        };
+    }
+    /**
+     * Enable GPU instancing
+     */
+    setInstancing(enabled, maxInstances) {
+        if (!this.optimization.batching) {
+            this.optimization.batching = {};
+        }
+        this.optimization.batching.instancing = enabled;
+        if (maxInstances) {
+            this.optimization.batching.maxInstanceCount = maxInstances;
+        }
+    }
+    /**
+     * Configure texture optimization
+     */
+    setTextureOptimization(config) {
+        this.optimization.textures = {
+            ...this.optimization.textures,
+            ...config,
+        };
+    }
+    /**
+     * Enable texture streaming
+     */
+    setTextureStreaming(enabled, budgetMB) {
+        if (!this.optimization.textures) {
+            this.optimization.textures = {};
+        }
+        this.optimization.textures.streaming = enabled;
+        if (budgetMB) {
+            this.optimization.textures.streamingBudget = budgetMB;
+        }
+    }
+    /**
+     * Set texture compression
+     */
+    setTextureCompression(compression) {
+        if (!this.optimization.textures) {
+            this.optimization.textures = {};
+        }
+        this.optimization.textures.compression = compression;
+    }
+    /**
+     * Set max texture resolution
+     */
+    setMaxTextureResolution(resolution) {
+        if (!this.optimization.textures) {
+            this.optimization.textures = {};
+        }
+        this.optimization.textures.maxResolution = resolution;
+    }
+    /**
+     * Configure shader optimization
+     */
+    setShaderOptimization(config) {
+        this.optimization.shaders = {
+            ...this.optimization.shaders,
+            ...config,
+        };
+    }
+    /**
+     * Set target GPU tier
+     */
+    setTargetGPUTier(tier) {
+        this.optimization.targetGPUTier = tier;
+    }
+    /**
+     * Enable adaptive quality (adjust based on frame rate)
+     */
+    setAdaptiveQuality(enabled, targetFrameRate) {
+        this.optimization.adaptiveQuality = enabled;
+        if (targetFrameRate) {
+            this.optimization.targetFrameRate = targetFrameRate;
+        }
+    }
+    /**
+     * Set fixed timestep for VR/AR
+     */
+    setFixedTimestep(timestep) {
+        this.optimization.fixedTimestep = timestep;
+    }
+    /**
+     * Get rendering preset for quality level
+     */
+    getPresetForQuality(quality) {
+        const presets = {
+            low: {
+                targetGPUTier: 'low',
+                lodStrategy: 'automatic',
+                culling: { mode: 'back', frustum: true, occlusion: false },
+                batching: { instancing: true, maxInstanceCount: 500 },
+                textures: {
+                    compression: 'astc',
+                    maxResolution: 512,
+                    streaming: true,
+                    streamingBudget: 128,
+                },
+                adaptiveQuality: true,
+                targetFrameRate: 30,
+            },
+            medium: {
+                targetGPUTier: 'medium',
+                lodStrategy: 'automatic',
+                culling: { mode: 'back', frustum: true, occlusion: true },
+                batching: { instancing: true, maxInstanceCount: 1000 },
+                textures: {
+                    compression: 'basis',
+                    maxResolution: 1024,
+                    streaming: true,
+                    streamingBudget: 256,
+                },
+                adaptiveQuality: true,
+                targetFrameRate: 60,
+            },
+            high: {
+                targetGPUTier: 'high',
+                lodStrategy: 'automatic',
+                culling: { mode: 'back', frustum: true, occlusion: true },
+                batching: { instancing: true, maxInstanceCount: 2000 },
+                textures: {
+                    compression: 'dxt',
+                    maxResolution: 2048,
+                    streaming: true,
+                    streamingBudget: 512,
+                },
+                adaptiveQuality: false,
+                targetFrameRate: 60,
+            },
+            ultra: {
+                targetGPUTier: 'ultra',
+                lodStrategy: 'manual',
+                culling: {
+                    mode: 'back',
+                    frustum: true,
+                    occlusion: true,
+                    hierarchicalZ: true,
+                },
+                batching: { instancing: true, maxInstanceCount: 5000 },
+                textures: {
+                    compression: 'none',
+                    maxResolution: 4096,
+                    virtualTexturing: true,
+                    streaming: true,
+                    streamingBudget: 1024,
+                },
+                adaptiveQuality: false,
+                targetFrameRate: 120,
+            },
+        };
+        return { ...this.optimization, ...presets[quality] };
+    }
+    /**
+     * Apply quality preset
+     */
+    applyQualityPreset(quality) {
+        const preset = this.getPresetForQuality(quality);
+        this.optimization = preset;
+    }
+    /**
+     * Estimate GPU memory usage
+     */
+    estimateGPUMemory() {
+        let textureMemory = 0;
+        let vertexBuffers = 0;
+        // Estimate texture memory based on max resolution
+        // Assuming RGBA format at 4 bytes per pixel
+        const maxRes = this.optimization.textures?.maxResolution || 2048;
+        textureMemory = (maxRes * maxRes * 4) / (1024 * 1024); // MB
+        // Estimate based on instancing
+        // Typical mesh: 10K vertices, position (12) + normal (12) + UV (8) + color (4) = 36 bytes
+        const instanceCount = this.optimization.batching?.maxInstanceCount || 1000;
+        const verticesPerMesh = 10000;
+        vertexBuffers = ((verticesPerMesh * 36 * instanceCount) / (1024 * 1024)) * 0.1; // 10% for practical estimate
+        return {
+            textureMemory: Math.round(textureMemory),
+            vertexBuffers: Math.max(1, Math.round(vertexBuffers)), // At least 1MB
+            estimatedTotal: Math.round(textureMemory + Math.max(1, vertexBuffers)),
+        };
+    }
+    /**
+     * Get rendering statistics/info
+     */
+    getInfo() {
+        const tier = this.optimization.targetGPUTier;
+        const lod = this.optimization.lodStrategy;
+        const culling = this.optimization.culling?.mode;
+        const instancing = this.optimization.batching?.instancing ? 'yes' : 'no';
+        const memory = this.estimateGPUMemory();
+        return `Rendering: tier=${tier} | LOD=${lod} | culling=${culling} | instancing=${instancing} | ` +
+            `memory=${memory.estimatedTotal}MB`;
+    }
+    /**
+     * Optimize for VR/AR (fixed timestep, fast culling)
+     */
+    optimizeForVRAR(targetFPS = 90) {
+        this.optimization.fixedTimestep = 1 / targetFPS;
+        this.optimization.targetFrameRate = targetFPS;
+        this.setOcclusionCulling(true, 50);
+        this.setInstancing(true, 5000);
+        this.setAdaptiveQuality(true, targetFPS);
+    }
+    /**
+     * Optimize for mobile (lower resources)
+     */
+    optimizeForMobile() {
+        this.applyQualityPreset('low');
+        this.setTextureCompression('astc');
+        this.setInstancing(true, 256);
+    }
+    /**
+     * Optimize for desktop (higher resources)
+     */
+    optimizeForDesktop() {
+        this.applyQualityPreset('ultra');
+        this.setTextureCompression('none');
+        this.setInstancing(true, 5000);
+    }
+    /**
+     * Dispose and cleanup
+     */
+    dispose() {
+        // Cleanup if needed
+    }
+}
+/**
+ * HoloScript+ @rendering trait factory
+ */
+export function createRenderingTrait(config) {
+    return new RenderingTrait(config);
+}