gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 18:22:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

rgbasm(5): Clarify charmap behavior (#558)

Browse Source
This commit is contained in:
dannye
2021-02-27 11:29:53 -06:00
committed by Eldred Habert
parent 8a75cc5051
commit a4049a3f1b
1 changed files with 12 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
src/asm/rgbasm.5
View File

@@ -391,16 +391,21 @@ with its corresponding argument in
.Pq So %% Sc is replaced by the So % Sc character .
.El
.Ss Character maps
When writing text that is meant to be displayed in the Game Boy, the characters used in the source code may have a different encoding than the default of ASCII.
For example, the tiles used for uppercase letters may be placed starting at tile index 128, which makes it difficult to add text strings to the ROM.
When writing text that is meant to be displayed on the Game Boy, the characters used in the source code may need to have a different encoding than the rest of the source code.
For example, the tiles used for uppercase letters may be placed starting at tile index 128, which would make it difficult to add text strings to the ROM.
.Pp
Character maps allow mapping strings up to 16 characters long to an abitrary 8-bit value:
Character maps allow mapping strings to arbitrary 8-bit values:
.Bd -literal -offset indent
CHARMAP "<LF>", 10
CHARMAP "&iacute", 20
CHARMAP "A", 128
.Ed
By default, a character map contains ASCII encoding.
This would result in
.Ql db \(dqAmen<LF>\(dq
being equivalent to
.Ql db 128, 109, 101, 110, 10 .
.Pp
Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.
.Pp
It is possible to create multiple character maps and then switch between them as desired.
This can be used to encode debug information in ASCII and use a different encoding for other purposes, for example.
@@ -410,20 +415,15 @@ and it is automatically selected as the current character map from the beginning
There is also a character map stack that can be used to save and restore which character map is currently active.
.Bl -column "NEWCHARMAP name, basename"
.It Sy Command Ta Sy Meaning
.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name .
.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename .
.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name No and switches to it.
.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it.
.It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
.It Ic PUSHC Ta Push the current character map onto the stack.
.It Ic POPC Ta Pop a character map off the stack and switch to it.
.El
.Pp
.Sy Note:
Character maps affect all strings in the file from the point in which they are defined, until switching to a different character map.
This means that any string that the code may want to print as debug information will also be affected by it.
.Pp
.Sy Note:
The output value of a mapping can be 0.
If this happens, the assembler will treat this as the end of the string and the rest of it will be trimmed.
Modifications to a character map take effect immediately from that point onward.
.Ss Other functions
There are a few other functions that do various useful things:
.Bl -column "DEF(symbol)"