Scene Graph Layer

ScenegraphLayer renders complete glTF scene graphs with support for hierarchical node structures, animations, and physically-based rendering (PBR) materials. It's designed for complex 3D models that require advanced lighting and animation capabilities.

Import

import { ScenegraphLayer } from "@deck.gl/mesh-layers";
import type { ScenegraphLayerProps } from "@deck.gl/mesh-layers";

Constructor

class ScenegraphLayer<DataT = any, ExtraPropsT extends {} = {}> extends Layer<
  ExtraPropsT & Required<ScenegraphLayerProps<DataT>>
> {
  constructor(props: ScenegraphLayerProps<DataT> & ExtraPropsT);
  static readonly layerName: "ScenegraphLayer";
  static readonly defaultProps: DefaultProps<ScenegraphLayerProps>;
}

Props Interface

interface ScenegraphLayerProps<DataT = unknown> extends LayerProps {
  // Data and scene
  data: LayerDataSource<DataT>;
  scenegraph: any;
  
  // Scene management
  getScene?: (
    scenegraph: any,
    context: {device?: Device; layer: ScenegraphLayer<DataT>}
  ) => GroupNode;
  getAnimator?: (
    scenegraph: any,
    context: {device?: Device; layer: ScenegraphLayer<DataT>}
  ) => GLTFAnimator;
  loaders?: any[];
  
  // Styling
  sizeScale?: number;
  sizeMinPixels?: number;
  sizeMaxPixels?: number;
  
  // Lighting
  _lighting?: 'flat' | 'pbr';
  _imageBasedLightingEnvironment?: 
    | PBREnvironment 
    | ((context: {gl: WebGL2RenderingContext; layer: ScenegraphLayer<DataT>}) => PBREnvironment);
  
  // Animation
  _animations?: {
    [name: number | string | '*']: {
      playing?: boolean;
      startTime?: number;
      speed?: number;
    };
  } | null;
  
  // Accessors
  getPosition?: Accessor<DataT, Position>;
  getColor?: Accessor<DataT, Color>;
  getOrientation?: Accessor<DataT, Orientation>;
  getScale?: Accessor<DataT, Scale>;
  getTranslation?: Accessor<DataT, Translation>;
  getTransformMatrix?: Accessor<DataT, number[]>;
}

Properties

Required Properties

data

• Type: LayerDataSource<DataT>
• Description: Array of data objects to render instances for

scenegraph

• Type: any
• Description: URL string for a glTF model, scenegraph object loaded via a scenegraph loader, or a luma.gl GroupNode

Scene Management Properties

getScene

• Type: (scenegraph, context) => GroupNode (optional)
• Default: Extracts scene from glTF or returns scenegraph directly
• Description: Function to create a luma.gl GroupNode from the resolved scenegraph prop

getAnimator

• Type: (scenegraph, context) => GLTFAnimator (optional)
• Default: Extracts animator from scenegraph
• Description: Function to create a luma.gl GLTFAnimator from the resolved scenegraph prop

loaders

• Type: any[] (optional)
• Default: [GLTFLoader]
• Description: Array of loaders.gl loader objects to use for loading the scenegraph

Styling Properties

sizeScale

• Type: number (optional, default: 1)
• Description: Multiplier to scale each geometry instance

sizeMinPixels

• Type: number (optional, default: 0)
• Description: Minimum size in pixels for one unit of the scene

sizeMaxPixels

• Type: number (optional, default: Number.MAX_SAFE_INTEGER)
• Description: Maximum size in pixels for one unit of the scene

Lighting Properties

_lighting

• Type: 'flat' | 'pbr' (optional, default: 'flat')
• Description: Lighting mode. Use 'pbr' for physically-based rendering with realistic materials

_imageBasedLightingEnvironment

• Type: PBREnvironment | Function (optional)
• Description: Image-based lighting environment for PBR mode. Can be a PBREnvironment object or function that returns one

Animation Properties

_animations

• Type: Object | null (optional, default: null)
• Description: Animation configurations. Keys can be animation indices, names, or '*' for all animations
• Properties:
  • playing: boolean - Whether the animation is playing
  • startTime: number - Start time of the animation (default: 0)
  • speed: number - Speed multiplier of the animation (default: 1)

Accessor Properties

getPosition

• Type: Accessor<DataT, Position> (optional, default: x => x.position)
• Description: Accessor for instance anchor positions as [x, y, z]

getColor

• Type: Accessor<DataT, Color> (optional, default: [255, 255, 255, 255])
• Description: Accessor for instance colors as [r, g, b, a]

getOrientation

• Type: Accessor<DataT, Orientation> (optional, default: [0, 0, 0])
• Description: Accessor for instance orientations as [pitch, yaw, roll] in degrees

getScale

• Type: Accessor<DataT, Scale> (optional, default: [1, 1, 1])
• Description: Accessor for instance scaling factors as [x, y, z]

getTranslation

• Type: Accessor<DataT, Translation> (optional, default: [0, 0, 0])
• Description: Accessor for instance translations from anchor point as [x, y, z] in meters

getTransformMatrix

• Type: Accessor<DataT, number[]> (optional, default: [])
• Description: Accessor for 4x4 transformation matrices. When specified, overrides orientation, scale, and translation

Methods

class ScenegraphLayer<DataT, ExtraPropsT> {
  // Layer state
  get isLoaded(): boolean;
  
  // Rendering
  getShaders(): ShaderModule;
  initializeState(): void;
  updateState(params: UpdateParameters<this>): void;
  finalizeState(context: LayerContext): void;
  draw(opts: {context: any}): void;
}

Usage Examples

Basic glTF Rendering

import { ScenegraphLayer } from "@deck.gl/mesh-layers";

const data = [
  {coordinates: [-122.4, 37.8, 0], name: "San Francisco"},
  {coordinates: [-74.0, 40.7, 0], name: "New York"},
];

const layer = new ScenegraphLayer({
  id: 'gltf-models',
  data,
  scenegraph: 'https://example.com/models/building.gltf',
  getPosition: d => d.coordinates,
  sizeScale: 500
});

Animated Scene with PBR

const layer = new ScenegraphLayer({
  id: 'animated-scene',
  data: myData,
  scenegraph: '/path/to/animated-model.glb',
  getPosition: d => d.position,
  getOrientation: d => [0, d.heading, 0],
  
  // Enable PBR lighting
  _lighting: 'pbr',
  _imageBasedLightingEnvironment: myPBREnvironment,
  
  // Configure animations
  _animations: {
    '*': {playing: true, speed: 1.5}, // All animations at 1.5x speed
    'walk': {playing: true, speed: 2.0}, // Walk animation at 2x speed
    'idle': {playing: false} // Disable idle animation
  }
});

Custom Scene Processing

import { createScenegraphsFromGLTF } from "@luma.gl/gltf";

const layer = new ScenegraphLayer({
  id: 'custom-scene',
  data: myData,
  scenegraph: myGLTFData,
  
  // Custom scene extraction
  getScene: (scenegraph, {device, layer}) => {
    const gltfObjects = createScenegraphsFromGLTF(device, scenegraph, {
      modelOptions: {
        id: layer.props.id + '-model',
        bufferLayout: layer.getAttributeManager()!.getBufferLayouts(),
        ...layer.getShaders()
      }
    });
    return gltfObjects.scenes[0];
  },
  
  // Custom animator
  getAnimator: (scenegraph) => {
    return scenegraph.animator || null;
  }
});

Animation Control

// Start with stopped animations
const layer = new ScenegraphLayer({
  id: 'controlled-animation', 
  data: myData,
  scenegraph: myModel,
  _animations: {
    '*': {playing: false}
  }
});

// Later, start specific animations
layer.setProps({
  _animations: {
    'run': {playing: true, startTime: Date.now() / 1000, speed: 1.2},
    'jump': {playing: true, startTime: Date.now() / 1000 + 2.0, speed: 0.8}
  }
});

Size Constraints

const layer = new ScenegraphLayer({
  id: 'size-constrained',
  data: myData,
  scenegraph: myModel,
  sizeScale: 1000,
  sizeMinPixels: 10, // Never smaller than 10 pixels
  sizeMaxPixels: 200, // Never larger than 200 pixels
  getPosition: d => d.coordinates
});

Scene Graph Format Support

ScenegraphLayer supports various input formats:

glTF Files

• Binary glTF (.glb): Recommended for production
• JSON glTF (.gltf): With separate resource files
• Embedded glTF: With embedded resources

Luma.gl Objects

• GroupNode: Direct luma.gl scene graph objects
• ScenegraphNode: Any luma.gl scenegraph node

Loaders.gl Integration

Uses @loaders.gl/gltf for loading and processing glTF assets with automatic:

• Texture loading and GPU upload
• Buffer creation and attribute binding
• Material parsing and PBR setup
• Animation timeline extraction

Animation System

Animation Naming

• Numeric keys: 0, 1, 2 - Animation by index
• String keys: "walk", "idle" - Animation by name
• Wildcard: "*" - Affects all animations

Animation Properties

• playing: Controls playback state
• startTime: Synchronizes animation timing
• speed: Controls playback rate (1.0 = normal speed)

Animation Timeline

Animations use the deck.gl timeline system and automatically:

• Update on each frame when _animations is configured
• Trigger redraws as needed
• Interpolate between keyframes

Lighting Modes

Flat Lighting ('flat')

• Simple, uniform lighting
• Faster rendering performance
• Good for simple visualizations

PBR Lighting ('pbr')

• Physically-based rendering
• Supports metallic/roughness materials
• Requires _imageBasedLightingEnvironment for realistic results
• Higher rendering cost but photorealistic output

Performance Considerations

• Use binary glTF (.glb) files for better loading performance
• Consider model complexity vs. instance count
• PBR lighting has higher GPU requirements
• Animations require continuous redraws
• Use sizeMinPixels/sizeMaxPixels to control level-of-detail