3D engine
The DS’s 3D engine is small and fixed. It has no programs of its own to run (no shaders), a hard limit on how much it can draw, and only whole-number arithmetic. Every DS 3D game looks the way it does partly because of what this engine cannot do.
Overview
Section titled “Overview”The 3D engine is two machines in a row:
- The geometry engine takes commands from the main processor: “load this matrix”, “this is the colour”, “here is a vertex”. It moves every vertex through the current matrices, lights it, throws away polygons that face away or lie off the screen, cuts the ones that cross the edge of the view, and stores what is left in a list for the frame.
- The rendering engine draws that list into the picture, line by line in step with the screen, testing depth, reading textures, mixing translucent polygons, and finally adding edges, fog and anti-aliasing.
The two run at once: while one frame’s list is being drawn, the next frame’s is being filled. The swap happens between two pictures.
Commands are 32-bit words. A display list is a prepared run of commands packed together, so a model can be sent with one fast copy instead of thousands of separate writes. This is the form models are stored in on the cartridge.
Polygon limit
Section titled “Polygon limit”The list the geometry engine fills has room for about 2,048 polygons and 6,144 vertices a frame. Polygons sent after it is full are simply not drawn. Only what survives culling and clipping counts, so a polygon behind the camera costs only the time to send it.
A polygon is a triangle or a quad (four corners, drawn as one). Strips of either share corners between neighbours and save vertices.
Two thousand polygons is a whole screen’s worth. That is why:
- The ground is flat squares, and a hill is a few slopes.
- A building is a box with a roof, a few dozen polygons, its detail painted on.
- Characters are not models but pictures on a card that faces the camera (see Flat characters and their shadows).
- The camera looks down from far away with a narrow view, so the screen holds a small patch of world (see How the field cameras work).
Fixed-point numbers
Section titled “Fixed-point numbers”The DS has no hardware for fractional numbers. The 3D engine uses fixed point: a whole number in which the lowest 12 bits count fractions of 1/4096. Matrices are 4 × 4 grids of such numbers (most commands send the 4 × 3 part). A vertex position is 16 bits with 12 of them fraction, so a model’s coordinates lie between -8 and just under 8; bigger models are scaled by their matrix. Texture coordinates have 4 bits of fraction.
There are small matrix stacks: one for the projection and a deeper one (31 levels) for positions, so a model can push its own matrix, draw, and pop back.
Textures
Section titled “Textures”A texture is a picture in video memory, 8 to 1,024 texels on a side, each side a power of two. The engine has seven texel formats:
| Format | Bits a texel | Colours | Good for |
|---|---|---|---|
| 4-colour | 2 | a palette of 4 | simple patterns |
| 16-colour | 4 | a palette of 16 | most scenery |
| 256-colour | 8 | a palette of 256 | detailed pictures |
| A3I5 | 8 | 32 colours, 8 levels of opacity | water, glass |
| A5I3 | 8 | 8 colours, 32 levels of opacity | soft-edged effects |
| 4 × 4 compressed | 2, plus a table per block | up to 4 per 4 × 4 block | large detailed pictures |
| Direct colour | 16 | any 15-bit colour | photographs, rare |
Texture palettes live in their own video memory. In the paletted formats colour 0 can be made transparent, so a leaf or a fence is a single quad with holes.
A texture can repeat, mirror or stop at its edges. There is no filtering: each pixel takes the nearest texel. That is the crisp, blocky look of DS textures up close, and the reason art for the DS is drawn texel by texel at the size it is seen.
The texel’s colour is multiplied by the vertex colour. Vertex colours therefore carry shading and tint for free: a dark corner, a sunset, a lit window.
Depth and translucency
Section titled “Depth and translucency”The engine keeps a depth buffer: for every pixel, how far the nearest thing drawn so far is. A new pixel is drawn only if it is nearer. This is why a character card behind a tree is hidden by the tree without any sorting.
A polygon has an opacity from 0 to 31. At 31 it is opaque. From 1 to 30 it is translucent: drawn after every opaque polygon, mixed with what is behind it, and it does not hide what comes later. The DS can sort translucent polygons by their height on the screen, or draw them in the order sent.
Each polygon also has a polygon ID (0 to 63). Two translucent polygons with the same ID never draw over each other, so overlapping shadows do not darken twice. IDs also decide where outlines go (see Toon, edges and fog).
Shaders
Section titled “Shaders”On a modern graphics card, a small program runs for every pixel and can compute any colour. The DS has none. Its colour rule is fixed: lighting at the corners, colours blended across the polygon, times the texel, then optional toon shading, fog and edges.
So everything that looks like an effect is made from that rule:
- Shading is baked into vertex colours or painted into textures, or comes from the four hardware lights (Lights and materials).
- Time of day is palettes multiplied by a colour, not a lighting pass.
- Shadows are translucent pictures on the ground.
- Water is a translucent texture that scrolls.
PokeLoom
Section titled “PokeLoom”Meshes are display lists. The build turns each OBJ model into a mesh file of DS geometry commands, grouped by material. On the DS those words go to the geometry engine as they are; the desktop decodes the same words. A material says which texture, its opacity (0 to 31), its polygon ID, whether both sides are drawn, and which light it takes. Models are authored as described on Art.
Formats. PokeLoom uses the 4-, 16- and 256-colour formats, A3I5 and A5I3. Pictures are 8 to 1,024 texels a side.
Translucent polygons are drawn in the order the engine sends them, after the opaque ones, so the engine decides what lies over what.
The polygon budget is checked before the game runs. ploom check stands the camera
on every cell a character can reach, builds that view as the game would, and counts what
it sends and what the geometry engine would keep:
| Check | Result |
|---|---|
| A view sends more than 1,800 polygons | a note |
| A view keeps more than 2,048 polygons | an error |
| A view lists more than 256 mesh instances | an error |
The budget is per view, not per map: what limits a frame is what one screen shows.
The field draws its 3D 30 times a second and holds the picture between, as the originals do; logic still runs 60 times. Battles draw at 60.
The camera is a perspective (or orthographic) camera with a tilt, a distance and a field of view, turned into the hardware’s matrices in fixed point. See Cameras.
Desktop
Section titled “Desktop”On desktop there is no DS, so a software renderer runs the same commands. It is written for PokeLoom from the hardware’s behaviour, with melonDS as the reference it is compared with. It copies:
- the matrix and vertex arithmetic, with the same rounding, so corners land on the same pixels;
- culling, clipping in the hardware’s order, and the fill rule that decides which pixels on a shared edge belong to which polygon;
- interpolation of colour and texture across a polygon, with the hardware’s precision;
- depth testing, nearest-texel textures, colour 0 transparency and the texel-times-colour formula;
- translucency, polygon IDs, fog, edge marking and anti-aliasing.
It does not copy the exact depth interpolation, polygons one pixel high, or wireframe polygons. All of it is integer arithmetic, so it gives the same picture on every desktop system. The 3D is compared with melonDS with a small tolerance; the 2D is compared exactly. More on Rendering.
Planned (plan 42): the 3D field at 60 pictures a second on maps whose budget allows it, and on desktop, higher resolutions and a GPU renderer as presentation settings.