@myned-ai/gsplat-flame-avatar-renderer 1.0.6 → 1.0.7

package/src/utils/RenderLoop.js

@@ -1,306 +0,0 @@
-/**
- * RenderLoop - Frame-independent animation loop with budget management
- *
- * Provides a robust requestAnimationFrame loop with:
- * - Delta time calculation for frame-independent updates
- * - Frame budget management to prevent frame drops
- * - Deferred task execution
- * - Performance monitoring
- */
-
-import { getLogger } from './Logger.js';
-
-const logger = getLogger('RenderLoop');
-
-/**
- * RenderLoop - Manages animation frame loop
- */
-export class RenderLoop {
-    /**
-     * Create a RenderLoop
-     * @param {Function} updateFn - Update function called each frame with deltaTime
-     * @param {Function} renderFn - Render function called each frame
-     * @param {object} [options] - Configuration options
-     * @param {number} [options.targetFps=60] - Target frames per second
-     * @param {number} [options.maxDeltaTime=0.1] - Maximum delta time in seconds (prevents spiral of death)
-     */
-    constructor(updateFn, renderFn, options = {}) {
-        this._update = updateFn;
-        this._render = renderFn;
-
-        this._targetFps = options.targetFps || 60;
-        this._maxDeltaTime = options.maxDeltaTime || 0.1; // 100ms max
-        this._frameBudget = 1000 / this._targetFps; // ms per frame
-
-        this._running = false;
-        this._rafId = null;
-        this._lastTime = 0;
-        this._frameCount = 0;
-        this._deferredTasks = [];
-
-        // Performance tracking
-        this._fpsHistory = [];
-        this._fpsHistorySize = 60; // Track last 60 frames
-        this._lastFpsUpdate = 0;
-        this._currentFps = 0;
-    }
-
-    /**
-     * Start the render loop
-     */
-    start() {
-        if (this._running) {
-            logger.warn('RenderLoop already running');
-            return;
-        }
-
-        this._running = true;
-        this._lastTime = performance.now();
-        this._frameCount = 0;
-        logger.info('RenderLoop started');
-
-        this._tick();
-    }
-
-    /**
-     * Stop the render loop
-     */
-    stop() {
-        if (!this._running) {
-            return;
-        }
-
-        this._running = false;
-
-        if (this._rafId !== null) {
-            cancelAnimationFrame(this._rafId);
-            this._rafId = null;
-        }
-
-        logger.info(`RenderLoop stopped after ${this._frameCount} frames`);
-    }
-
-    /**
-     * Main loop tick
-     * @private
-     */
-    _tick = () => {
-        if (!this._running) {
-            return;
-        }
-
-        const frameStart = performance.now();
-        const rawDeltaTime = (frameStart - this._lastTime) / 1000; // Convert to seconds
-
-        // Clamp delta time to prevent spiral of death
-        const deltaTime = Math.min(rawDeltaTime, this._maxDeltaTime);
-
-        this._lastTime = frameStart;
-        this._frameCount++;
-
-        try {
-            // Update logic
-            this._update(deltaTime);
-
-            // Render
-            this._render();
-
-            // Process deferred tasks if time permits
-            const frameElapsed = performance.now() - frameStart;
-            const remainingTime = this._frameBudget - frameElapsed;
-
-            if (remainingTime > 1 && this._deferredTasks.length > 0) {
-                this._processDeferredTasks(remainingTime - 1); // Leave 1ms margin
-            }
-
-            // Update FPS tracking
-            this._updateFpsTracking(performance.now() - frameStart);
-
-        } catch (error) {
-            logger.error('Error in render loop:', error);
-            // Continue loop despite error
-        }
-
-        // Schedule next frame
-        this._rafId = requestAnimationFrame(this._tick);
-    };
-
-    /**
-     * Update FPS tracking
-     * @private
-     * @param {number} frameTime - Time taken for this frame in ms
-     */
-    _updateFpsTracking(frameTime) {
-        this._fpsHistory.push(1000 / frameTime);
-
-        if (this._fpsHistory.length > this._fpsHistorySize) {
-            this._fpsHistory.shift();
-        }
-
-        // Update FPS every second
-        const now = performance.now();
-        if (now - this._lastFpsUpdate > 1000) {
-            this._currentFps = this._fpsHistory.reduce((a, b) => a + b, 0) / this._fpsHistory.length;
-            this._lastFpsUpdate = now;
-        }
-    }
-
-    /**
-     * Process deferred tasks within time budget
-     * @private
-     * @param {number} maxTime - Maximum time in ms to spend on tasks
-     */
-    _processDeferredTasks(maxTime) {
-        const startTime = performance.now();
-
-        while (this._deferredTasks.length > 0) {
-            if (performance.now() - startTime >= maxTime) {
-                break;
-            }
-
-            const task = this._deferredTasks.shift();
-
-            try {
-                task.fn();
-            } catch (error) {
-                logger.error(`Error in deferred task: ${task.label}`, error);
-            }
-        }
-    }
-
-    /**
-     * Execute task if within frame budget, otherwise defer
-     *
-     * @param {Function} task - Task function to execute
-     * @param {number} [priority=0] - Task priority (higher = more important)
-     * @param {string} [label=''] - Task label for debugging
-     */
-    executeOrDefer(task, priority = 0, label = '') {
-        const frameElapsed = performance.now() - this._lastTime;
-
-        if (frameElapsed < this._frameBudget * 0.8) {
-            // Within budget, execute now
-            task();
-        } else {
-            // Over budget, defer
-            this._deferredTasks.push({ fn: task, priority, label });
-
-            // Sort by priority (higher first)
-            this._deferredTasks.sort((a, b) => b.priority - a.priority);
-        }
-    }
-
-    /**
-     * Get current FPS
-     * @returns {number} Average FPS over recent frames
-     */
-    getFps() {
-        return Math.round(this._currentFps);
-    }
-
-    /**
-     * Get performance stats
-     * @returns {object} Performance statistics
-     */
-    getStats() {
-        return {
-            fps: this.getFps(),
-            frameCount: this._frameCount,
-            deferredTaskCount: this._deferredTasks.length,
-            running: this._running
-        };
-    }
-
-    /**
-     * Check if loop is running
-     * @returns {boolean} True if running
-     */
-    isRunning() {
-        return this._running;
-    }
-
-    /**
-     * Get frame count
-     * @returns {number} Total frames rendered
-     */
-    getFrameCount() {
-        return this._frameCount;
-    }
-
-    /**
-     * Clear all deferred tasks
-     */
-    clearDeferredTasks() {
-        this._deferredTasks.length = 0;
-        logger.debug('Cleared all deferred tasks');
-    }
-}
-
-/**
- * FrameBudgetMonitor - Monitors and alerts on frame budget violations
- */
-export class FrameBudgetMonitor {
-    /**
-     * Create a FrameBudgetMonitor
-     * @param {number} [targetFps=60] - Target FPS
-     * @param {Function} [onViolation] - Callback when budget is violated
-     */
-    constructor(targetFps = 60, onViolation = null) {
-        this._targetFps = targetFps;
-        this._frameBudget = 1000 / targetFps;
-        this._onViolation = onViolation;
-        this._violations = 0;
-        this._frameStart = 0;
-    }
-
-    /**
-     * Mark start of frame
-     */
-    startFrame() {
-        this._frameStart = performance.now();
-    }
-
-    /**
-     * Check if frame is within budget
-     * @param {string} [location] - Location identifier for debugging
-     * @returns {boolean} True if within budget
-     */
-    checkBudget(location = '') {
-        const elapsed = performance.now() - this._frameStart;
-        const withinBudget = elapsed < this._frameBudget;
-
-        if (!withinBudget) {
-            this._violations++;
-
-            if (this._onViolation) {
-                this._onViolation({
-                    location,
-                    elapsed,
-                    budget: this._frameBudget,
-                    overrun: elapsed - this._frameBudget
-                });
-            }
-
-            logger.warn(`Frame budget violation at ${location}: ${elapsed.toFixed(2)}ms / ${this._frameBudget.toFixed(2)}ms`);
-        }
-
-        return withinBudget;
-    }
-
-    /**
-     * Get violation count
-     * @returns {number} Total violations
-     */
-    getViolationCount() {
-        return this._violations;
-    }
-
-    /**
-     * Reset violation count
-     */
-    resetViolations() {
-        this._violations = 0;
-    }
-}
-
-export default RenderLoop;

package/src/utils/Util.js

@@ -1,416 +0,0 @@
-/**
- * Core utility functions for Gaussian Splat rendering
- *
- * Derived from @mkkellogg/gaussian-splats-3d (MIT License)
- * https://github.com/mkkellogg/GaussianSplats3D
- *
- * Import paths adjusted for gsplat-flame-avatar package structure.
- */
-
-import { DataUtils } from 'three';
-import { NetworkError } from '../errors/index.js';
-import { getLogger } from './Logger.js';
-
-const logger = getLogger('Util');
-
-/**
- * Custom error for aborted operations
- * @deprecated Use NetworkError instead for consistency
- */
-export class AbortedPromiseError extends Error {
-    constructor(msg) {
-        super(msg);
-        this.name = 'AbortedPromiseError';
-        this.code = 'ABORTED';
-    }
-}
-
-/**
- * Fetch with progress tracking using standard AbortController
- *
- * @param {string} path - URL to fetch
- * @param {Function} [onProgress] - Progress callback (percent, percentLabel, chunk, fileSize)
- * @param {boolean} [saveChunks=true] - Whether to save and return downloaded chunks
- * @param {object} [headers] - Optional HTTP headers
- * @returns {Promise<ArrayBuffer>} Promise that resolves with downloaded data
- * @throws {NetworkError} If fetch fails or is aborted
- */
-export const fetchWithProgress = function(path, onProgress, saveChunks = true, headers) {
-
-    const abortController = new AbortController();
-    const signal = abortController.signal;
-    let aborted = false;
-
-    let onProgressCalledAtComplete = false;
-    const localOnProgress = (percent, percentLabel, chunk, fileSize) => {
-        if (onProgress && !onProgressCalledAtComplete) {
-            try {
-                onProgress(percent, percentLabel, chunk, fileSize);
-                if (percent === 100) {
-                    onProgressCalledAtComplete = true;
-                }
-            } catch (error) {
-                // Don't let progress callback errors break the download
-                logger.error('Error in progress callback:', error);
-            }
-        }
-    };
-
-    const promise = new Promise((resolve, reject) => {
-        const fetchOptions = { signal };
-        if (headers) fetchOptions.headers = headers;
-
-        fetch(path, fetchOptions)
-        .then(async (data) => {
-            // Handle HTTP error responses
-            if (!data.ok) {
-                let errorText = '';
-                try {
-                    errorText = await data.text();
-                } catch {
-                    // Ignore if we can't read error text
-                }
-                reject(new NetworkError(
-                    `Fetch failed: ${data.statusText}${errorText ? ' - ' + errorText : ''}`,
-                    data.status
-                ));
-                return;
-            }
-
-            const reader = data.body?.getReader();
-            if (!reader) {
-                reject(new NetworkError('Response body is not readable', 0));
-                return;
-            }
-
-            let bytesDownloaded = 0;
-            const _fileSize = data.headers.get('Content-Length');
-            const fileSize = _fileSize ? parseInt(_fileSize, 10) : undefined;
-
-            const chunks = [];
-
-            while (!aborted) {
-                try {
-                    const { value: chunk, done } = await reader.read();
-                    if (done) {
-                        localOnProgress(100, '100%', chunk, fileSize);
-                        if (saveChunks) {
-                            const buffer = new Blob(chunks).arrayBuffer();
-                            resolve(buffer);
-                        } else {
-                            resolve();
-                        }
-                        break;
-                    }
-                    bytesDownloaded += chunk.length;
-                    let percent;
-                    let percentLabel;
-                    if (fileSize !== undefined) {
-                        percent = (bytesDownloaded / fileSize) * 100;
-                        percentLabel = `${percent.toFixed(2)}%`;
-                    }
-                    if (saveChunks) {
-                        chunks.push(chunk);
-                    }
-                    localOnProgress(percent, percentLabel, chunk, fileSize);
-                } catch (error) {
-                    reject(new NetworkError(
-                        `Error reading response stream: ${error.message}`,
-                        0,
-                        error
-                    ));
-                    return;
-                }
-            }
-        })
-        .catch((error) => {
-            // Don't wrap if already a NetworkError
-            if (error instanceof NetworkError) {
-                reject(error);
-            } else if (error.name === 'AbortError') {
-                reject(new NetworkError('Fetch aborted by user', 0, error));
-            } else {
-                reject(new NetworkError(
-                    `Fetch failed: ${error.message || 'Unknown error'}`,
-                    0,
-                    error
-                ));
-            }
-        });
-    });
-
-    // Attach abort functionality to the promise
-    promise.abort = (reason) => {
-        aborted = true;
-        abortController.abort(reason);
-    };
-    promise.abortController = abortController;
-
-    return promise;
-};
-
-// Clamp value between min and max
-export const clamp = function(val, min, max) {
-    return Math.max(Math.min(val, max), min);
-};
-
-// Get current time in seconds
-export const getCurrentTime = function() {
-    return performance.now() / 1000;
-};
-
-// Dispose all meshes in a scene graph
-export const disposeAllMeshes = (object3D) => {
-    if (object3D.geometry) {
-        object3D.geometry.dispose();
-        object3D.geometry = null;
-    }
-    if (object3D.material) {
-        object3D.material.dispose();
-        object3D.material = null;
-    }
-    if (object3D.children) {
-        for (let child of object3D.children) {
-            disposeAllMeshes(child);
-        }
-    }
-};
-
-// Delayed execution helper
-export const delayedExecute = (func, fast) => {
-    return new Promise((resolve) => {
-        window.setTimeout(() => {
-            resolve(func());
-        }, fast ? 1 : 50);
-    });
-};
-
-// Get spherical harmonics component count for degree
-export const getSphericalHarmonicsComponentCountForDegree = (sphericalHarmonicsDegree = 0) => {
-    switch (sphericalHarmonicsDegree) {
-        case 1:
-            return 9;
-        case 2:
-            return 24;
-    }
-    return 0;
-};
-
-// Create native promise with extracted components
-export const nativePromiseWithExtractedComponents = () => {
-    let resolver;
-    let rejecter;
-    const promise = new Promise((resolve, reject) => {
-        resolver = resolve;
-        rejecter = reject;
-    });
-    return {
-        'promise': promise,
-        'resolve': resolver,
-        'reject': rejecter
-    };
-};
-
-/**
- * Create a promise with extracted resolve/reject functions and optional abort capability
- * Uses standard Promise with attached abort method
- */
-export const abortablePromiseWithExtractedComponents = (abortHandler) => {
-    let resolver;
-    let rejecter;
-    const promise = new Promise((resolve, reject) => {
-        resolver = resolve;
-        rejecter = reject;
-    });
-    
-    // Attach abort method to promise
-    promise.abort = abortHandler || (() => {});
-    
-    return {
-        'promise': promise,
-        'resolve': resolver,
-        'reject': rejecter
-    };
-};
-
-// Semver class for version handling
-export class Semver {
-    constructor(major, minor, patch) {
-        this.major = major;
-        this.minor = minor;
-        this.patch = patch;
-    }
-
-    toString() {
-        return `${this.major}_${this.minor}_${this.patch}`;
-    }
-}
-
-// iOS detection
-export function isIOS() {
-    const ua = navigator.userAgent;
-    return ua.indexOf('iPhone') > 0 || ua.indexOf('iPad') > 0;
-}
-
-export function getIOSSemever() {
-    if (isIOS()) {
-        const extract = navigator.userAgent.match(/OS (\d+)_(\d+)_?(\d+)?/);
-        return new Semver(
-            parseInt(extract[1] || 0, 10),
-            parseInt(extract[2] || 0, 10),
-            parseInt(extract[3] || 0, 10)
-        );
-    }
-    return null;
-}
-
-// Half float conversion utilities
-export const toHalfFloat = DataUtils.toHalfFloat.bind(DataUtils);
-export const fromHalfFloat = DataUtils.fromHalfFloat.bind(DataUtils);
-
-// Default spherical harmonics compression range (imported from enums)
-import { DefaultSphericalHarmonics8BitCompressionRange } from '../enums/EngineConstants.js';
-export { DefaultSphericalHarmonics8BitCompressionRange };
-export const DefaultSphericalHarmonics8BitCompressionHalfRange = DefaultSphericalHarmonics8BitCompressionRange / 2.0;
-
-// Uncompress float based on compression level
-export const toUncompressedFloat = (f, compressionLevel, isSH = false, range8BitMin, range8BitMax) => {
-    if (compressionLevel === 0) {
-        return f;
-    } else if (compressionLevel === 1 || (compressionLevel === 2 && !isSH)) {
-        return DataUtils.fromHalfFloat(f);
-    } else if (compressionLevel === 2) {
-        return fromUint8(f, range8BitMin, range8BitMax);
-    }
-};
-
-// Convert to uint8
-export const toUint8 = (v, rangeMin, rangeMax) => {
-    v = clamp(v, rangeMin, rangeMax);
-    const range = (rangeMax - rangeMin);
-    return clamp(Math.floor((v - rangeMin) / range * 255), 0, 255);
-};
-
-// Convert from uint8
-export const fromUint8 = (v, rangeMin, rangeMax) => {
-    const range = (rangeMax - rangeMin);
-    return (v / 255 * range + rangeMin);
-};
-
-// Half float to uint8
-export const fromHalfFloatToUint8 = (v, rangeMin, rangeMax) => {
-    return toUint8(fromHalfFloat(v), rangeMin, rangeMax);
-};
-
-// Uint8 to half float
-export const fromUint8ToHalfFloat = (v, rangeMin, rangeMax) => {
-    return toHalfFloat(fromUint8(v, rangeMin, rangeMax));
-};
-
-// Read float from DataView based on compression level
-export const dataViewFloatForCompressionLevel = (dataView, floatIndex, compressionLevel, isSH = false) => {
-    if (compressionLevel === 0) {
-        return dataView.getFloat32(floatIndex * 4, true);
-    } else if (compressionLevel === 1 || (compressionLevel === 2 && !isSH)) {
-        return dataView.getUint16(floatIndex * 2, true);
-    } else {
-        return dataView.getUint8(floatIndex, true);
-    }
-};
-
-// Convert between compression levels
-export const convertBetweenCompressionLevels = function() {
-    const noop = (v) => v;
-
-    return function(val, fromLevel, toLevel, isSH = false) {
-        if (fromLevel === toLevel) return val;
-        let outputConversionFunc = noop;
-
-        if (fromLevel === 2 && isSH) {
-            if (toLevel === 1) outputConversionFunc = fromUint8ToHalfFloat;
-            else if (toLevel === 0) {
-                outputConversionFunc = fromUint8;
-            }
-        } else if (fromLevel === 2 || fromLevel === 1) {
-            if (toLevel === 0) outputConversionFunc = fromHalfFloat;
-            else if (toLevel === 2) {
-                if (!isSH) outputConversionFunc = noop;
-                else outputConversionFunc = fromHalfFloatToUint8;
-            }
-        } else if (fromLevel === 0) {
-            if (toLevel === 1) outputConversionFunc = toHalfFloat;
-            else if (toLevel === 2) {
-                if (!isSH) outputConversionFunc = toHalfFloat;
-                else outputConversionFunc = toUint8;
-            }
-        }
-
-        return outputConversionFunc(val);
-    };
-}();
-
-// Copy between buffers
-export const copyBetweenBuffers = (srcBuffer, srcOffset, destBuffer, destOffset, byteCount = 0) => {
-    const src = new Uint8Array(srcBuffer, srcOffset);
-    const dest = new Uint8Array(destBuffer, destOffset);
-    for (let i = 0; i < byteCount; i++) {
-        dest[i] = src[i];
-    }
-};
-
-// Float to half float conversion
-export const floatToHalf = function() {
-    const floatView = new Float32Array(1);
-    const int32View = new Int32Array(floatView.buffer);
-
-    return function(val) {
-        floatView[0] = val;
-        const x = int32View[0];
-
-        let bits = (x >> 16) & 0x8000;
-        let m = (x >> 12) & 0x07ff;
-        const e = (x >> 23) & 0xff;
-
-        if (e < 103) return bits;
-
-        if (e > 142) {
-            bits |= 0x7c00;
-            bits |= ((e == 255) ? 0 : 1) && (x & 0x007fffff);
-            return bits;
-        }
-
-        if (e < 113) {
-            m |= 0x0800;
-            bits |= (m >> (114 - e)) + ((m >> (113 - e)) & 1);
-            return bits;
-        }
-
-        bits |= ((e - 112) << 10) | (m >> 1);
-        bits += m & 1;
-        return bits;
-    };
-}();
-
-// Encode float as uint
-export const uintEncodedFloat = function() {
-    const floatView = new Float32Array(1);
-    const int32View = new Int32Array(floatView.buffer);
-
-    return function(f) {
-        floatView[0] = f;
-        return int32View[0];
-    };
-}();
-
-// RGBA to integer
-export const rgbaToInteger = function(r, g, b, a) {
-    return r + (g << 8) + (b << 16) + (a << 24);
-};
-
-// RGBA array to integer
-export const rgbaArrayToInteger = function(arr, offset) {
-    return arr[offset] + (arr[offset + 1] << 8) + (arr[offset + 2] << 16) + (arr[offset + 3] << 24);
-};
-
-// BASE_COMPONENT_COUNT for UncompressedSplatArray
-export const BASE_COMPONENT_COUNT = 14;