GPUVectorFormat

GPUVectorFormat is the canonical memory-layout string for GPUVector and GPUData.

It describes bytes in GPU memory, not the shader value written in WGSL or GLSL. Shader values are declared by ShaderLayout, for example vec4<f32>.

Types

import type {VertexFormat} from '@luma.gl/core';

export type VertexList<Format extends VertexFormat = VertexFormat> =
  `vertex-list<${Format}>`;

export type GPUVectorFormat = VertexFormat | VertexList;

Fixed-width vectors reuse core VertexFormat strings:

'float32'
'float32x2'
'float32x3'
'float32x4'
'uint32'
'unorm8x4'

Variable-length vertex-aligned vectors wrap a fixed element format:

'vertex-list<float32x3>'
'vertex-list<unorm8x4>'

vertex-list<format> means each logical row owns a variable-length sequence of per-vertex element values. The format inside the angle brackets describes one flattened element. Offset buffers, row ranges, closed-path flags, text glyph maps, and similar topology metadata are adapter-owned.

Generic list<format> is intentionally reserved for a possible future non-vertex offset-list type.

Helpers

getGPUVectorFormatInfo(format): GPUVectorFormatInfo

Decodes a fixed or vertex-list<...> format string.

const info = getGPUVectorFormatInfo('vertex-list<float32x3>');

info.elementFormat; // 'float32x3'
info.vertexList; // true
info.components; // 3
info.byteLength; // 12
info.primitiveType; // 'f32'

getGPUVectorElementFormat(format): VertexFormat

Returns the fixed element format. For fixed vectors this is the input format; for vertex lists this is the format inside vertex-list<...>.

isVertexListGPUVectorFormat(format): boolean

Returns true for vertex-list<...> formats.

isGPUVectorFormatCompatibleWithShaderType(format, shaderType): boolean

Checks whether the memory format can feed one shader attribute type.

Examples:

GPU format	Shader type	Compatible	Reason
float32x3	vec3<f32>	yes	Same component count and float primitive type.
unorm8x4	vec4<f32>	yes	Normalized bytes become floats.
uint32x2	vec2<u32>	yes	Unsigned integer primitive type matches.
sint32x2	vec2<u32>	no	Signedness mismatch.
float32x3	vec4<f32>	no	Component count mismatch.

Buffer Layouts

Fixed formats can synthesize ordinary BufferLayout entries:

const positions = new GPUVector({
  type: 'buffer',
  name: 'positions',
  buffer,
  format: 'float32x3',
  length
});

This yields a layout like:

[{name: 'positions', format: 'float32x3', byteStride: 12}]

If the source rows are padded, GPUVector.byteStride is preserved:

const positions = new GPUVector({
  type: 'buffer',
  name: 'positions',
  buffer,
  format: 'float32x3',
  length,
  byteStride: 16,
  rowByteLength: 12
});

vertex-list<...> vectors do not synthesize generic vertex-buffer layouts. Path, text, polygon, and geometry adapters must either expand them into renderable fixed vectors or bind them through an explicit storage/offset path.

Arrow Mapping

@luma.gl/arrow maps supported Arrow types into these formats:

Arrow type	GPUVector format
FixedSizeList<Float32, 3>	float32x3
FixedSizeList<Uint8, 4> as normalized color	unorm8x4
List<FixedSizeList<Float32, 3>> path coordinates	vertex-list<float32x3>
List<FixedSizeList<Uint8, 4>> vertex colors	vertex-list<unorm8x4>

Arrow data types remain adapter/readback metadata. Table core uses GPUVectorFormat.