Choosing a luma.gl API layer

The luma.gl API enables portable GPU applications on WebGPU or WebGL 2. Choose the highest-level layer that expresses the work clearly, then move down only when the application needs more control.

If you need to…	Start with
Render geometry, manage redraws, animate, or pick objects	Engine
Create and control buffers, textures, passes, pipelines, and submission	Core
Compose reusable WGSL/GLSL behavior	Shadertools
Schedule several dependent WebGPU operations with indirect work or transient storage	GPU scheduling

Start with How luma.gl fits together for one small rendered application viewed through each layer and concrete guidance on when to move up or down.

Engine

The engine API provides higher-level classes like Model, AnimationLoop, BufferTransform, TextureTransform, and Computation. Its shared animation system adds keyframe tracks, clips, weighted mixing, crossfades, and portable morph-target deformation. Scenegraphs are included, while glTF loading, physical materials, skeletal animation, and morph animation live in the format-specific @luma.gl/gltf module.

The experimental SceneRenderer and DeferredSceneRenderer consume format-independent scene descriptions instead of introducing a second glTF renderer. Their physical lighting environments can be prepared from caller-owned equirectangular textures.

For an experimental retained, renderer-independent scene contract, see Declarative Scene Rendering. It introduces the experimental @luma.gl/scene package, scene objects, committed parameters, instancing, physically based lighting, and HDR presentation.

Core

The core luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications. It is a portable API, in the sense that the @luma.gl/core module provides an abstract API for writing application code that works with both WebGPU and/or WebGL depending on which adapter modules are installed (@luma.gl/webgl and/or @luma.gl/webgpu).

Core responsibilities for any GPU library are to enable applications to perform:

• GPU initialization - Open a GPU device and query its capabilities
• GPU memory management - Create, upload memory to and read from Buffers, Textures etc.
• GPU command encoding - Decide when to use immediate resource helpers versus explicit CommandEncoder recording.
• GPU resource management - Create Shader, Renderpipeline, RenderPass etc objects.
• GPU binding management - Make attribute buffers, uniforms, textures, samplers available to GPU shaders.
• Shader execution / rendering - Drawing into textures, running compute shaders.
• GPU parameter management - Configuring blending, clipping, depth tests etc.

Shadertools

The Shader API lets the application use a library of existing shader modules to create new custom shaders. It is also possible for developers to create new reusable shader modules.

Most applications work with the engine API (Model, AnimationLoop and related classes), leveraging the core GPU API as necessary to obtain a Device and use it to create GPU resources such as Buffer and Texture. The shader API is used to assemble shaders and define shader modules.

Typical application flow

Most luma.gl applications will:

1. Use the core API to create a Device class to access the GPU (either using WebGPU or WebGL).
2. Upload data to the GPU via methods on the Device, using Buffer and Texture objects.
3. Use the engine API to create one or more Model instances from GLSL or WGSL shader code.
4. Bind attribute buffers and bindings (textures, uniform buffers or uniforms).
5. Start an engine API AnimationLoop loop, and draw each frame into a RenderPass.