RadarPPU.txt

*** INFORMATION ***

This is a fantasy graphics chip created by The Beesh-Spweesh! for the Hexheld fantasy portable console.

This chip generates grayscale, 4-bit images at a resolution of 168x224.
Due to the hexagon shape of the physical LCD display, the corners of the image are not visible.

The image generated by the RPPU consists of the following elements:

- Backgrounds (BG)
    These are full-screen layers of tile-based graphics which may be scrolled on both axes individually.
    The RPPU provides 4 modes of displaying backgrounds:
      MODE 0: 1 layer of bitmap cutouts. Each tile has X,Y offsets into the VRAM treated as a 256x256 bitmap.
      MODE 1: 1 layer of 4BPP character graphics. This layer uses planes 3:2:1:0 to construct its tiles.
      MODE 2: 2 layers of 3BPP+1BPP characters. These layers use planes 2:1:0 and plane 3, respectively.
      MODE 3: 2 layers of 2BPP+2BPP characters. These layers use planes 1:0 and planes 3:2, respectively.
    There are 4 KB of dedicated RAM for storing 2 32x32 maps of 8x8 tiles (256x256 pixels per map).
- Sprites (SPR)
    128 small objects which may be placed freely in the image.
    Each sprite can be sized from 8x8 to 8x32 by stacking up to 4 characters of any BPP.
    Each sprite may either be sandwiched between both BGs or placed above them.
    There are 640 bytes of dedicated attribute RAM with each sprite taking up 5 bytes.
- Window (WIN)
    A programmable rectangle generator which may be used to limit the areas in where the layers can be shown.

This chip also provides a multi-channel backlight driver using 8-bit PWM.


*** MEMORY MAP ***

The following memory pools in the HiveCraft's memory map are allocated to the Radar chip:

$008000 - $00FFFF  32 KB  8-bit    VRAM
$FFE000 - $FFE7FF   2 KB  8-bit    BG1 Tilemap RAM
$FFE800 - $FFEFFF   2 KB  8-bit    BG2 Tilemap RAM
$FFF000 - $FFF27F  640 B  8-bit    Sprite Attribute RAM
$FFF280 - $FFF29F   32 B  8-bit    I/O Registers
$FFF2A0 - $FFF2BF   32 B  8-bit    Palettes
$FFF2C0 - $FFF2FF   64 B  8-bit    <reserved>


*** VRAM ***

This is a 32 KB block of memory dedicated to storing a collection of 8x8 mnemonics called "characters".
It is organized as 4 segments of 8 KB, each of which stores a 1BPP "plane" of character data.
VRAM holds a total of 4096 characters shared among the BGs and the SPR objects.

Organization:
$008000 - $009FFF  8 KB    Plane 0
$00A000 - $00BFFF  8 KB    Plane 1
$00C000 - $00DFFF  8 KB    Plane 2
$00E000 - $00FFFF  8 KB    Plane 3

Per Plane:
+0    - +7       Character 0
+8    - +15      Character 1
...
+8184 - +8191    Character 1023

Per Character:
+0    ABCDEFGH    A: Left-most pixel, H: Right-most pixel
+1    ABCDEFGH    ^
...               |
+7    ABCDEFGH    |

VRAM can also hold a 256x256, 4BPP bitmap for use with BG mode 0.
Any characters for SPRs must be interleaved within the bitmap, preferably on its left or right edge.

Format:
$008000 - $00807F    Row 0
$008080 - $0080FF    Row 1
...
$00FF80 - $00FFFF    Row 255

Per Row:
+0      AAAABBBB    A: Pixel 0, B: Pixel 1
+1      AAAABBBB    A: Pixel 2, B: Pixel 3
...
+127    AAAABBBB    A: Pixel 254, B: Pixel 255

When the RPPU constructs a pixel from bitplanes or reads from the packed bitmap,
a pixel value of 0 is treated as transparent.


*** TILEMAP RAM ***

These are two 2 KB blocks of memory storing the tilemap data for each BG.

Both maps are 32 tiles wide by 32 tiles tall, and are arranged in left-to-right, top-to-bottom order.

Each tilemap entry is a 16-bit little-endian word and its format varies according to the BPP and BG mode:

Bitmap:    DYYYYYYY YXXXXXXX
4BPP:      D--CCCCC CCCCCSHV
3BPP:      P--CCCCC CCCCCSHV
2BPP:      PP-CCCCC CCCCCSHV
1BPP:      PPPCCCCC CCCCCSHV
    X  -  [7:1] of the X offset into the bitmap. [0] is fixed to zero.
    Y  -  The Y offset into the bitmap.
    D  -  Display Priority:  0 = Display with respect to sprite priority. (High)
                             1 = Always display behind sprites.           (Low)
    V  -  If set, the character is flipped vertically.
    H  -  If set, the character is flipped horizontally.
    S  -  If set, a character will be displayed. If clear, this tile will be completely transparent.
    C  -  [9:0] of the character index. [11:10] is hardcoded according to the BG mode.
    P  -  The offset into the BG's palette, aligned on a boundary the same size as the number of colors.


*** SPRITE ATTRIBUTE RAM ***

This is a 640-byte block of memory storing the attributes for the SPR objects.
It is organized as 5 blocks of 128 bytes, each of which stores 1 byte of attributes for all 128 sprites.

Organization:
$FFF000 + spriteNo    XXXXXXXX
$FFF080 + spriteNo    YYYYYYYY
$FFF100 + spriteNo    CCCCC-HV
$FFF180 + spriteNo    PPPCCCCC (1BPP)
                      PP-CCCCC (2BPP)
                      P--CCCCC (3BPP)
                      ---CCCCC (4BPP)
$FFF200 + spriteNo    EDGZZBBB
    X  -  The X coordinate of the left-most column of the sprite, plus 8, relative to the left of the image.
    Y  -  The Y coordinate of the top-most row of the sprite, relative to the top of the image.
              Values from $E0 to $FF are treated as negative coordinates.
    V  -  If set, the sprite's graphic is flipped vertically.
    H  -  If set, the sprite's graphic is flipped horizontally.
    C  -  [9:0] of the base character index. [11:10] is chosen according to B.
    P  -  The offset into the SPR's palette, aligned on a boundary the same size as the number of colors.
    B  -  Determines the sprite's BPP and which segments of VRAM to fetch the bitplanes from:
              0 - 1BPP   -:-:-:0
              1 - 1BPP   -:-:-:1
              2 - 1BPP   -:-:-:2
              3 - 1BPP   -:-:-:3
              4 - 2BPP   -:-:1:0
              5 - 2BPP   -:-:3:2
              6 - 3BPP   -:2:1:0
              7 - 4BPP   3:2:1:0
    Z  -  Sprite Size:  0 = 8x8  (1 character)
                        1 = 8x16 (2 characters stacked)
                        2 = 8x24 (3 characters stacked)
                        3 = 8x32 (4 characters stacked)
    G  -  If set, Hexagon Correction is enabled for this sprite.
    D  -  Display Priority:  0 = Display above both of the BGs. (High)
                             1 = Display in between the BGs.    (Low)
    E  -  If set, the RPPU's sprite search loop will be terminated on this sprite,
              preventing it and all subsequent sprites from being drawn.


*** I/O REGISTERS ***

There are 32 bytes of registers which control the various aspects of the LCDs, PPU, and backlight driver.

$FFF280    LCD_CTL (R/W)    LCD Control
  ----LSMM
      M (R)   - The current state of the LCD frame operation:
                    0 - Pre-render or Active Display
                    1 - HBLANK
                    2 - VBLANK
                    3 - HBLANK + VBLANK
      S (R/W) - If set, the 7-segment auxiliary display is turned on.
      L (R/W) - If set, the main hexagon display is turned on and the RPPU will operate.

$FFF281    <reserved>

$FFF282    LCD_LINE_L (R)    LCD Current Line (Low)
$FFF283    LCD_LINE_H (R)    LCD Current Line (High)
  -------L LLLLLLLL
      L (R)   - The LCD line currently being drawn to.
                    0 to 223 correspond to Active Display.
                    224 to 261 correspond to VBLANK period lines.

$FFF284    LCD_LINECP_L (R/W)    LCD Compare Line (Low)
$FFF285    LCD_LINECP_H (R/W)    LCD Compare Line (High)
  -------L LLLLLLLL
      L (R/W) - The LCD line on which to send a Line Compare interrupt to the HiveCraft.
                    0 to 223 correspond to Active Display.
                    224 to 261 correspond to VBLANK period lines. (not recommended)
                    If between 262 and 511, no Line Compare interrupt will be fired.

$FFF286    RAD_CTL_L (R/W)    RadarPPU Control (Low)
$FFF287    RAD_CTL_H (R/W)    RadarPPU Control (High)
  HGIIIOOO WSBANNMM
      M (R/W) - The background mode to use:
                    0 - Bitmap
                    1 - 4BPP
                    2 - 3BPP+1BPP
                    3 - 2BPP+2BPP
      N (R/W) - Specifies additional operating functions for BG modes 2 and 3:
                    0 - Normal
                    1 - Exchange BG1 and BG2
                    2 - Enable Palette Modulation
                    3 - Exchange BG1 and BG2, then enable Palette Modulation
                    This field must be set to 0 for BG modes 0 and 1.
      A (R/W) - If set, BG1 is displayed.
      B (R/W) - If set, BG2 is displayed. This bit must be cleared for BG modes 0 and 1.
      S (R/W) - If set, the SPR engine is enabled.
      W (R/W) - If set, the window is enabled.
      O (R/W) - These bits control which layers to display outside of the window rectangle:
                    +$0100 = Show BG1
                    +$0200 = Show BG2
                    +$0400 = Show SPR
      I (R/W) - These bits control which layers to display inside the window rectangle:
                    +$0800 = Show BG1
                    +$1000 = Show BG2
                    +$2000 = Show SPR
      G (R/W) - If set, Hexagon Correction is enabled for BG1.
      H (R/W) - If set, Hexagon Correction is enabled for BG2.

$FFF288    RAD_WINL (R/W)    Window Left Edge
  LLLLLLLL
$FFF289    RAD_WINT (R/W)    Window Top Edge
  TTTTTTTT
$FFF28A    RAD_WINR (R/W)    Window Right Edge
  RRRRRRRR
$FFF28B    RAD_WINB (R/W)    Window Bottom Edge
  BBBBBBBB
      L (R/W) - The inclusive X position of the left edge of the window rectangle.
                    This value must not exceed the display boundary of 167.
      T (R/W) - The inclusive Y position of the top edge of the window rectangle.
                    This value must not exceed the display boundary of 223.
      R (R/W) - The exclusive X position of the right edge of the window rectangle.
                    This value must not exceed the display boundary of 168, and also must be greater than L.
      B (R/W) - The exclusive Y position of the bottom edge of the window rectangle.
                    This value must not exceed the display boundary of 224, and also must be greater than T.

$FFF28C    RAD_BG1X (R/W)    BG1 X Scroll
  XXXXXXXX
$FFF28D    RAD_BG1Y (R/W)    BG1 Y Scroll
  YYYYYYYY
      X (R/W) - The horizontal scroll offset into BG1's map.
      Y (R/W) - The vertical scroll offset into BG1's map.

$FFF28E    RAD_BG2X (R/W)    BG2 X Scroll
  XXXXXXXX
$FFF28F    RAD_BG2Y (R/W)    BG2 Y Scroll
  YYYYYYYY
      X (R/W) - The horizontal scroll offset into BG2's map in BG modes 2 and 3.
      Y (R/W) - The vertical scroll offset into BG2's map in BG modes 2 and 3.

$FFF290 - $FFF297    LCD_7SEG (R/W)    7-Segment LCD Data

These 8 registers store the segment data to display.

Organization:
+0    -GFEDCBA  (left-most digit)
+1    -GFEDCBA
...
+7    -GFEDCBA  (right-most digit)
       A
     -----
  F |     | B
    |  G  |
     -----
  E |     | C
    |  D  |
     -----
If a bit is set, its corresponding segment is turned on.

$FFF298    BLD_CTL (R/W)    Backlight Driver Control
  T------E
      E (R/W) - If set, the backlight is enabled.
      T (R)   - Backlight Type:  0 = Monochrome
                                 1 = RGB

$FFF299    BLD_R (R/W)    Backlight Red/Monochrome Intensity
  RRRRRRRR
$FFF29A    BLD_G (R/W)    Backlight Green Intensity
  GGGGGGGG
$FFF29B    BLD_B (R/W)    Backlight Blue Intensity
  BBBBBBBB
      R (R/W) - The intensity of the backlight's red channel.
      G (R/W) - The intensity of the backlight's green channel.
                    <undefined> on the monochrome type.
      B (R/W) - The intensity of the backlight's blue channel.
                    <undefined> on the monochrome type.

$FFF29C    <reserved>
$FFF29D    <reserved>
$FFF29E    <reserved>

$FFF29F    LCD_VER (R)    LCD Module Version Number
  VVVVVVVV
      V (R)   - The version of the Radar chip, starting from $00.


*** PALETTES ***

There are 4 palettes of 16 entries each, with each entry being a 4-bit grayscale level.
These palettes may be subdivided into 8, 16, or 32 smaller palettes according to the BPP of a character.
Palettes serve as a means to translate raw pixels from VRAM into actual intensity levels for the display.

Because a pixel value of 0 is treated as transparent, the first entry of each palette will effectively be unused.

When a pixel in the image is not occupied by a BG or SPR, the resulting output will be the "backdrop" color.
This color is entry 0 of the low-priority BG palette.

Organization:
$FFF2A0 - $FFF2A7    PAL_SPRH (R/W)    High-Priority SPR Palette
$FFF2A8 - $FFF2AF    PAL_BGH  (R/W)    High-Priority BG Palette
$FFF2B0 - $FFF2B7    PAL_SPRL (R/W)    Low-Priority SPR Palette
$FFF2B8 - $FFF2BF    PAL_BGL  (R/W)    Low-Priority BG Palette

Per Palette:
+0    AAAABBBB    A: Entry 0, B: Entry 1
+1    AAAABBBB    A: Entry 2, B: Entry 3
...
+7    AAAABBBB    A: Entry 14, B: Entry 15

The grayscale ramp is linear, with 0 being no intensity (white) and 15 being maximum intensity (black).

Palette Modulation:

This is a special function of BG modes 2 and 3 which repurposes the character pixel data of the low-priority BG,
allowing to change the high-priority BG's palette offset at the pixel level.
The low-priority BG itself is not displayed, and the palette offsets in the tile data for both BGs are ignored.

Palette modulation takes effect as long as both BGs are set to visible and the window allows them for the given pixel.
Otherwise, the BGs will be displayed as normal using the palette offsets from their tile data.

Depending on the BPP of the BGs, the index into the high-priority one's palette is modulated as follows:

BGH     BGL     Combined BGH Pixel    Note
3BPP    1BPP    L:H:H:H               BG Mode 2, No BG Exchange
1BPP    3BPP    L:L:L:H               BG Mode 2, BG Exchange
2BPP    2BPP    L:L:H:H               BG Mode 3
      H  -  The character pixel from the high-priority BG.
      L  -  The character pixel from the low-priority BG.

In any case, a character pixel value of 0 in the high-priority BG will always be treated as transparent,
so the backdrop color and low-priority sprites will be shown behind the modulated background.


*** BG LAYERS ***

The RPPU provides 2 independent, freely scrollable layers of tiles using embedded tilemap memory.

Each BG uses a 32x32 map of 8x8 tiles, i.e. 256x256 pixels, which is beyond the dimensions of the LCD image.

The scrolling registers ($FFF28C-$FFF28F) dictate the pixel positions within the maps to be displayed
at the upper-left corner of the 168x224 LCD image.
Increasing one of these registers will move the viewport further rightwards or downwards within the map.
When scrolling beyond the edges of the map, the data from the other side will be repeated.

BG Modes:

The RPPU provides 4 modes of displaying BGs, which serve to balance BG count and bit depth (BPP).

Mode 0:
This mode provides a single layer of 4BPP packed graphics using a 256x256 bitmap as the image source.
Each tile stores an X offset and a Y offset into this bitmap, as well as a priority setting (high or low).
The X offset must be even, i.e. on a 2-pixel boundary. This ensures adjacent pixels will be fetched in groups of 2.
When scrolling beyond the edges of the bitmap, the pixels from the other side will be repeated.

This mode uses BG1 only.

Mode 1:
This mode provides a single layer of 4BPP character graphics.
Each tile can be set to either high or low priority, as with Mode 0.

This mode uses BG1 only.

Mode 2:
This mode provides 2 independent layers of character graphics.
BG1 uses 3BPP characters from planes 2:1:0.
BG2 uses 1BPP characters from plane 3.

Mode 3:
This mode provides 2 independent layers of character graphics.
BG1 uses 2BPP characters from planes 1:0.
BG2 uses 2BPP characters from planes 3:2.

BG Priority:

By default, BG1 is assigned as high-priority and BG2 is assigned as low-priority.
When BG Exchange is enabled, their priorities are reversed from the usual order.
This is useful in BG Mode 2 to display 1BPP elements on top of 3BPP elements.


*** SPR ENGINE ***

The RPPU provides a sprite engine with support for a maximum of 128 individual objects on-screen.

Sprites may be composed of 1 to 4 characters from VRAM stacked under each other,
yielding sprite heights of 8, 16, 24 or 32 pixels.
The RPPU applies an OR operation to the 10-bit character base to get the indices of the subsequent characters,
so the base character must be a multiple of 2 for 16-pixel height, or a multiple of 4 for 24- or 32-pixel height.

SPR Priority:

When multiple sprites occupy the same pixel in the image,
the sprites are oriented such that the one with the highest offset into Sprite Attribute RAM is displayed on top.
As such, sprite 0 will have the lowest priority, and sprite 127 will have the highest priority of all.

Each sprite has a priority setting which may be set to either high or low.
However, this does not affect the sprite's relationship to other sprites.
It only controls the relationship with the BG tiles.

When set to the same priority, sprites will dominate BG tiles.

Scanline Limits:

[TBD]


*** WINDOW ***

This is a programmable rectangle generator which can be used to restrict where the BGs and SPR can be shown.


*** HEXAGON CORRECTION ***

Due to the staggered hexagon arrangement of the pixels on the display,
every other scanline will appear to be offset by half a pixel.
Imagery designed with this arrangement in mind will appear to be distorted if care is not taken
to ensure that the diagonal segments in the image line up, depending on where it is displayed.

If a BG layer is scrolled to an odd Y position or a sprite is placed at an odd Y coordinate,
every other line within its graphic will be subject to this offsetting.

To correct these issues, the RPPU provides the Hexagon Correction function.
When a BG's Y scroll is odd, every odd-numbered scanline within its viewport will be scrolled 1 pixel to the right.
When a sprite's Y coordinate is odd, every odd-numbered row of its graphic will be shifted rightwards by 1 pixel.

This feature can be enabled for each BG layer and sprite separately.


*** APPENDIX ***

Display Priority Relationship:

  +------------------+
  | BG Low/Backdrop  |
  |  +------------------+
  |  | SPR Low Pixels   |
  |  |  +------------------+
  |  |  | BG High          |
  |  |  |  +------------------+
  |  |  |  | SPR High Pixels  |
  |  |  |  |         +        |
  +--|  |  |        / \       |
     |  |  |     --- 1 \      |
     +--|  |    | 2 |-- +     |
        |  |    | +-----+     |
        +--|     -|  3  |     |
           |      +-----+     |
           +------------------+

Rendering Timings:

NOTE: Check `ppu_timings.txt` by Kagamiin.