kinetic-slider/dist/types/managers/FrameThrottler.d.ts

A WebGL-powered kinetic slider component using PIXI.js

/**
 * @file FrameThrottler.ts
 * @description Provides advanced frame timing controls to optimize rendering performance.
 * Offers various throttling strategies to consolidate updates and reduce GPU load.
 */
/**
 * Frame throttling strategies that determine how updates are scheduled.
 * @enum {string}
 */
export declare enum ThrottleStrategy {
    /**
     * Fixed frames per second - aims for consistent frame timing
     * by enforcing a fixed interval between frames.
     */
    FIXED_FPS = "fixed_fps",
    /**
     * Adaptive - adjusts timing based on device performance
     * by monitoring actual frame rates and adjusting accordingly.
     */
    ADAPTIVE = "adaptive",
    /**
     * Priority-based - only throttles lower priority updates
     * while allowing high-priority updates to bypass throttling.
     */
    PRIORITY = "priority",
    /**
     * None - no throttling applied (use with caution)
     * as it may lead to performance issues on low-end devices.
     */
    NONE = "none"
}
/**
 * Configuration options for the FrameThrottler.
 * @interface ThrottlerConfig
 */
export interface ThrottlerConfig {
    /**
     * Target frames per second (for FIXED_FPS strategy).
     * Higher values provide smoother animation but require more processing power.
     */
    targetFps?: number;
    /**
     * Minimum acceptable frames per second (for ADAPTIVE strategy).
     * The throttler will attempt to maintain at least this frame rate.
     */
    minFps?: number;
    /**
     * Maximum acceptable frames per second (for ADAPTIVE strategy).
     * The throttler will cap the frame rate at this value to save resources.
     */
    maxFps?: number;
    /**
     * Selected throttling strategy to use.
     * @see {ThrottleStrategy}
     */
    strategy?: ThrottleStrategy;
    /**
     * Enable performance monitoring and auto-adjustment.
     * When enabled, the throttler will collect metrics and adjust settings dynamically.
     */
    enableMonitoring?: boolean;
}
/**
 * Manages frame timing and throttling for optimal performance.
 * This class helps reduce GPU load by controlling when frames are processed.
 */
export declare class FrameThrottler {
    /** Active configuration */
    private config;
    /** Performance monitoring data */
    private performance;
    /** Timestamp of the last processed frame */
    private lastFrameTime;
    /**
     * Create a new FrameThrottler with the specified configuration.
     *
     * @param {ThrottlerConfig} [config] - Configuration options for the throttler
     *
     * @example
     * // Create a throttler with default settings (60fps, FIXED_FPS strategy)
     * const throttler = new FrameThrottler();
     *
     * @example
     * // Create a throttler with custom settings
     * const throttler = new FrameThrottler({
     *   targetFps: 30,
     *   strategy: ThrottleStrategy.ADAPTIVE,
     *   minFps: 15,
     *   maxFps: 60
     * });
     */
    constructor(config?: Partial<ThrottlerConfig>);
    /**
     * Calculate the frame interval in milliseconds from FPS.
     *
     * @param {number} fps - Frames per second
     * @returns {number} Interval in milliseconds between frames
     * @private
     */
    private calculateInterval;
    /**
     * Check if enough time has passed to process the next frame.
     *
     * @param {number} [priority] - Optional priority level to consider (higher values bypass more throttling)
     * @returns {boolean} True if the frame should be processed, false if it should be skipped
     *
     * @example
     * // Basic usage in animation loop
     * if (throttler.shouldProcessFrame()) {
     *   // Process frame
     *   render();
     *   throttler.frameProcessed();
     * }
     *
     * @example
     * // Usage with priority (3 is highest priority)
     * if (throttler.shouldProcessFrame(2)) {
     *   // Process high-priority frame
     *   renderImportantElements();
     *   throttler.frameProcessed();
     * }
     */
    shouldProcessFrame(priority?: number): boolean;
    /**
     * Mark the current frame as processed and update timing metrics.
     * Should be called after processing a frame that passed the shouldProcessFrame check.
     *
     * @example
     * if (throttler.shouldProcessFrame()) {
     *   // Process frame
     *   render();
     *   throttler.frameProcessed();
     * }
     */
    frameProcessed(): void;
    /**
     * Update performance metrics with the latest frame duration.
     *
     * @param {number} frameDuration - Duration of the last frame in milliseconds
     * @private
     */
    private updatePerformanceMetrics;
    /**
     * Update adaptive performance settings based on recent metrics.
     * This method adjusts the frame rate based on the device's capabilities.
     *
     * @param {number} now - Current timestamp in milliseconds
     * @private
     */
    private updateAdaptivePerformance;
    /**
     * Set a specific throttling strategy.
     *
     * @param {ThrottleStrategy} strategy - The throttling strategy to use
     *
     * @example
     * // Switch to adaptive strategy based on device capability
     * if (isLowEndDevice) {
     *   throttler.setStrategy(ThrottleStrategy.ADAPTIVE);
     * }
     */
    setStrategy(strategy: ThrottleStrategy): void;
    /**
     * Set a specific target FPS.
     *
     * @param {number} fps - Target frames per second (must be > 0)
     *
     * @example
     * // Reduce target FPS to save battery
     * if (isBatteryLow) {
     *   throttler.setTargetFps(30);
     * } else {
     *   throttler.setTargetFps(60);
     * }
     */
    setTargetFps(fps: number): void;
    /**
     * Get current performance metrics for monitoring and debugging.
     *
     * @returns {Object} Performance information including current FPS, interval, frame count, and strategy
     *
     * @example
     * // Log performance metrics
     * console.log(throttler.getPerformanceMetrics());
     * // Example output: { currentFps: 58.2, targetInterval: 16.67, frameCount: 1242, strategy: 'fixed_fps' }
     */
    getPerformanceMetrics(): {
        currentFps: number;
        targetInterval: number;
        frameCount: number;
        strategy: ThrottleStrategy;
    };
}