Overview

The @luma.gl/gpgpu module performs GPU-based data transformation.

API Reference

• Operations
• Custom Operations
• GPU Evaluators
• GPU Data
• cleanEvaluate

GPU Data Primitives

The experimental @luma.gl/gpgpu/gpu-data subpath provides Arrow-independent GPU storage primitives for compute and rendering. It is not re-exported from the @luma.gl/gpgpu 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/experimental/gpu-tables adds record batches, schemas, table bindings, computations, and planners above these primitives. @luma.gl/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/gpgpu

Usage

Interleaving two buffers together

import {luma} from '@luma.gl/core';
import {webglAdapter} from '@luma.gl/webgl';
import {GPUDataEvaluator, add, interleave} from '@luma.gl/gpgpu';

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: [webglAdapter]
});

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/gpgpu 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/gpgpu';
import * as webglBackend from '@luma.gl/gpgpu/webgl';
import * as webgpuBackend from '@luma.gl/gpgpu/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/gpgpu';
import * as webgpuBackend from '@luma.gl/gpgpu/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/gpgpu';
import {interleave, swizzle} from '@luma.gl/gpgpu/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/gpgpu/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.

Related Engine APIs

@luma.gl/gpgpu uses engine compute helpers internally, but it does not re-export them. Import BufferTransform, TextureTransform, and Computation from @luma.gl/engine when you need direct access to those lower-level classes.