Skip to main content

BackgroundTextureModel

BackgroundTextureModel is a specialized ClipSpace that renders one texture across the screen while preserving aspect ratio.

It is useful for fullscreen background imagery, texture previews, and screen-space compositing.

Usage​

import {BackgroundTextureModel} from '@luma.gl/engine';
import {DynamicTexture} from '@luma.gl/core/dynamic';

const backgroundTexture = new DynamicTexture(device, {data: loadImageBitmap('/background.png')});

const background = new BackgroundTextureModel(device, {
  backgroundTexture
});

Types​

BackgroundTextureModelProps​

export type BackgroundTextureModelProps = ClipSpaceProps & {
  id?: string;
  backgroundTexture: Texture | DynamicTexture;
  blend?: boolean;
};

Properties​

backgroundTexture​

Resolved core texture currently used for drawing.

Methods​

constructor(device: Device, props: BackgroundTextureModelProps)​

Creates the fullscreen texture renderer. Throws if backgroundTexture is missing.

setProps(props: Partial<BackgroundTextureModelProps>): void​

Updates the background texture and recomputes aspect-ratio scale when the texture is ready.

predraw(commandEncoder: CommandEncoder): void​

Runs the normal ClipSpace predraw path, encoding any managed uniform uploads onto the supplied command encoder.

updateScale(texture: Texture): void​

Updates the internal shader uniforms that preserve aspect ratio.

Remarks​

  • BackgroundTextureModel accepts DynamicTexture directly and waits for it to resolve before updating scale.
  • When blend is enabled, the model configures blend parameters intended for compositing into transparent areas.