MESS OUT

=MESS_OUT ($C004CE): Generic VRAM output=

MESS_OUT executes the command buffer in the System ROM's work RAM that starts at BIOS_MESS_BUFFER (constant $10FF00) and goes up to BIOS_MESS_POINT (longword variable $10FDBE). This can be used to display text messages, boxes... on the fix layer (is it used for sprites too ?).

MESS_OUT is automatically called in the SYSTEM_INT1 call. BIOS_MESS_BUSY ($10FDC2.b) can be used to prevent this (when setting up the command list, for example).

The command buffer can be made of commands directly, or pointers to lists in ROM or user RAM. To put commands directly into the buffer, a null pointer ($00.l) needs to be placed before the command list.

Commands are always words.

=Commands=

Command 0: End of command list
1 word: $0000

Command 1: Set data format
2 words:

This command specifies if the data will be in bytes or words, and if the size is defined or if an end code has to be reached.


 * If data is in bytes (bit 9 = 0):
 * The next word's upper byte will be the data's constant upper byte (since VRAM can only be written in words).
 * If the data is limited by an end code (bit 8 = 0), the next word's lower byte will be the end code's value.
 * If the data size is defined (bit 8 = 1), the next word's lower byte will be the size (so max length is $FF).


 * If data is in words (bit 9 = 1):
 * If the data is limited by an end code (bit 8 = 0), the next word will be the end code's value.
 * If the data size is defined (bit 8 = 1), the next word will be the size (so max length is $FFFF).

Examples:

The format stays the same until command 1 is used again.

Command 2: Set auto-increment

 * 1 word

Sets the auto-increment value (written to VRAM_MOD ($3C0004)). Is the value sign-extended or not ?

Command 3: Set VRAM address
Sets the VRAM address written to VRAM_ADDR ($3C0000)) to the next word's value.
 * 2 words

Command 4: Set data address
Sets the output data address to the next longword. Actual writes to VRAM are done with this command.
 * 3 words

Command 5: Add to current VRAM address
Add the next word to the current VRAM address. (This is different from command 2). Useful to skip lines or spaces.
 * 2 words

Command 6: Resume data output
Resume data output (instead of using command 4 again, keep going from the last address).
 * 1 word

Command 7: Directly define output data
Directly define the data (instead of using command 4 to point to it). Don't forget the padding byte if the data ends on an odd address.
 * at least 2 words

Command 8: Write text with 8x16 font

 * at least 2 words

Writes with the 8*16 pixels fix font. The commands upper byte will be the data's constant upper byte. The next bytes are data, and the end code is $FF.

The auto-inc is automaticaly set to $20.

Command 9: Write Japanese text
Same as command 8 but for Japanese characters.

Command A: Call sub list
Call sub command list. The next longword is a pointer to another command list. Return has to be made using command B. The call stack seems to be 5 addresses deep. Be sure to avoid nesting too many list calls.
 * 3 words

Command B: Return from sub list
Return to calling command list.
 * 1 word

Command C: Repeated data output
Repeat output. The upper byte of the command is the number of times to output the next word.
 * 2 words

Command D: Repeat and increment output

 * 2 words

Repeat and increment output. The upper byte of the command is the number of times to output the next word. The lower byte of the data is incremented each time.

=Example code and command lists= (Slightly modified code from SNK's doc, output gives the above screencap.)