luma.gl Documentation

luma.gl applications require shader source code to run on the GPU. Depending on the target backend (WebGPU or WebGL 2), this code must be provided as WGSL or GLSL. luma.gl provides tools to assemble this source, bind inputs, and execute it through the engine APIs.

Key workflows include:

• Shader Assembly: Combining application-specific source with reusable shader code using ShaderAssembler, ShaderModule, and ShaderPlugin.
• Customizable Shaders: Using ShaderPlugin and ShaderAssembler to allow optional features to modify a base shader without duplicating code.
• Portable Shaders: Writing shaders that work across both WebGPU and WebGL 2 using Model and WGSL Support.
• Shader Passes: Running image effects or fullscreen texture stages using ShaderPass and ShaderPassRenderer.

The luma.gl tutorials are designed to teach you how to build a portable renderer incrementally. The course covers fundamental GPU concepts and the luma.gl object model.

Key features of the tutorial approach:

• Backend Portability: Lessons include live examples that can switch between WebGPU and WebGL2 whenever both backends support the feature.
• Code Sync: The code shown in the documentation is loaded directly from the runnable examples in the repository, ensuring documentation and tested code remain in sync.
• Type Safety: Tutorial application sources are typechecked by the repository's test setup.

Prerequisites:

• Complete the Getting Started guide first.
• Familiarity with TypeScript and basic GPU concepts is recommended.

The @luma.gl/shadertools package provides textual shader assembly utilities and the shader descriptors used by luma.gl engine classes.

Key Characteristics:

• It handles shader assembly and descriptor definitions.
• It does not compile shaders or call WebGL/WebGPU APIs directly.
• It is used to define reusable shader source, uniform descriptors, bindings, dependencies, and injections.

For guidance on authoring shader code, refer to the Shader-Level Programming guide.

The @luma.gl/tables module provides typed, batch-preserving GPU table primitives designed for rendering, transforms, and compute tasks. It manages the lifecycle and structure of data on the GPU, allowing for efficient attribute and storage workflows.

Key components include:

• Data Ownership: Use GPUTable to manage data ownership.
• Shader Resources: Use GPUTableShaderBindings to resolve shader declarations into owned, batch-preserving attribute and storage resources.
• Apache Arrow Integration: Use @luma.gl/arrow adapters when your source data is in Apache Arrow format to build generic GPU table objects.
• Structural Typing: The module provides types like GPUSchema, GPUField, and GPUVectorFormat to define data layouts.
• Execution Helpers: Includes TableTransform, GPUTableComputation, and GPUTableBufferPlanner for table-oriented operations.

@luma.gl/gpgpu is a general-purpose GPU computation module for luma.gl. It is designed to perform computations directly on the GPU.

Key Data Flow:

• Inputs: It consumes packed single-chunk GPUVector inputs provided by @luma.gl/tables.
• Outputs: It materializes the results of operations as GPUVector objects.

@luma.gl/tables provides GPU-resident table primitives designed for high-performance data handling in luma.gl. It defines a set of core types that allow data to reside on the GPU in a structured format without requiring Apache Arrow.

Key concepts include:

• Core Types: Defines structured data containers like GPUData, GPUVector, GPURecordBatch, GPUTable, GPUSchema, GPUField, GPUVectorFormat, VertexList, and GPUInputSchema.
• Data Ingestion: While @luma.gl/tables defines the types, adapter modules like @luma.gl/arrow are used to create these objects from external source data (e.g., Arrow buffers).
• Model Integration: Models can use the gpuInputSchema property to declare the specific GPUVector inputs they require for rendering.

luma.gl's experimental GPU primitives move away from isolated visual effects toward reusable GPU building blocks. Instead of accumulating individual shaders (like bloom or specific materials), the system exposes low-level mechanisms like parallel scans, compaction, indirect commands, and explicit resource scheduling. This approach supports complex, GPU-resident dataflows common in scientific visualization, geospatial rendering, and large-scale particle systems.

A typical GPU-resident dataflow follows this pattern:

1. GPU-resident source data
2. Visibility or application predicate
3. Exclusive scan
4. Stable compaction
5. Indirect draw arguments
6. Pre-recorded render commands

Note: This feature is experimental, requires WebGPU, and is intended for luma.gl v10+.

The devtools-extensions module contains reusable development helpers designed to be upstreamed into @vis.gl/dev-tools. It provides standardized configurations and helpers for various development tasks within the repository, including linting, testing, and browser debugging.

Key supported areas include:

• Linting: Biome base configurations and root lint wrappers.
• Testing: Vitest configuration boilerplate via getVitestConfig() and Tape-style assertions via vitest-tape.
• E2E Testing: Playwright launch option helpers.
• Website Development: Routing and execution helpers for examples.
• Debugging: Support for launching or attaching to Chromium-family browsers.

luma.gl is a suite of composable npm modules. To use luma.gl, you must install @luma.gl/core and at least one backend adapter: either @luma.gl/webgl or @luma.gl/webgpu.

For high-level 3D rendering, it is recommended to use @luma.gl/engine, which provides the Model class and other engine-style utilities that work independently of the chosen backend.