Rendering
The frame model itself (why the engine speaks DS terms, the tick and the frame) is explained in one description of a frame. This page is about the code that builds and draws it.
pl-render
Section titled “pl-render”pl-render is no_std and shared by every backend. Its types say what to show, in
the DS’s own vocabulary, and nothing about how.
| File | Holds |
|---|---|
frame.rs |
Frame: two ScreenFrames (four tile layers, up to 128 sprites, affine parameters, brightness, one blend), an optional 3D Scene, hold_scene, scene_below |
scene.rs |
Scene (camera, mesh instances, billboards, clear colour, fog, edges, anti-aliasing, hardware lights), Camera, Scene::emit |
gx.rs |
The DS geometry engine’s commands, numbered as the hardware numbers them, and GxSink |
mesh.rs |
The PFM2 mesh file, MeshBuilder, Material, Texture and TexFormat |
vram.rs |
Vram: who has which part of video memory |
light.rs |
Light through the day by palette, and HwLights |
fog.rs |
Depth fog: start, step, colour, a 32-entry density table |
anim.rs |
Animated textures: up to 16 slots an area, frames copied over a texture |
profile.rs |
Presentation profiles: Ds (two 256×192 screens) and Wide (plan 16) |
overlay.rs |
The debug overlay, “P1234 V5678”, with its own 13 tiles |
The 3D scene becomes geometry commands
Section titled “The 3D scene becomes geometry commands”Scene::emit turns a scene into the DS geometry engine’s commands and hands them to
a GxSink:
pub trait GxSink { fn cmd(&mut self, op: u8, params: &[u32]); // one command fn list(&mut self, words: &[u32]); // a packed display list}The DS backend’s sink writes the words to the geometry FIFO. The desktop’s sink is
soft3d, which runs the same commands in software. Because both platforms execute
the same command stream, the only thing that can differ is the rasterizer, and that
is what test-nds measures.
Meshes are stored in the pack as DS display lists (PFM2: per material a material
word, a length and the list). The DS sends a list unchanged; the desktop decodes the
same bytes. A material word carries the texture slot, alpha, polygon ID, two-sided,
which light it takes and which hardware lights its normals are lit by.
Budgets are checked where the scene is built: MAX_POLYS is 2,048 (the hardware’s
limit), and WARN_POLYS (1,800) logs a warning.
Textures and palettes
Section titled “Textures and palettes”Textures are the DS’s formats (TexFormat): 4, 16 and 256 colours, A3I5 and A5I3
(colour and alpha in one byte, for water and glass), each side a power of two from 8 to
1,024. One palette a texture; colour 0 may be transparent.
Light by palette. The 3D engine multiplies texture colour by vertex colour, so a
palette multiplied by a light’s colour is that light on everything drawn with it, at
no cost per frame. When the period of the day changes, pl-game multiplies the
palettes again from their own colours (light.rs). A material takes the sun, the
lamp light of windows, a constant white, or a lamp’s strength as opacity.
Hardware lights. A map lit as its original game lights it sends HwLights: the
four directional lights and the period’s material colours (diffuse, ambient,
specular, emission), sent as the hardware takes them. Materials that name lights are
lit from their normals; billboards are lit as a face turned up. See
lights and materials.
Video memory books
Section titled “Video memory books”The engine decides where everything goes. Vram hands out offsets; a backend only
copies bytes there. The division follows the DS’s banks, and the desktop keeps arrays
of the same sizes, so a layout that fits on the desktop fits on the DS.
| Use | Size | DS banks |
|---|---|---|
| Textures | 384 KB | A, B, C |
| Texture palettes | 16 KB (8,192 colours) | F |
| Top screen tiles and maps | 64 KB | E |
| Top screen sprite graphics | 16 KB | G |
| Bottom screen tiles and maps | 48 KB | H, I |
| Bottom screen sprite graphics | 128 KB | D |
Vram is bookkeeping only. Which scene owns which region (the field’s textures
survive a battle above it) is the engine’s rule; see
scenes and the world and DS memory.
Logic runs at 60 ticks a second. The overworld’s 3D picture changes 30 times a second:
the field sends its scene every second frame and sets hold_scene in between, so the
backend keeps showing the last one. 2D screens and battles draw at 60.
DS backend
Section titled “DS backend”crates/pl-nds/src/video.rs maps the frame onto the hardware almost one to one:
layer settings to the 2D engines’ registers, sprites to OAM entries, tiles, maps and
palettes into their banks, the 3D scene’s commands to the geometry FIFO. The top
screen is the main engine with 3D; the bottom is the sub engine, 2D only, except when
a frame asks for scene_below (a game’s 3D title model on the lower screen). Fog,
edge marking and anti-aliasing are the hardware’s own, set from the scene.
Desktop backend
Section titled “Desktop backend”The desktop has no GPU renderer. It draws in software (decision in plan 03):
- Identical pixels are reachable. A GPU renderer would differ by driver across three operating systems; integer code gives the same output everywhere.
- It runs headless. Golden-image tests and
test-ndsneed no window and no GPU. - It is cheap. 2,048 polygons at 256×192 is a small job for a desktop CPU.
crates/pl-desktop/src/soft3d.rs runs the geometry commands and rasterizes at the
screen’s size, imitating the DS 3D hardware. The rules are the hardware’s as the
melonDS project worked them out; the code was written for this project, and no
emulator code was copied. What it imitates:
- matrix and vertex arithmetic in 20.12 fixed point with the same truncation, so vertices land on the same pixels;
- winding, culling, clipping plane by plane in the hardware’s order, the viewport;
- edges stepped with the hardware’s precision and fill rules, so polygons that share an edge neither overlap nor leave a gap;
- perspective-correct interpolation with the hardware’s short factors;
- depth on z, nearest texels, colour 0 transparent, texture times vertex colour by the hardware’s formula;
- translucent polygons after the opaque ones, in the order sent, with the polygon-ID rule that stops a translucent ID drawing twice;
- depth fog, edge marking and anti-aliasing as melonDS draws them.
Not imitated: the exact depth interpolation, polygons one row high, wireframe, fog on the second layer, and toon or highlight shading.
crates/pl-desktop/src/video.rs is the 2D side: layers and sprites with the DS’s
priorities, flips, affine sprites, translucent sprites, master brightness and 6 bits a
colour channel, so colours widen as the DS widens them. All arithmetic is integer.
How close it is
Section titled “How close it is”cargo xtask test-nds plays the same input log on both platforms and compares the
pictures: 2D must be equal pixel for pixel; for the 3D scene at most 1 % of
pixels may differ by more than 16/255. Golden images in
crates/pl-desktop/tests/golden/ pin the desktop’s own output. See
testing.
Why soft3d stays
Section titled “Why soft3d stays”Plan 42 adds a GPU renderer, but soft3d remains the reference: every DS comparison and every golden image is drawn by it, at scale 1, untouched by presentation settings. A setting changes only pixels, never state (see presentation and state).
Planned
Section titled “Planned”- Planned (plan 42): soft3d draws at a whole-number resolution scale, still in integers so its goldens are equal on every host, and a CPU post-processing chain (bloom and the like) runs after it. Floats are allowed in that chain and nowhere in logic.
- Planned (plan 42):
crates/pl-gpu, astddesktop-only crate onwgpu. It readspl_render::Scene, not geometry commands:pl-desktop’spresenthands itframe.sceneinstead of callingemit. Meshes are the pack’sPFM2lists decoded once per area into vertex buffers; textures are decoded from the desktop’s mirror of texture memory. At itsclassicsetting it stays within 2 % of soft3d on every 3D session; above it come shadow maps, water, depth of field and a toy ray tracer. A build without thegpufeature has nowgpu, andpl-ndsnever depends on it. - Planned (plan 42): if no GPU adapter is found, the desktop falls back to soft3d at
classic.
The players’ side of these settings is in presentation settings.