Skip to main content

Overview

The @luma.gl/graph/gpu-simple-graph module performs GPU-based data transformation.

API Reference​

GPU Graph package​

Graph-based submodules now belong to @luma.gl/graph. Import graph subpaths from that package; GPU data primitives remain in @luma.gl/graph/gpu-data.

SubpathReference
gpu-dataGPU Data and GPUVector storage
gpu-graphGPUCommandGraph execution scheduling
gpu-coreCompute primitives, programs, and execution helpers
gpu-graph-algorithmsGraph analytics and layouts
gpu-parseEncoded columnar page decoding
gpu-physicsGPU-resident physics
gpu-vector-searchSimilarity search
gpu-timeseriesTime series and chart envelopes
gpu-geometryGeometry computations
gpu-pointcloudPoint-cloud operations
gpu-dggsDiscrete global grids
gpu-h3H3 cell projection
gpu-a5A5 cell projection

GPU Physics​

The experimental GPU physics subpath provides separate sphere and rigid-body worlds with GPU-resident state, explicit ownership and diagnostics. It requires WebGPU; see the world references for supported shapes and limits.

GPU Data Primitives​

The experimental @luma.gl/graph/gpu-data subpath provides Arrow-independent GPU storage primitives for compute and rendering. It is not re-exported from the @luma.gl/graph/gpu-simple-graph root in v9.4.

  • GPUData owns or borrows one GPU buffer and its typed row metadata.
  • GPUDataView describes a non-owning slice or child view.
  • GPUVector preserves an ordered list of GPUData chunks.
  • GPUConstant represents one fixed-width value shared across logical rows.
  • GPUVectorFormat describes stored bytes independently from shader-facing value types.
  • GPU Vector Search performs exact, bounded similarity search over borrowed fixed-size GPU rows.

Each GPUData owns or borrows exactly one buffer. A GPUVector does not own a separate raw buffer; it preserves its ordered GPUData chunks and their source batch boundaries. Packing and repacking are explicit higher-level operations, never side effects of append or streaming.

Runtime format strings describe GPU memory, including fixed-width formats such as float32x3, normalized formats such as unorm8x4, and variable-length formats such as vertex-list<float32x3>. Shader compatibility is checked at adapter and model boundaries.

@luma.gl/graph/gpu-tables adds record batches, schemas, table bindings, computations, and planners above these primitives. @luma.gl/graph/arrow converts Apache Arrow inputs to the shared GPU data objects; the GPU data types do not depend on Apache Arrow.

Installing​

npm install @luma.gl/graph

Usage​

Interleaving two buffers together

import {luma} from '@luma.gl/core';
import {webgl2Adapter} from '@luma.gl/core/webgl';
import {GPUDataEvaluator, add, interleave} from '@luma.gl/graph/gpu-simple-graph';

const inputA = GPUDataEvaluator.fromArray(new Float32Array([0, 0, 0, 1, 0, 0]), {size: 3});
const inputB = GPUDataEvaluator.fromArray(new Float32Array([10, 20]), {size: 1});
const output = interleave(inputA, inputB);

// Operations can be chained
const outputAlt = interleave(inputA, add(inputB, GPUDataEvaluator.fromConstant(1)));

// No computation is performed until the output is evaluated.
// The WebGL backend is loaded automatically on first use.

const device = await luma.createDevice({
  type: 'webgl',
  adapters: [webgl2Adapter]
});

const outputVector = await output.evaluate(device);

For synchronous call sites that cannot propagate Promises, use the sync counterparts:

  • output.evaluateSync(device)
  • cleanEvaluateSync(device, result)

Sync evaluation requires any backend modules to already be registered and any required CPU values to already be present. If a sync path would need async work, it throws immediately instead of waiting.

BackendRegistry​

The backendRegistry dispatches lazy operations to the backend module for the evaluation device. The CPU backend is available by default. If no backend has been registered for a webgl or webgpu device, @luma.gl/graph/gpu-simple-graph automatically loads the matching backend with a dynamic import, so built-in backend registration is not required.

const outputVector = await output.evaluate(device);

Backend modules are also available from dedicated endpoints. Use these imports when you want to eagerly load a backend or register a custom subset of operation handlers:

import {backendRegistry} from '@luma.gl/graph/gpu-simple-graph';
import * as webglBackend from '@luma.gl/graph/gpu-simple-graph/webgl';
import * as webgpuBackend from '@luma.gl/graph/gpu-simple-graph/webgpu';

backendRegistry.add('webgl', webglBackend);
backendRegistry.add('webgpu', webgpuBackend);

If you plan to use synchronous evaluation on a webgl or webgpu device, eager registration is recommended so backend lookup is already resolved:

import {backendRegistry, cleanEvaluateSync, interleave} from '@luma.gl/graph/gpu-simple-graph';
import * as webgpuBackend from '@luma.gl/graph/gpu-simple-graph/webgpu';

backendRegistry.add('webgpu', webgpuBackend);

const packed = interleave(inputA, inputB);
cleanEvaluateSync(device, packed);

The same endpoints export individual backend operation handlers. Applications can combine those handlers with their own custom operation handlers, or register only the handlers they need. When registering a subset, only those operations can be evaluated for that device type:

import {backendRegistry} from '@luma.gl/graph/gpu-simple-graph';
import {interleave, swizzle} from '@luma.gl/graph/gpu-simple-graph/webgl';
import {customOpWebGL} from './custom-operation';

backendRegistry.add('webgl', {
  // Built-in operation handlers selected from the WebGL backend.
  interleave,
  swizzle,

  // Custom operation handler. The key must match the custom operation name.
  customOp: customOpWebGL
});

See Custom Operations for a full operation and backend handler example.

The CPU backend can be imported from @luma.gl/graph/gpu-simple-graph/cpu when explicitly registering CPU handlers for another device type.

Concepts​

  • Choosing a GPU Data-Processing API compares portable GPGPU evaluators with GPUCommandGraph and lower-level compute helpers.
  • Operations documents the supported lazy compute operations such as add(), interleave(), and fround().
  • Custom Operations shows how to define lazy operations and register backend handlers.
  • GPU Evaluators documents GPUDataEvaluator for one fixed-width GPUData or borrowed strided GPUDataView, and GPUVectorEvaluator for chunk-preserving GPUVector.data[] transforms.
  • cleanEvaluate evaluates final result tables and cleans up intermediate dependencies in one step.

@luma.gl/graph executes WebGL operations through RenderKernel, without depending on engine. Import Kernel and RenderKernel from @luma.gl/graph. Shader-module conveniences Computation and ShaderInputs belong to @luma.gl/engine. The model-based BufferTransform and TextureTransform adapters belong to @luma.gl/engine.

Geometry and point clouds​

  • GPU Geometry: triangle and vertex normals plus adjacency-based mesh smoothing.
  • GPU Point Cloud: deterministic voxel sampling and bounded exact radius filtering.

Dynamic resource compatibility​

Import DynamicBuffer and DynamicTexture from @luma.gl/core/dynamic. Graph accepts these resources, but core owns their implementation. Graph preserves the dynamic resource exports with the same class identity.

Execution kernels​

Import Kernel and RenderKernel from @luma.gl/graph. Kernel executes WebGPU compute shaders; RenderKernel executes WebGL/WebGPU render shaders. Both consume already assembled source and explicit per-call bindings.

SimpleGraph composition​

GPUSimpleGraph compiles expression programs into CompiledGPUSimpleGraph. Use GPUSimpleGraphValue, GPUSimpleGraphValueOperation, and simpleGraphOperations to author expressions, or wrap existing evaluators with GPUSimpleGraphOperation. GPUSimpleGraphUploadOperation and GPUSimpleGraphCopyOperation provide explicit transfers. See the SimpleGraph reference.

GPUVectorEvaluator and getGPUVectorEvaluator preserve chunked expressions. GPUEvaluationScope supports caller-owned execution scopes. backendRegistry registers operation backends. getGPUDataEvaluatorInspection inspects evaluator dependencies and getGPUDataEvaluatorFormat returns their storage format. See the evaluator reference.