Geometry (BufferGeometry)

A BufferGeometry is a collection of named attributes — each attribute is a flat typed array (like Float32Array) that holds per-vertex data. The GPU reads these arrays directly from Video RAM.

Core Methods

// Set an attribute (also triggers GPU upload on next render)
geometry.setAttribute( 'position',
  new THREE.BufferAttribute( new Float32Array([...]), 3 ) // 3 = itemSize (x,y,z)
);

// Retrieve an attribute
const pos = geometry.getAttribute( 'position' );

// Set the index buffer
geometry.setIndex( new THREE.BufferAttribute(
  new Uint16Array([ 0,1,2, 1,3,2 ]), 1
));

// Mark the position attribute as needing GPU re-upload
geometry.getAttribute('position').needsUpdate = true;

// Render only vertices 10–99
geometry.drawRange.start = 10;
geometry.drawRange.count = 90;

// Free CPU + GPU memory
geometry.dispose();

A BufferAttribute wraps a typed array and tells three.js how to interpret it for the GPU.

// Triangle with 3 vertices, each having (x, y, z)
const positions = new Float32Array([
  // vertex 0      vertex 1       vertex 2
     0,  1, 0,   -1, -1, 0,    1, -1, 0
]);

const attr = new THREE.BufferAttribute(
  positions,  // the typed array
  3           // itemSize: how many values per vertex (3 = vec3)
);
// attr.count = 3 (positions.length / itemSize)
// attr.array = positions (the raw typed array)
// attr.itemSize = 3

Memory Layout

Data is interleaved or separate. Three.js uses separate arrays by default (one per attribute). The memory layout for 3 vertices looks like:

Key Properties

Without an index buffer, each triangle requires 3 unique vertices. With indexing, vertices can be shared between triangles:

For a sphere with 1000 segments, vertex sharing reduces vertex count by ~50% and enables the GPU's built-in vertex cache.

• OpenGL Wiki — Vertex Array Objects
• Khronos — Vertex Specification

Three.js uploads geometry lazily — on the first render call for a given geometry+material+object combination.

BufferAttribute Usage Hints

// Static mesh (default) — uploaded once, rarely changed
geometry.getAttribute('position').usage = THREE.StaticDrawUsage;
// → gl.bufferData(..., gl.STATIC_DRAW)

// Animated/morphing mesh — re-uploaded frequently
geometry.getAttribute('position').usage = THREE.DynamicDrawUsage;
// → gl.bufferData(..., gl.DYNAMIC_DRAW)

// Per-frame streaming (particles, etc.)
geometry.getAttribute('position').usage = THREE.StreamDrawUsage;
// → gl.bufferData(..., gl.STREAM_DRAW)

These hints tell the GPU driver how to allocate VRAM (which memory pool to use), affecting upload speed and rendering throughput.

A geometry can be split into groups, each rendered with a different material. This is used for models with separate textures on different parts (e.g. a car body and its windows).

// Define groups (ranges of the index buffer)
geometry.addGroup( 0, 36, 0 );   // indices 0-35 → material[0]
geometry.addGroup( 36, 12, 1 );  // indices 36-47 → material[1]

// Mesh with multiple materials
const mesh = new THREE.Mesh( geometry, [
  new THREE.MeshStandardMaterial({ color: 0xff0000 }),  // index 0
  new THREE.MeshStandardMaterial({ color: 0x0000ff }),  // index 1
]);

The renderer calls renderBufferDirect() once per group, with the corresponding material. Each call becomes a separate draw call on the GPU.

Three.js includes generators that produce BufferGeometry with pre-computed attributes:

// BoxGeometry — generates position, normal, uv attributes + index
const box = new THREE.BoxGeometry( 1, 1, 1 );

// SphereGeometry — sphere with lat/lon segments
const sphere = new THREE.SphereGeometry( 0.5, 32, 16 );

// PlaneGeometry — flat plane in XZ
const plane = new THREE.PlaneGeometry( 10, 10, 100, 100 );

// Custom: build your own
const geom = new THREE.BufferGeometry();
geom.setAttribute( 'position', new THREE.BufferAttribute(
  new Float32Array([ 0,1,0, -1,-1,0, 1,-1,0 ]), 3
));
// Normals are optional but required for lighting
geom.computeVertexNormals(); // auto-compute from faces

• Three.js Docs — BufferGeometry
• WebGL Fundamentals — Attributes
• Khronos — Vertex Buffer Objects