@mediamonks/fast-image-sequence
Version:
The fast-image-sequence-renderer is a powerful package for displaying image sequences at high frame rates on websites. Use it to create smooth animations, 360° product views, or video-like sequences from series of images. Zero dependencies.
199 lines (198 loc) • 7.56 kB
TypeScript
import { default as Frame } from './Frame.js';
import { default as ImageSource, ImageSourceOptions } from './ImageSource.js';
export declare function isMobile(): boolean;
export declare function clamp(value: number, min: number, max: number): number;
export type FastImageSequenceDisplayOptions = {
objectFit: 'contain' | 'cover';
horizontalAlign: number;
verticalAlign: number;
};
/**
* @typedef FastImageSequenceOptions
*
* This type represents the options for the FastImageSequence class.
*
* @property {number} frames - The number of frames in the image sequence.
* @property {ImageSourceOptions[] | ImageSourceOptions} src - The source of the images for the FastImageSequence class. It can either be an array of ImageSourceOptions or a single ImageSourceOptions instance.
* @property {boolean} [loop=false] - Whether the sequence should loop back to the start when it reaches the end.
* @property {string | undefined} [poster] - The URL of the poster image to be displayed before the sequence loads.
* @property {string} [fillStyle='#00000000'] - The fill style of the canvas. This is a color in any valid CSS color format.
* @property {boolean} [clearCanvas=false] - Whether to clear the canvas before drawing each frame.
* @property {boolean} [showDebugInfo=false] - Whether to display debug information.
* @property {string} [name='FastImageSequence'] - The name of the FastImageSequence instance.
* @property {FastImageSequenceDisplayOptions} [objectFit='cover'] - How the image should be resized to fit the canvas. It can be either 'contain' or 'cover'.
* @property {number} [horizontalAlign=0.5] - The horizontal alignment of the image. It should be a number between 0 and 1.
* @property {number} [verticalAlign=0.5] - The vertical alignment of the image. It should be a number between 0 and 1.
*/
export type FastImageSequenceOptions = {
frames: number;
src: Partial<ImageSourceOptions>[] | Partial<ImageSourceOptions>;
} & Partial<{
loop: boolean;
poster: string | undefined;
fillStyle: string;
clearCanvas: boolean;
showDebugInfo: boolean;
name: string;
scale: number;
}> & Partial<FastImageSequenceDisplayOptions>;
export declare class FastImageSequence {
private static defaultOptions;
canvas: HTMLCanvasElement;
options: Required<FastImageSequenceOptions>;
width: number;
height: number;
frame: number;
log: (...args: any[]) => void;
frames: Frame[];
sources: ImageSource[];
private context;
private tickFunctions;
private startTime;
private animationRequestId;
private container;
private resizeObserver;
private mutationObserver;
private inViewportObserver;
private forceRedraw;
private speed;
private prevFrame;
private direction;
private lastFrameDrawn;
private destructed;
private logElement;
private initialized;
private posterImage;
private timeFrameVisible;
private lastImageDrawn;
private inViewport;
private containerWidth;
private containerHeight;
/**
* Creates an instance of FastImageSequence.
*
* @param {HTMLElement} container - The HTML element where the image sequence will be displayed.
* @param {FastImageSequenceOptions} options - The options for the image sequence.
*
* @throws {Error} If the number of frames is less than or equal to 0.
*/
constructor(container: HTMLElement, options: FastImageSequenceOptions);
/**
* Get whether the image sequence is playing.
*/
get playing(): boolean;
/**
* Get whether the image sequence is paused.
*/
get paused(): boolean;
/**
* Get the current progress of the image sequence loading.
*/
get loadProgress(): number;
/**
* Get the current progress of the image sequence.
* @returns {number} - The current progress of the image sequence.
*/
get progress(): number;
/**
* Set the current progress of the image sequence.
* @param {number} value - The progress value to set.
*/
set progress(value: number);
/**
* Set the scale of the image sequence. Default is 1.
* @param value
*/
set scale(value: number);
/**
* Get the scale of the image sequence.
* @returns {number} - The scale of the image sequence.
*/
get scale(): number;
/**
* Set the horizontal alignment of the image sequence. Default is 0.5.
* @param value
*/
set horizontalAlign(value: number);
/**
* Get the horizontal alignment of the image sequence.
*/
get horizontalAlign(): number;
/**
* Set the vertical alignment of the image sequence. Default is 0.5.
* @param value
*/
set verticalAlign(value: number);
/**
* Get the vertical alignment of the image sequence.
*/
get verticalAlign(): number;
/**
* Get the first ImageSource from the sources array.
* @returns {ImageSource} - The first ImageSource object in the sources array.
*/
get src(): ImageSource;
/**
* Set number of frames in the image sequence.
*/
set frameCount(value: number);
/**
* Get number of frames in the image sequence.
*/
get frameCount(): number;
private get index();
/**
* Returns a promise that resolves when the image sequence is ready to play.
*/
ready(): Promise<void>;
/**
* Register a tick function to be called on every frame update.
*
* @param func - The function to be called.
*/
tick(func: (dt: number) => void): void;
/**
* Start playing the image sequence at a specified frame rate.
* @param {number} [fps=30] - The frame rate to play the sequence at.
*/
play(fps?: number): void;
/**
* Stop playing the image sequence.
*/
stop(): void;
/**
* Get the image of a specific frame.
* @param {number} index - The index of the frame.
* @returns {Promise<HTMLImageElement | ImageBitmap | undefined>} - A promise that resolves with the image of the frame.
*/
getFrameImage(index: number): Promise<CanvasImageSource | undefined>;
/**
* Register a callback function that is called with the progress of the loading.
* The function returns a promise that resolves when progress reaches 1.
* @param onProgress - A callback function that is called with the progress of the loading.
*/
onLoadProgress(onProgress?: (progress: number) => void): Promise<boolean>;
/**
* Destruct the FastImageSequence instance.
*/
destruct(): void;
/**
* Set the size and alignment of the image sequence on the canvas.
*
* @param {Partial<FastImageSequenceDisplayOptions>} options - An object containing the size and alignment options.
* @property {string} options.objectFit - How the image should be resized to fit the canvas. It can be either 'contain' or 'cover'.
* @property {number} options.horizontalAlign - The horizontal alignment of the image. It should be a number between 0 and 1.
* @property {number} options.verticalAlign - The vertical alignment of the image. It should be a number between 0 and 1.
*/
setDisplayOptions(options: Partial<FastImageSequenceDisplayOptions>): void;
private setTreePriority;
private setLoadingPriority;
private loadResources;
private wrapIndex;
private wrapFrame;
private drawingLoop;
private drawFrame;
private drawImage;
private process;
private logDebugStatus;
}