@lightningjs/renderer
Version:
Lightning 3 Renderer
250 lines (249 loc) • 8.25 kB
TypeScript
import { ImageWorkerManager } from './lib/ImageWorker.js';
import type { CoreRenderer } from './renderers/CoreRenderer.js';
import { ColorTexture } from './textures/ColorTexture.js';
import { ImageTexture } from './textures/ImageTexture.js';
import { NoiseTexture } from './textures/NoiseTexture.js';
import { SubTexture } from './textures/SubTexture.js';
import { RenderTexture } from './textures/RenderTexture.js';
import { Texture } from './textures/Texture.js';
import { EventEmitter } from '../common/EventEmitter.js';
import type { Stage } from './Stage.js';
/**
* Augmentable map of texture class types
*
* @remarks
* This interface can be augmented by other modules/apps to add additional
* texture types. The ones included directly here are the ones that are
* included in the core library.
*/
export interface TextureMap {
ColorTexture: typeof ColorTexture;
ImageTexture: typeof ImageTexture;
NoiseTexture: typeof NoiseTexture;
SubTexture: typeof SubTexture;
RenderTexture: typeof RenderTexture;
}
export type ExtractProps<Type> = Type extends {
z$__type__Props: infer Props;
} ? Props : never;
/**
* Contains information about the texture manager's internal state
* for debugging purposes.
*/
export interface TextureManagerDebugInfo {
keyCacheSize: number;
}
export interface TextureManagerSettings {
numImageWorkers: number;
createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
}
export type ResizeModeOptions = {
/**
* Specifies that the image should be resized to cover the specified dimensions.
*/
type: 'cover';
/**
* The horizontal clipping position
* To clip the left, set clipX to 0. To clip the right, set clipX to 1.
* clipX 0.5 will clip a equal amount from left and right
*
* @defaultValue 0.5
*/
clipX?: number;
/**
* The vertical clipping position
* To clip the top, set clipY to 0. To clip the bottom, set clipY to 1.
* clipY 0.5 will clip a equal amount from top and bottom
*
* @defaultValue 0.5
*/
clipY?: number;
} | {
/**
* Specifies that the image should be resized to fit within the specified dimensions.
*/
type: 'contain';
};
/**
* Universal options for all texture types
*
* @remarks
* Texture Options provide a way to specify options that are relevant to the
* texture loading process (including caching) and specifically for how a
* texture is rendered within a specific Node (or set of Nodes).
*
* They are not used in determining the cache key for a texture (except if
* the `cacheKey` option is provided explicitly to oveerride the default
* cache key for the texture instance) nor are they stored/referenced within
* the texture instance itself. Instead, the options are stored/referenced
* within individual Nodes. So a single texture instance can be used in
* multiple Nodes each using a different set of options.
*/
export interface TextureOptions {
/**
* Preload the texture immediately even if it's not being rendered to the
* screen.
*
* @remarks
* This allows the texture to be used immediately without any delay when it
* is first needed for rendering. Otherwise the loading process will start
* when the texture is first rendered, which may cause a delay in that texture
* being shown properly.
*
* @defaultValue `false`
*/
preload?: boolean;
/**
* Prevent clean up of the texture when it is no longer being used.
*
* @remarks
* This is useful when you want to keep the texture in memory for later use.
* Regardless of whether the texture is being used or not, it will not be
* cleaned up.
*
* @defaultValue `false`
*/
preventCleanup?: boolean;
/**
* Flip the texture horizontally when rendering
*
* @defaultValue `false`
*/
flipX?: boolean;
/**
* Flip the texture vertically when rendering
*
* @defaultValue `false`
*/
flipY?: boolean;
/**
* You can use resizeMode to determine the clipping automatically from the width
* and height of the source texture. This can be convenient if you are unsure about
* the exact image sizes but want the image to cover a specific area.
*
* The resize modes cover and contain are supported
*/
resizeMode?: ResizeModeOptions;
}
export declare class CoreTextureManager extends EventEmitter {
/**
* Map of textures by cache key
*/
keyCache: Map<string, Texture>;
/**
* Map of cache keys by texture
*/
inverseKeyCache: WeakMap<Texture, string>;
/**
* Map of texture constructors by their type name
*/
txConstructors: Partial<TextureMap>;
private priorityQueue;
private uploadTextureQueue;
private initialized;
private stage;
private numImageWorkers;
imageWorkerManager: ImageWorkerManager | null;
hasCreateImageBitmap: boolean;
imageBitmapSupported: {
basic: boolean;
options: boolean;
full: boolean;
};
hasWorker: boolean;
/**
* Renderer that this texture manager is associated with
*
* @remarks
* This MUST be set before the texture manager is used. Otherwise errors
* will occur when using the texture manager.
*/
renderer: CoreRenderer;
/**
* The current frame time in milliseconds
*
* @remarks
* This is used to populate the `lastRenderableChangeTime` property of
* {@link Texture} instances when their renderable state changes.
*
* Set by stage via `updateFrameTime` method.
*/
frameTime: number;
constructor(stage: Stage, settings: TextureManagerSettings);
registerTextureType<Type extends keyof TextureMap>(textureType: Type, textureClass: TextureMap[Type]): void;
private initialize;
/**
* Enqueue a texture for uploading to the GPU.
*
* @param texture - The texture to upload
*/
enqueueUploadTexture(texture: Texture): void;
/**
* Create a texture
*
* @param textureType - The type of texture to create
* @param props - The properties to use for the texture
*/
createTexture<Type extends keyof TextureMap>(textureType: Type, props: ExtractProps<TextureMap[Type]>): InstanceType<TextureMap[Type]>;
orphanTexture(texture: Texture): void;
/**
* Override loadTexture to use the batched approach.
*
* @param texture - The texture to load
* @param immediate - Whether to prioritize the texture for immediate loading
*/
loadTexture(texture: Texture, priority?: boolean): void;
/**
* Upload a texture to the GPU
*
* @param texture Texture to upload
* @returns Promise that resolves when the texture is fully loaded
*/
uploadTexture(texture: Texture): Promise<void>;
/**
* Check if a texture is being processed
*/
isProcessingTexture(texture: Texture): boolean;
/**
* Process a limited number of uploads.
*
* @param maxProcessingTime - The maximum processing time in milliseconds
*/
processSome(maxProcessingTime: number): Promise<void>;
hasUpdates(): boolean;
/**
* Initialize a texture to the cache
*
* @param texture Texture to cache
* @param cacheKey Cache key for the texture
*/
initTextureToCache(texture: Texture, cacheKey: string): void;
/**
* Get a texture from the cache
*
* @param cacheKey
*/
getTextureFromCache(cacheKey: string): Texture | undefined;
/**
* Remove a texture from the cache
*
* @remarks
* Called by Texture Cleanup when a texture is freed.
*
* @param texture
*/
removeTextureFromCache(texture: Texture): void;
/**
* Remove texture from the upload queue
*
* @param texture - The texture to remove
*/
removeTextureFromQueue(texture: Texture): void;
/**
* Resolve a parent texture from the cache or fallback to the provided texture.
*
* @param texture - The provided texture to resolve.
* @returns The cached or provided texture.
*/
resolveParentTexture(texture: ImageTexture): Texture;
}