Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Geometry and Materials

Custom Shapes with BufferGeometry

Build your own Three.js geometry with BufferGeometry and BufferAttribute: positions, indices, normals, vertex colors and UVs, plus procedural terrain and waves.

Every built-in geometry is a BufferGeometry underneath, and you can build your own. Once you know how, you can draw terrain from a height map, a chart from data, a custom character mesh or a procedural tree. This lesson explains the attributes the GPU needs and builds a triangle, a quad, a terrain and an animated wave.

What a geometry holds

A BufferGeometry is a set of named attributes. Each attribute is a flat typed array plus the number of values per vertex (itemSize).

Attribute Item size Meaning
position 3 x, y, z of every vertex
normal 3 The direction the surface faces, used for lighting
uv 2 Texture coordinates from 0 to 1
color 3 Optional per-vertex color
index 1 Optional list of vertex numbers, three per triangle

Every three vertices make one triangle. The order matters: Three.js draws the front face when the vertices appear counter-clockwise as seen from the viewer. Wind them clockwise and the triangle is invisible from the front, unless the material uses DoubleSide.

flowchart LR
  V["Vertex positions"] --> T["Triangles (indices)"]
  T --> N["Normals computed for lighting"]
  T --> R["Rasterized by the GPU"]

Positions plus an index list define triangles. Normals and UVs ride along per vertex.

A single triangle

JavaScript
const geometry = new THREE.BufferGeometry();
const positions = new Float32Array([
   0,  1, 0,   // vertex 0
  -1, -1, 0,   // vertex 1
   1, -1, 0,   // vertex 2 (counter-clockwise)
]);
geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
geometry.computeVertexNormals();

computeVertexNormals() fills the normal attribute from the triangle layout. Without normals, lit materials look black or flat.

Indices: sharing vertices

A quad has four corners but needs two triangles, six corner references. With an index, you store the four vertices once and refer to them by number:

JavaScript
geometry.setAttribute("position", new THREE.BufferAttribute(new Float32Array([
  -1, -1, 0,  // 0
   1, -1, 0,  // 1
   1,  1, 0,  // 2
  -1,  1, 0,  // 3
]), 3));
geometry.setIndex([0, 1, 2,  0, 2, 3]);

Indexed geometry uses less memory and smooths normals across shared vertices. Non-indexed geometry duplicates vertices but allows hard edges, because each corner of a cube needs a different normal per face.

Vertex colors and UVs

Add a color attribute and set vertexColors: true on the material to paint colors per vertex; the GPU blends between them. A uv attribute maps each vertex to a point on a texture, with (0, 0) at the bottom-left of the image and (1, 1) at the top-right.

A hand-built triangle and quad

The triangle blends red, green and blue across its face with no texture at all. The quad's four UV pairs stretch the checker image over the surface.

Procedural terrain

A grid of vertices whose heights come from a function is a terrain. Start from PlaneGeometry (which already has positions, normals and UVs), then change the y of each vertex. We rotate the plane to lie flat first, so height goes along y.

Terrain from a height function

The loop reads each vertex with getX, getZ, writes the new height with setY and colors the vertex by height. After editing positions, recompute normals so the lighting matches the new surface.

Updating geometry every frame

For waves or cloth, change the positions each frame and tell Three.js to re-upload them:

JavaScript
const pos = geometry.attributes.position;
for (let i = 0; i < pos.count; i++) {
  const x = pos.getX(i), z = pos.getZ(i);
  pos.setY(i, Math.sin(x * 2 + time) * 0.3);
}
pos.needsUpdate = true;
geometry.computeVertexNormals();

needsUpdate = true marks the attribute dirty. For large meshes, uploading new data every frame from JavaScript is slow; move the animation into a vertex shader instead (see the shaders chapter) and keep the geometry static. Declare frequently-changing attributes with attribute.setUsage(THREE.DynamicDrawUsage) as a hint.

If you add vertices after the geometry has been rendered once, the old GPU buffer is too small. Create a new attribute (or a new geometry) rather than resizing an array.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many numbers does the position attribute store per vertex?

    Positions are x, y, z, so itemSize is 3. UVs have 2 values.
  2. 2. A triangle you built is invisible from the front. What is a likely cause?

    Front faces are counter-clockwise. Reverse the order of two vertices or use DoubleSide.
  3. 3. After changing vertex positions, what must you call to keep lighting correct?

    Normals are stored separately. They are not updated when positions change.
  4. 4. What does attribute.needsUpdate = true do?

    Without it, the GPU keeps using the old data.

Summary

  • A BufferGeometry is a set of typed-array attributes: position, normal, uv, color and an optional index.
  • Triangles are counter-clockwise from the front; indices let triangles share vertices.
  • Call computeVertexNormals() after changing positions and set needsUpdate after editing attributes.
  • Start from PlaneGeometry for terrain and waves; move heavy animation to shaders.

Next: Basic Materials