Model

The Model class is the centerpiece of the luma.gl API. It brings together all GPU functionality needed to run shaders and perform draw calls, in a single, easy-to-use interface.

Model manages the following responsibilities:

• Render pipeline creation and reuse - builds GPU pipelines and recreates them when render state changes.
• Attributes - manages vertex attributes and can create buffers from typed arrays.
• Bindings - handles textures, samplers and uniform buffers.
• Uniforms - supports typed uniform buffers.
• Async texture handling - accepts DynamicTexture bindings and defers rendering until textures have loaded.
• Shader module injection - assembles GLSL or WGSL shaders from modules.
• Debugging - detailed draw call logging and optional shader source display.

The Model class integrates:

• The @luma.gl/shadertools shader module system: see Shader Assembly.
• ShaderInputs for uniform and binding management.
• The geometry helpers - accepts a Geometry instance (or mesh) plus any additional attributes for instanced rendering.

Usage

import {Model} from `@luma.gl/engine`;

One of the simplest way to provide attribute data is by using a Geometry object.

Create model object by passing shaders, uniforms, geometry and render it by passing updated uniforms.

import {Model, CubeGeometry} from `@luma.gl/engine`;

const model = new Model(device, {
  source: WGSL_SHADER,
  vs: GLSL_VERTEX_SHADER,
  fs: GLSL_FRAGMENT_SHADER,
  geometry: new CubeGeometry(),
  bindings: {
    uSampler: texture
  },
})

Provide attribute data using Buffer

When using Buffer objects, data remains on GPU and same Buffer object can be shared between multiple models.

// construct the model.
const model = new Model(device, {
  vs: VERTEX_SHADER,
  fs: FRAGMENT_SHADER,
  topology: 'triangle-list',
  vertexCount: 3,
  attributes: {
    attributeName1: bufferObject,
    attributeName2: device.createBuffer(new Float32Array(...))
  },
  bindings: {uSampler: texture},
})

On each frame, update any uniform buffers or bindings and issue a draw call:

model.setBindings({uSampler: texture});
model.draw(renderPass);

Debug shader source (even when shader successful)

// construct the model.
const model = new Model(device, {
  vs: VERTEX_SHADER,
  fs: FRAGMENT_SHADER,
  debugShaders: 'always'
});

Instanced rendering

model.setInstanceCount(numInstances);
model.draw(renderPass);

Async textures

const texture = new AsyncTexture(device, {url});
const model = new Model(device, {
  vs: VERTEX_SHADER,
  fs: FRAGMENT_SHADER,
  geometry: new CubeGeometry(),
  bindings: {uSampler: texture}
});

Types

ModelProps

Property	Type	Description
source	string	WGSL source code containing both vertex and fragment stages.
vs?	string	GLSL vertex shader source.
fs?	string	GLSL fragment shader source.
modules	ShaderModule[]	Shader modules to apply.
defines	Record<string, boolean>	Module defines passed to shader assembler.
shaderInputs?	ShaderInputs	Pre-created uniform/binding store.
bindings?	Record<string, Binding, AsyncTexture>	Textures, samplers and uniform buffers.
parameters?	RenderPipelineParameters	Pipeline parameters baked into the pipeline.
geometry?	Geometry	Geometry or mesh providing attributes and indices.
isInstanced?	boolean	Use instanced rendering (auto-detected).
instanceCount?	number	Number of instances to render.
vertexCount?	number	Number of vertices to render.
indexBuffer?	Buffer	Index buffer for indexed rendering.
attributes?	Record<string, Buffer>	Buffer-valued attributes.
constantAttributes?	Record<string, TypedArray>	Constant attributes (WebGL only).
disableWarnings?	boolean	Suppress warnings for unused attributes or bindings.
varyings?	string[]	WebGL transform feedback varyings.
transformFeedback?	TransformFeedback	WebGL transform feedback object.
debugShaders?	'never' | 'errors' | 'warnings' | 'always'	Display shader sources for debugging.
pipelineFactory?	PipelineFactory	Factory used to create RenderPipeline instances.
shaderFactory?	ShaderFactory	Factory used to create Shader instances.
shaderAssembler?	ShaderAssembler	Assembles GLSL or WGSL from modules.

ModelProps also include RenderPipelineProps such as id, shaderLayout, bufferLayout, topology and userData.

Properties

id: string

Model identifier.

device: Device

Device that created this model.

parameters: RenderPipelineParameters

Pipeline parameters such as blending and depth testing.

topology: PrimitiveTopology

Primitive topology used when drawing.

bufferLayout: BufferLayout[]

Vertex buffer layout.

isInstanced: boolean | undefined

Whether instanced rendering is enabled.

instanceCount: number

Number of instances to draw.

vertexCount: number

Number of vertices to draw.

indexBuffer: Buffer | null

Index buffer used for indexed drawing.

bindings: Record<string, Binding | AsyncTexture>

Currently bound textures, samplers and uniform buffers.

vertexArray: VertexArray

Vertex array object tracking attribute bindings.

transformFeedback: TransformFeedback | null

Transform feedback object (WebGL2 only).

pipeline: RenderPipeline

Underlying GPU pipeline.

pipelineFactory: PipelineFactory

Factory used to create pipelines.

shaderFactory: ShaderFactory

Factory used to create shaders.

userData: Record<string, any>

Application-specific data.

Methods

constructor(device: Device, props: ModelProps)

Create a new Model.

destroy(): void

Release GPU resources associated with the model.

needsRedraw(): false | string

Returns the reason string if the model has requested a redraw, or false if no redraw is needed. Calling this method clears the flag.

setNeedsRedraw(reason: string): void

Mark the model as needing to be redrawn. The optional reason string is remembered until needsRedraw() is called.

predraw(): void

Update uniform buffers and pipeline state prior to drawing.

draw(renderPass: RenderPass): boolean

Render the model once to the supplied render pass.

setGeometry(geometry: Geometry | GPUGeometry | null): void

Set the geometry for this model.

setTopology(topology: PrimitiveTopology): void

Update the primitive topology.

setBufferLayout(bufferLayout: BufferLayout[]): void

Update the buffer layout.

setParameters(parameters: RenderPipelineParameters): void

Change render pipeline parameters.

setInstanceCount(instanceCount: number): void

Specify how many instances to render.

setVertexCount(vertexCount: number): void

Specify how many vertices to render.

setShaderInputs(shaderInputs: ShaderInputs): void

Set the ShaderInputs instance.

updateShaderInputs(): void

Update internal uniform buffers and bindings from shaderInputs.

setBindings(bindings: Record<string, Binding | AsyncTexture>): void

Set textures, samplers and uniform buffers.

setTransformFeedback(transformFeedback: TransformFeedback | null): void

Attach an optional transform feedback object.

setIndexBuffer(indexBuffer: Buffer | null): void

Specify the index buffer.

setAttributes(buffers: Record<string, Buffer>, options?): void

Set buffer-valued attributes.

setConstantAttributes(attributes: Record<string, TypedArray>, options?): void

Set constant-valued attributes (WebGL only).