Skip to content

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 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

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 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.

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.

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.

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-nds need 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.

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.

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 (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, a std desktop-only crate on wgpu. It reads pl_render::Scene, not geometry commands: pl-desktop’s present hands it frame.scene instead of calling emit. Meshes are the pack’s PFM2 lists decoded once per area into vertex buffers; textures are decoded from the desktop’s mirror of texture memory. At its classic setting 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 the gpu feature has no wgpu, and pl-nds never 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.