Simple Mesh Layer

SimpleMeshLayer renders multiple instances of a single 3D mesh with per-instance transformations, colors, and materials. It's designed for efficient rendering of many instances of the same geometry with WebGL instancing.

Import

import { SimpleMeshLayer } from "@deck.gl/mesh-layers";
import type { SimpleMeshLayerProps } from "@deck.gl/mesh-layers";

Constructor

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

Props Interface

interface SimpleMeshLayerProps<DataT = unknown> extends LayerProps {
  // Data and mesh
  data: LayerDataSource<DataT>;
  mesh: string | Mesh | Promise<Mesh> | null;
  
  // Styling
  texture?: string | TextureSource | Promise<TextureSource>;
  textureParameters?: SamplerProps | null;
  material?: Material;
  wireframe?: boolean;
  sizeScale?: number;
  
  // 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[]>;
  
  // Advanced
  _instanced?: boolean;
}

Properties

Required Properties

data

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

mesh

• Type: string | Mesh | Promise<Mesh> | null
• Description: 3D mesh geometry to render. Can be a URL string, Geometry object, mesh attributes, or a Promise resolving to any of these

Styling Properties

texture

• Type: string | TextureSource | Promise<TextureSource> (optional)
• Description: Texture to apply to the mesh. Can be a URL string or texture object

textureParameters

• Type: SamplerProps | null (optional)
• Description: WebGL texture parameters for texture sampling behavior

material

• Type: Material (optional, default: true)
• Description: Material properties for lighting effects and surface appearance

wireframe

• Type: boolean (optional, default: false)
• Description: Whether to render the mesh in wireframe mode

sizeScale

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

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: [0, 0, 0, 255])
• Description: Accessor for instance colors as [r, g, b, a]. Mixed with vertex colors if mesh contains them. Ignored if texture is provided

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 getOrientation, getScale, and getTranslation

Advanced Properties

_instanced

• Type: boolean (optional, default: true)
• Description: Experimental property. When false, treats mesh positions as deltas of world coordinates instead of meter offsets

Methods

class SimpleMeshLayer<DataT, ExtraPropsT> {
  // Layer state
  get isLoaded(): boolean;
  getBounds(): [number[], number[]] | null;
  
  // Rendering
  getShaders(): ShaderModule;
  initializeState(): void;
  updateState(params: UpdateParameters<this>): void;
  finalizeState(context: LayerContext): void;
  draw(opts: {uniforms: any}): void;
}

Usage Examples

Basic Mesh Rendering

import { SimpleMeshLayer } from "@deck.gl/mesh-layers";
import { CubeGeometry } from "@luma.gl/engine";

const data = [
  {position: [0, 0, 0], color: [255, 0, 0, 255]},
  {position: [100, 100, 0], color: [0, 255, 0, 255]},
  {position: [-100, 50, 100], color: [0, 0, 255, 255]}
];

const layer = new SimpleMeshLayer({
  id: 'simple-mesh',
  data,
  mesh: new CubeGeometry(),
  getPosition: d => d.position,
  getColor: d => d.color,
  sizeScale: 50
});

Mesh with Transformations

import { SimpleMeshLayer } from "@deck.gl/mesh-layers";
import { COORDINATE_SYSTEM } from "@deck.gl/core";

const data = [
  {
    pos: [-122.4, 37.8, 0],
    orientation: [0, 45, 0], // yaw 45 degrees
    scale: [1, 1, 2] // stretched vertically
  }
];

const layer = new SimpleMeshLayer({
  id: 'transformed-mesh',
  data,
  mesh: '/path/to/model.obj',
  getPosition: d => d.pos,
  getOrientation: d => d.orientation,
  getScale: d => d.scale,
  coordinateSystem: COORDINATE_SYSTEM.LNGLAT_OFFSETS
});

Textured Mesh

const layer = new SimpleMeshLayer({
  id: 'textured-mesh',
  data: myData,
  mesh: myGeometry,
  texture: '/path/to/texture.jpg',
  textureParameters: {
    [GL.TEXTURE_MIN_FILTER]: GL.LINEAR_MIPMAP_LINEAR,
    [GL.TEXTURE_MAG_FILTER]: GL.LINEAR
  },
  getPosition: d => d.coordinates,
  getColor: [255, 255, 255, 255] // use original texture colors
});

Custom Material

import { Material } from "@deck.gl/core";

const layer = new SimpleMeshLayer({
  id: 'material-mesh',
  data: myData,
  mesh: myGeometry,
  material: new Material({
    ambient: 0.35,
    diffuse: 0.6,
    shininess: 32,
    specularColor: [30, 30, 30]
  }),
  getPosition: d => d.position
});

Coordinate Systems

SimpleMeshLayer supports all deck.gl coordinate systems:

• CARTESIAN: Direct 3D coordinates
• LNGLAT_OFFSETS: Longitude/latitude with meter offsets
• METER_OFFSETS: Meter offsets from coordinate origin
• DEFAULT: Viewport-dependent coordinate system

The _instanced property affects how mesh vertex positions are interpreted:

• true (default): Mesh positions are meter offsets from anchor
• false: Mesh positions are coordinate deltas (experimental)

Performance Notes

• Use instancing for rendering many copies of the same mesh
• Provide mesh as Geometry object rather than URL for better performance
• Consider texture atlasing for multiple textured meshes
• Use lower-resolution meshes for distant or small instances