Course outline

Topic 4.1Beginner ~19 min · step 1 of 7

Built-in Geometries

In one line

three.js ships ready-made shapes: box, sphere, cylinder, torus, plane, capsule and tube. Each is a grid of vertices joined into triangles, and the segment numbers you pass decide how round it looks and how many triangles it costs.

0/7 · 0%

Think of it like this

A tiler covers a round table with flat square tiles. With a few big tiles the edge looks like a polygon. With hundreds of tiny tiles it looks round, but the job takes far longer. A built-in geometry is that table, and the segment counts are the number of tiles.

Words you'll meet

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

vertex: One corner point of a shape, with an x, y and z position and often more data (normal, uv).
triangle: Three vertices joined by edges. The GPU draws everything as triangles, lines or points.
index: A list of vertex numbers, three per triangle, that says which corners each triangle joins. It lets triangles share vertices.
segments: How many pieces a built-in shape is cut into along one direction. More segments: rounder and more triangles.

Step by step

01Make the shapes and read their counts

Each shape is created with new, for example new THREE.TorusGeometry(0.5, 0.15): a ring of radius 0.5 whose tube has radius 0.15. The two lines at the bottom of the loop read geometry.attributes.position.count (vertices) and geometry.index.count / 3 (triangles).

02Put them in a row

All seven share one MeshBasicMaterial, so the scene has seven meshes, seven geometries and one material. Each mesh is moved 1.2 units to the right of the last, then tilted a little so you see more than one face.

03Count one frame

After one renderer.render(scene, camera), renderer.info.render holds that frame's numbers. The seven shapes add up to 3,422 triangles in 7 draw calls (one per mesh). The sum of the column and the number from the renderer agree: the renderer is not guessing.

04Segments move the price

The second example fixes one radius and changes only the segments. The count always equals width × (height − 1) × 2. The flat-shaded balls make each triangle visible: a 6 × 4 ball is a lump, a 32 × 16 ball is already smooth from a metre away.

Try it yourself

1
Make one ball very round
In the first example change new THREE.SphereGeometry(0.6) to new THREE.SphereGeometry(0.6, 64, 32). The solid frame now says 6430 triangles (3,422 − 960 + 3,968) and the wireframe frame 19290 lines. The turning ball is drawn in wireframe, so it becomes an almost solid orange blob: its lines are packed too close to tell apart.
2
Make the tyre cheap
Change new THREE.TorusGeometry(0.5, 0.15) to new THREE.TorusGeometry(0.5, 0.15, 6, 12). The solid frame says 2414 triangles and the wireframe frame 7242 lines. The tyre now shows its corners: a 12-sided ring with a six-sided tube.

Code & diagrams

Every built-in shape, counted New tab

Open the status bar: 7 draw calls. The first frame is drawn solid, then again as wireframe, so the console shows both counts.

idle

Console

Run the scene to see its console.

Expected console output

BoxGeometry         24 vertices    12 triangles
SphereGeometry     561 vertices   960 triangles
CylinderGeometry   196 vertices   128 triangles
TorusGeometry      637 vertices  1152 triangles
PlaneGeometry        4 vertices     2 triangles
CapsuleGeometry     90 vertices   144 triangles
TubeGeometry       585 vertices  1024 triangles
solid frame: 7 draw calls, 3422 triangles (column total 3422)
wireframe frame: 0 triangles, 10266 lines

Segments are the price: five balls New tab

The same radius five times. The fourth ball uses the defaults.

idle

Console

Run the scene to see its console.

Expected console output

6 x 4 -> 36 triangles (formula 36)
12 x 8 -> 168 triangles (formula 168)
20 x 12 -> 440 triangles (formula 440)
32 x 16 -> 960 triangles (formula 960)
64 x 32 -> 3968 triangles (formula 3968)
drawn: 5 draw calls, 5572 triangles
geometries on the GPU: 5

Break it on purpose

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

Break #1

Far too many segments

In "Segments are the price", change the last setting [64, 32] to [256, 256].

terminal

$ Run

── what you'll see ──

256 x 256 -> 130560 triangles (formula 130560)

drawn: 5 draw calls, 132164 triangles

No error, only a number. On a phone the frame rate falls long before this number looks "big".

Myth vs fact

Myth

More segments always look better.

Fact

Past the point where you cannot see the corners, extra segments add cost and no quality. A tyre 66 cm across that appears 200 pixels wide needs far fewer triangles than a sphere filling the whole screen.

Pro corner

Extra depth for experienced readers. New to this? Skip it for now and come back later.

▸
renderer.info.render.triangles counts the triangles that were submitted, including ones the GPU later throws away (behind the camera, off screen or back-facing). It measures the work you sent, not the pixels you see.
▸
Geometries are cached on the GPU the first time they are drawn. Ten meshes that share one geometry object upload it once (renderer.info.memory.geometries stays at 1). Make the geometry once and reuse it: ten new THREE.SphereGeometry() calls make ten copies.

Remember this

1
The problem this solves: the GPU only draws triangles. To show a ball, a pipe or a tyre you must turn it into triangles. Writing the corner numbers for a sphere by hand is slow and easy to get wrong, so three.js writes them for you from a few parameters (a radius, a height, a number of segments) and gives you a BufferGeometry back.
2
What a geometry holds. A vertex is one corner point. Triangles are described by an index: a list of numbers, three per triangle, each naming a vertex. A built-in geometry carries a position attribute (x, y, z for every vertex), a normal attribute (which way the surface faces, Topic 4.4) and a uv attribute (where the vertex sits on a picture, Topic 4.5). geometry.attributes.position.count is the vertex count and geometry.index.count / 3 is the triangle count.
3
Segments are the price. SphereGeometry(radius, widthSegments, heightSegments) defaults to 32 and 16 and makes width × (height − 1) × 2 triangles: 960. Doubling both numbers makes about four times as many triangles (64 × 32 gives 3,968). Boxes default to one segment per side (12 triangles); cylinders and tori have radialSegments and tubularSegments. Round shapes are only as round as their segments.
4
Odd inputs are not errors. three.js rounds segment counts down and raises tiny ones to a minimum (SphereGeometry(1, 1, 1) becomes 3 × 2 with 6 triangles; (1, 8.9, 6.9) becomes 8 × 6 with 80), but a box with 0 segments quietly fills its positions with NaN ("not a number"). Nothing throws. If a shape is missing, print its triangle count and look for NaN before you suspect the camera.

Explain it without notes

Why does the default sphere have 960 triangles but only 561 vertices?

A shape is missing from your scene and there is no error. Name three geometry-side things you would check.

Practice

Build a CylinderGeometry for a bike tube with radius 0.02 and length 0.5, with 8 sides. Print its triangle count, then predict what 16 sides gives and check.

You need a bell for the bike: a dome. Which built-in shape would you start from, and how would you cut it in half?

Done when you can

Create a box, sphere, cylinder, torus, plane, capsule and tube and read each triangle count
Predict a sphere's triangles from its two segment numbers
Read a vertex count and a triangle count from a geometry

Command Palette