Format of .SAP files
Format of .SAP files is quite simple. SAP file is divided
into two parts, text part and binary part. Binary part is just an Atari Binary File. This
format is used in all atari binary programs that can be loaded with DOS 2.5 (and with
other DOSes compatible with DOS 2.5). In this format, each atari file (and binary part of
SAP file) begins with two bytes (in hex) FF,FF. Next bytes are blocks which are loaded
into Atari 65kB memory (SAP emulates this 65kB of memory). Each block begins with four
byte header. First two bytes tells to loader, when first byte of this block (without
header) should be loaded, and next two bytes (in this header) tells to loader, when the
last byte (of this block) will be placed. So, for example, block, which looks like this:
00,20,05,20,01,42,A3,04,D5
will load values 01,42,A3,04,D5 into memory, from 2000 to
2005.
Text part of SAP file always begins with a single line
"SAP". Next lines can be command lines or comment lines (each line that is not
recognized as command line, is threaded as comment line). Currently (version 0.9 of SAP
player) only those commands are recognized:
- TYPE
- INIT
- PLAYER
- MUSIC
- SONGS
- DEFSONG
- FASTPLAY
"SONGS" always describes number of songs in this
SAP file. "DEFSONG" always describes number of first song, that will be played
after SAP file is loaded ("DEFSONG" is ignored if there's only one song).
Interpreting of other commands depends on the most important command: "TYPE".
"TYPE" can contains full word, but only first character in this word is
recognized. Currently there are 4 types:
- B (binary). In SAP file with this type, must be also defined
commands "INIT" and "PLAYER". "INIT" sets address of
initialization procedure. When this procedure is called, register "A" (in 6502)
contain number of song that should be played. This procedure must return end with
"RTS" opcode. "PLAYER" sets address of procedure that will be called
in 1/50s intervals. This procedure should generate sound, that will be emulated via Pokey
emulation, and (like in "INIT") must end with "RTS" opcode.
- C (cmc). This is special type used only with songs that are
composed in quite popular Chaos Music Composer. In SAP with this type, must be also
defined commands "PLAYER" and "MUSIC". "PLAYER" sets address
of CMC player (that must be included). "MUSIC" sets address of music data for
this player. Note! This type is
probably temporary, and will be deleted in future release. You should use type
"binary" instead.
- S (SoftSynth). Like type "C", this type is
temporary, and is used only for special type of songs, that where composed using program
SoftSynth.
- D (digi). In SAP file with this type, must be also defined
commands "INIT" and "PLAYER". "PLAYER" (line in type
"B") sets address of procedure that will be called in 1/50s intervals and (like
in type "B") must end with "RTS" opcode. "INIT" this time is
little diferent. "INIT" sets address of procedure that will be called (with
number of song in register "A") to initialize program, but it cannot end with
"RTS". It should start playing digitalizations in "never ending" loop.
In SAP player are emulated two registers $D40B, and $D40A (ANTIC) that can help with
playing digitalizations. In Atari, $D40B increases every two screen lines. Single write to
$D40A holds CPU to the end of screen line. SAP emulates Atari in PAL with disabled screen.
So we have 312 screen lines with 105 CPU cycles per each line, and with 9 cycles of memory
refresh (105 cycles of CPU, and 9 cycles of memory refresh gives 114 cycles per line).
- R (registers) (will appear in
future release) In this type, binary part is not an Atari
Binary File! This part contains values that are directly written to Pokey registers
($D200-$D208) in 1/50s intervals.
Last (optional) command "FASTPLAY" can change (in
type "B") interval time. As default, procedure "PLAYER" is called in
1/50s intervals. "FASTPLAY" sets number of screen lines for each interval.
Default 1/50s sets interval to 312 lines. You can set eg. interval to 1/100s and that will
be 156 lines.
Command lines can appear in any order. This is an example of
text part:
- SAP
- AUTHOR "Adrian Galinski"
- PLAYER A000
- MUSIC 3000
- SONGS 5
- DEFSONG 0
- TYPE cmc
For more examples You can look into any .SAP files that are
already made, or ... just ask an author of SAP ;)
Hint: once You have crated text part of SAP file, You can
link this with binary part using eg.command line (in MS-DOS) "copy":
copy /b text_part+binary_part Music.sap
Note that "/b" option is nessesary !!!