A Tale of Three APIs

The luma.gl API enables the creation of portable GPU applications that can run on top of either WebGPU, or WebGL 2. luma.gl is divided into different sub-APIs: the core GPU API, the shader API and the engine API.

Engine API

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 Rendering with ANARI. It introduces the experimental, private @luma.gl/anari workspace, scene objects, committed parameters, instancing, physically based lighting, and HDR presentation.

Core API

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.

Shader API

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.

General Usage

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.