esvm.txt

word = 2 bytes

0x10000 words (128 KB) of ram
addresses are words rather than bytes
0000-7fff generally contains forth dictionary and thus isn't usually swapped out

words are big endian

rom is split into 0x2000-word (16 KB) banks
maximum rom size is 0x8000 banks (512 MB)
ram contents are initialized to banks 0-7 of rom
banks can be swapped out at will, though unpredictable behavior will result if ram is overwritten while being executed

* all of this might be changed

=======================
GRAPHICS SPECIFICATIONS
=======================

resolution info
===============

screen resolution: 944x528
59 by 33 tiles (1947 tiles total) on screen, 60 by 34 tiles (2040 tiles) in memory for scrolling
tiles are always stretched to 16x16, so 8x16 tiles are stretched double-wide, etc.

screen palettes
===============

screen palette data resides in bank -5 (ppu ram) from 0000-00ff
each color takes up a word, 256 colors total
16-bit color format is 0bbbbbgg gggrrrrr (identical to snes)
converts to 24-bit color as such:
C8' = C5 * 8
C8 = C8' + C8' / 32
where C5 is the 5-bit color and C8 is the 8-bit color
palette may be modified on the fly for e.g. fading effects

graphical modes
===============

modes give a tradeoff between resolution and color depth
mode data resides in banks -1 through -4 (vram)
since there is only 64 KB of VRAM available, modes can be layered as such:
- 4 short (16 KB) modes
- 2 short (16 KB) modes and 1 long (32 KB) mode
- 2 long (32 KB) modes
* a micro size mode exists for text, but although it needs only 4 KB of space, it uses a full short (16 KB) slot
* the remaining 12 KB are unread and can thus be used for scratch space if necessary
mode ids are stored in mode headers
obviously, these are important to get right, or else the screen will appear garbled

screen data format
==================

tttttttt ??hvpppp
t: tile id
?: ?
h: horizontal flip
v: vertical flip
p: palette number

tile data format
================

tiles are stored using multiple bit planes
e.g. a 6 bpp tileset will be stored in six segments, each representing a different bit per pixel
ordered from least significant to most significant

palette reference tables
========================

note: the first color of any given palette is considered transparent

1 bpp/1 bpp
    16x16      8x16
num first last first last
  0     0    1     2    3
  1     4    5     6    7
  2     8    9    10   11
  3    12   13    14   15
  4    16   17    18   19
  5    20   21    22   23
  6    24   25    26   27
  7    28   29    30   31
  8    32   33    34   35
  9    36   37    38   39
 10    40   41    42   43
 11    44   45    46   47
 12    48   49    50   51
 13    52   53    54   55
 14    56   57    58   59
 15    60   61    62   63

2 bpp
num first last
  0     0    3
  1     4    7
  2     8   11
  3    12   15
  4    16   19
  5    20   23
  6    24   27
  7    28   31
  8    32   35
  9    36   39
 10    40   43
 11    44   47
 12    48   51
 13    52   55
 14    56   59
 15    60   63

3 bpp
num first last
  0     0    7
  1     8   15
  2    16   23
  3    24   31
  4    32   39
  5    40   47
  6    48   55
  7    56   63
  8    64   71
  9    72   79
 10    80   87
 11    88   95
 12    96  103
 13   104  111
 14   112  119
 15   120  127

4 bpp
num first last
  0     0   15
  1    16   31
  2    32   47
  3    48   63
  4    64   79
  5    80   95
  6    96  111
  7   112  127
  8   128  143
  9   144  159
 10   160  175
 11   176  191
 12   192  207
 13   208  223
 14   224  239
 15   240  255

6 bpp
num first last
  0     0   63
  1    64  127
  2   128  191
  3   192  255
  4     0   63
...

7 bpp
num first last
  0     0  127
  1   128  255
  2     0  127
...

mode header
===========
only read if preceding mode has ended
0000 mode id
0001 scroll x
0002 scroll y
0003
0004
0005
0006
0007

0000 0 = tiles
0001 tile height/width
0002 bpp
0003 tile height/width
0004 bpp
0005
0006 scroll x
0007 scroll y

mode specifications
===================

mode 0: nothing

mode 1: text micro
0000-0007 mode header
0008-07ff text screen data (flat utf-16, no tile attributes)
* uses built-in system font, 16x16 tiles, 1 bpp/1 bpp palette 0
* the advantage of this mode is that it can display full unicode
* however, custom tiles are not possible, and there's only one palette available
* not sure if i'll keep this mode, though

mode 2: 8x8 short
0000-0007 mode header
0008-07ff screen data (6 bpp palette)
0800-1fff 8x8 tile data (256 tiles)
- 0800-0bff plane 0
- 0c00-0fff plane 1
- 1000-13ff plane 2
- 1400-17ff plane 3
- 1800-1bff plane 4
- 1c00-1fff plane 5
* 24 words (384 bits) per tile
* 6 bpp / 64 colors per tile

mode 3: 8x16 short
0000-0007 mode header
0008-07ff screen data (6 bpp palette)
0800-1fff 8x16 tile data (256 tiles)
- 0800-0fff plane 0
- 1000-17ff plane 1
- 1800-1fff plane 2
* 24 words (384 bits) per tile
* 3 bpp / 8 colors per tile

mode 4: 16x16 + 8x16 short
0000-0007 mode header
0008-07ff screen data (1 bpp/1 bpp palette)
0800-17ff 16x16 tile data (256 tiles)
- 0800-17ff plane 0
* 16 words (256 bits) per tile
* 1 bpp / 2 colors per tile
1800-1fff 8x16 tile data (256 tiles)
- 1800-1fff plane 0
* 8 words (128 bits) per tile
* 1 bpp / 2 colors per tile
* 16x16 tiles are layered on top of 8x16 tiles

mode 5: 8x8 long (need to work out advantages)

mode 6: 8x16 long
0000-0007 mode header
0008-07ff screen data (7 bpp palette)
0800-3fff 8x16 tile data (256 tiles)
- 0800-0fff plane 0
- 1000-17ff plane 1
- 1800-1fff plane 2
- 2000-27ff plane 3
- 2800-2fff plane 4
- 3000-37ff plane 5
- 3800-3fff plane 6
* 56 words (896 bits) per tile
* 7 bpp / 128 colors per tile

mode 7: 16x16 long
0000-0007 mode header
0008-07ff screen data (3 bpp palette)
0800-37ff 16x16 tile data (256 tiles)
- 0800-17ff plane 0
- 1800-27ff plane 1
- 2800-37ff plane 2
* 48 words (768 bits) per tile
* 3 bpp / 8 colors per tile
3800-3fff unused? there's room for 1 bpp 8x16 or 2 bpp 8x8, but neither would be useful

mode 8: direct mode (uses all 64 KB)
* need to incorporate mode header, etc. since we don't need all 0x8000 words
0000-7fff canvas data
- 524288 bits
-  8x 8 : 2048 4bpp
- 16x 8 : 2048 2bpp
- 16x16 : 2048 1bpp
- 25856 bits
* how should palettes work?

TODO: figure out what to use two remaining bits in tile attributes for
TODO: banks? pages? where are we going with this?
TODO: work out mode 5 and 8