Skip to content

Screens and touch

The DS has two screens of 256 × 192 pixels, one above the other. Each is drawn by its own 2D graphics engine:

  • The main engine has four tile layers, 128 sprites, and one extra trick: its first layer can show the picture of the 3D engine instead of tiles.
  • The sub engine has the same four layers and 128 sprites, but no 3D.

Either engine can be sent to either screen; a single switch swaps them. So “the top screen” and “the 3D screen” are the same only because a game chose so.

Both screens refresh about 60 times a second, in step. A game changes what they show in the short pause between two pictures (the vertical blank), so a picture is never shown half old and half new.

There is one 3D engine, and its output goes into the main engine’s first layer. So in any one picture, only the screen the main engine drives can show 3D. The other screen is pure 2D: tiles and sprites.

That shapes the games:

  • The field and battles put the 3D world on the top screen. The lower screen holds a menu, a map or buttons, drawn from tiles.
  • A title screen may put a 3D logo or creature on the lower screen instead, by swapping which engine drives which screen.
  • 3D on both screens is possible only by a trick: draw one screen’s 3D, copy the finished picture into video memory (display capture), show the copy as a still image on the other screen, and alternate. Each screen then gets a new 3D picture only 30 times a second, and the copy costs video memory. Most games do not bother.

The lower screen is covered by a resistive touch panel. It reports one point: where the pen presses, as a pixel position, and whether anything presses at all. There is no multi-touch and no useful pressure reading. A finger works, less precisely.

The hardware measures the touch as voltages; the system turns them into pixel positions using a calibration stored in the console’s settings. A game reads the result as an x of 0 to 255 and a y of 0 to 191.

Because the panel is only on the lower screen, DS games put their touch menus there: large buttons, lists you can tap, a keyboard for names. Everything on the top screen is for looking at.

The top screen shows the 3D field or the battle scene, with 2D over it: text boxes, the location banner, weather particles and emotes are tile layers and sprites on the same screen. The lower screen shows the menus and touch buttons. A game picks the lower screen’s style in game.toml:

[ui.bottom]
style = "menu"

The keys are in the game.toml reference, and the lower screen’s designs on Gadgets.

Touch is never required. Every menu works with the buttons too (plan 05). Touch is a faster way to do the same thing.

The engine reads touch once a tick, as one pixel position or none, together with the buttons. That reading goes into the input log like a button, so a recorded session replays exactly, touches included.

The 3D world refreshes 30 times a second in the field, and the 2D and the logic 60. The field sends its scene every second frame and holds the last picture between, which halves the 3D work and matches the original games’ feel. Battles and menus draw at 60.

A title’s 3D on the lower screen is one flag in the frame: the engine swaps the two engines for those frames and lets the layers behind the 3D show where it draws nothing.

On desktop the same two 256 × 192 pictures are drawn by software and put in a window:

  • Stacked (the top screen above the lower) by default, or side by side, with an optional gap between them.
  • Scaled by the largest whole number that fits the window, with a border where the window’s shape differs. Whole-number scaling keeps every DS pixel square and sharp.
  • The mouse is the pen: pressing the left button over the lower screen is a touch at that pixel.

These are set on the command line (--scale, --side-by-side, --gap) or in the desktop’s config file:

scale = 3
layout = side-by-side
gap = 8

The desktop also has a second presentation profile, wide: one 320 × 180 screen for a 16:9 monitor, where the world is seen a little wider and the menus are laid out for one screen. It changes how the game is shown, never how it plays. See One wide screen on desktop.

Planned (plan 16): every menu and battle screen laid out for the wide profile.