Display

The WonderSwan's display functionality generally consists of:

• a 224x144 display clocked at ~75.47 Hz by default, capable of displaying:
  • up to sixteen distinct shades of gray
  • 12-bit RGB444 color^(color)
• two 32x32 background layers ("screens"), capable of displaying up to 512 (1024^(color)) distinct tiles,
• a sprite layer, capable of displaying up to 128 8x8 sprites (up to 32 per line),
• six LCD icons to the bottom or right of the display, usable as additional indicators.

Components

Tiles

The "mono" WonderSwan can display up to 512 tiles stored in a planar format, with two bits total per pixel.

The planes are interleaved with each other; that is, two consecutive bytes form a full 8x1 row of the tile:

 plane 0      plane 1
 byte N       byte N+1
7  bit  0    7  bit  0      full tile
---- ----    ---- ----
.... ...1    .222 22..       .22222.1
.... ...1    2222 22..       222222.1
.... ....    22.. ....       22......
...1 1...    22.2 2...  --\  22.33...
...1 1...    22.2 2...  --/  22.33...
.... ....    22.. ....       22......
.... ....    .... ....       ........
11.. ....    .... ....       11......

The WonderSwan Color extends this with an additional 512 tiles (available for screens only, not sprites) and support for three new modes.

• The first new mode is another two bit per pixel mode, but using color palettes instead of monochrome shades.

The latter two modes extend tiles to four bits per pixel.

• The first among them is the planar mode, which works similarly to the two bit per pixel mode:

 plane 0      plane 1      plane 2      plane 3
 byte N       byte N+1     byte N+2     byte N+3
7  bit  0    7  bit  0    7  bit  0    7  bit  0      full rows
---- ----    ---- ----    ---- ----    ---- ----
1.1. 1.1.    22.. 22..    4444 ....    .... ....  --\  7654321.
.1.1 .1.1    ..22 ..22    .... 4444    8888 8888  --/  89ABCDEF

• The second is the chunky mode, which instead stores each plane as consecutive bits, with each byte responsible for two of the eight pixels:

 pxl 1,0      pxl 2,3      pxl 5,4      pxl 7,6
 byte N       byte N+1     byte N+2     byte N+3
7  bit  0    7  bit  0    7  bit  0    7  bit  0      full rows
---- ----    ---- ----    ---- ----    ---- ----
.42. .421    .4.. .4.1    ..2. ..21    .... ...1  --\  7654321.
8..1 8...    8.21 8.2.    84.1 84..    8421 842.  --/  89ABCDEF

Colors, Shades

The "mono" WonderSwan uses eight value indices, which are converted by a global look-up table to eight of the sixteen shades the LCD can display:

      Palette            Global shade LUT
 1  ===========> 2 ==========================> 5
 ^  (0, 2, 4, 6) ^ (1, 3, 5, 7, 9, 11, 13, 15) ^
 |               |                             |
Tile pixel      Value                        Displayed shade

In "color" mode, the WonderSwan instead loads RGB444 color values from a table in the console's internal RAM:

15  bit  8  7  bit  0
 ---- ----  ---- ----
 .... rrrr  gggg bbbb
      ||||  |||| ||||
      ||||  |||| ++++- Blue (0-15)
      ||||  ++++------ Green (0-15)
      ++++------------ Red (0-15)

No further processing or look-up tables are applied.

Palettes

The WonderSwan provides sixteen different palettes. All sixteen can be used for screens only, while the latter eight can be used for screens and sprites. In addition, the background color (for areas where no opaque pixel is drawn) can be selected arbitrarily from the color palette or from the shade LUT.

In two bit per pixel modes, palettes 0 - 3 and 8 - 11 are opaque (color zero is opaque, four distinct colors are usable), while palettes 4 - 7 and 12 - 15 are translucent (color zero is transparent, three distinct colors are usable). This applies in both mono and color modes.

In four bit per pixel modes, every palette is translucent (color zero is transparent, fifteen distinct colors are usable). The first entry of each palette can be used only for the background color.

Palettes 8-15 are also referred to as sprite palettes 0-7.

Screens

The WonderSwan can display up to two distinct 32x32 screens. These consist of 1024 two-byte cells:

15  bit  8  7  bit  0
 ---- ----  ---- ----
 vhbp pppt  tttt tttt
 |||| ||||  |||| ||||
 |||| |||+--++++-++++- Tile index (0-511)
 |||+-+++------------- Palette (0-15)
 ||+------------------ Tile bank (0-1) - color only
 |+------------------- Horizontal flip
 +-------------------- Vertical flip

Sprites

The WonderSwan can display up to 128 sprites, with a limit of 32 visible sprites per line.

These are stored in a sprite table in RAM, which consists of up to 128 four-byte entries:

 (Byte 1)   (Byte 0)
15  bit  8  7  bit  0
 ---- ----  ---- ----
 vhPi pppt  tttt tttt
 |||| ||||  |||| ||||
 |||| |||+--++++-++++- Tile index (0-511) - only bank 0
 |||| +++------------- Palette (0-7) - mapped to screen palettes 8-15
 |||+----------------- Window location - 0 = inside, 1 = outside
 ||+------------------ Priority - 0 = behind Screen 2, 1 = in front of Screen 2
 |+------------------- Horizontal flip
 +-------------------- Vertical flip

 (Byte 2)
 7  bit  0
 ---- ----
 yyyy yyyy
 |||| ||||
 ++++-++++- Y coordinate

 (Byte 3)
 7  bit  0
 ---- ----
 xxxx xxxx
 |||| ||||
 ++++-++++- X coordinate

Windows

Screen 2 and the sprite layer can optionally be restricted to a specific window.

In addition, one can control if a given element is rendered inside or outside that window. For Screen 2, this is controlled globally; for sprites, this is controlled per-sprite.

Icons

Finally, the WonderSwan features six LCD segment icons which are displayed to the right^(color) or below^(mono) the main display. These are, as follows:

• Aux 3 - large circle,
• Aux 2 - medium circle,
• Aux 1 - small circle,
• Horizontal orientation,
• Vertical orientation,
• Sleep.

Interrupts

The display circuit generates two interrupts of its own:

• Display Interrupt Line Match - when Display Current Line == Display Interrupt Line, at the beginning of said line.
• Display Vertical Blank - when Display Current Line == 144, at the beginning of said line.

It also provides a timing source for the two Horizontal and Vertical Blank Timers, which provide their own respective interrupts.

I/O ports

Display Control ($00)

7  bit  0
---- ----
..ow Ws21
  || ||||
  || |||+- Enable Screen 1 layer
  || ||+-- Enable Screen 2 layer
  || |+--- Enable Sprite layer
  || +---- Enable Sprite window
  |+------ Enable Screen 2 window
  +------- Screen 2 window location:
           0 = inside, 1 = outside

Display Background Color ($01)

  (mono)             (color)
7  bit  0           7  bit  0
---- ----           ---- ----
.... .sss           pppp iiii
      |||           |||| ||||
      +++- Value    |||| ++++- Index in palette (0-15)
           (0-7)    ++++------ Color palette (0-15)

Display Current Line ($02 read)

The current line being drawn by the display.

Note that lines are sent to the display with a one-line delay. This matters for color palette or shade LUT manipulation; changing these values when current line == 1 will actually affect line 0.

Display Interrupt Line ($03)

The line to emit an interrupt on.

Sprite Table Address ($04)

7  bit  0
---- ----
..Aa aaaa
  || ||||
  |+-++++- Address (bits 9-13)
  +------- Address (bit 14) - color only

Sprite Table First ($05)

7  bit  0
---- ----
.iii iiii
 ||| ||||
 +++-++++- Index of first sprite entry to draw (0-127)

Sprite Table Count ($06)

7  bit  0
---- ----
cccc cccc
|||| ||||
++++-++++- Count of sprite entries to draw (1-128)

Screen Address ($07)

7  bit  0
---- ----
2222 1111
|||| ||||
|||| |+++- Screen 1 address (bits 11-13)
|||| +---- Screen 1 address (bit 14) - color only
|+++------ Screen 2 address (bits 11-13)
+--------- Screen 2 address (bit 14) - color only

LCD Control ($14)

7  bit  0
---- ----
.... ..Ce
       ||
       |+- LCD Enable: 0 = sleep, 1 = enabled
       +-- Contrast (WSC): 0 = low, 1 = high

LCD Icon Control ($15)

7  bit  0
---- ----
..32 1hvs
  || ||||
  || |||+- Sleep
  || ||+-- Vertical orientation
  || |+--- Horizontal orientation
  || +---- Aux 1
  |+------ Aux 2
  +------- Aux 3

Internal I/O ports

These I/O ports are said to be internal and not intended for use by commercial games.

LCD Final Line ($16)

The final line preceding line counter restart. By default, this should be set to 158.

It is said setting this register to an odd value on SwanCrystal has an adverse effect to the LCD panel, but the exact mechanism is unknown.

LCD Back Porch Line ($17, WSC only)

This port is available on the WonderSwan Color only - not the SwanCrystal!

The final line preceding the vertical back porch; by default, this should be set to 155.

The vertical back porch of the LCD is assumed to be 4 lines by some hardware, including IPS mods, as well as the official "TV Swan" capture device. Given that the first visible line is sent to the LCD on the display's line 1, this should be generally set to LCD Final Line - 3.

Conversely, it is said moving this value closer to vertical blank improves LCD visibility, but the exact mechanism is unknown.

LCD Status ($1A)

7  bit  0
---- ----
...v vv.s
   | || |
   | || +- LCD sleep: 0 = no, 1 = sleep
   | ||
   | ||    Volume segments:
   | |+--- Volume B (medium, high)
   | +---- Volume A (low, high)
   +------ Speaker

LCD Timing Configuration ($70, $71, $72, $73, $74, $75, $76, $77 SwanCrystal only)

These eight bytes are read from internal EEPROM and configure unknown aspects of the console's TFT LCD panel.

They are only writable while the Boot ROM is unlocked - locking has the side effect of making them read-only.