Index: /trunk/asma/Docs/Sap.txt =================================================================== --- /trunk/asma/Docs/Sap.txt (revision 468) +++ /trunk/asma/Docs/Sap.txt (revision 469) @@ -6,5 +6,5 @@ History ------- -The SAP format was created in the 1990s by Adam Bienias and was intended to be a single format for playback of any 8-bit Atari music on a PC. Adam Bienias has also created the first player for Windows and later published its source code so that other players were created. +The SAP format was created in the 1990s by Adam Bienias and was intended to be a single format for playback of any 8-bit Atari music on a PC. Adam Bienias has also created the first player for Windows and later published its source code so that other players appeared. At the time of writing there are four independent players of the SAP format: @@ -19,7 +19,7 @@ ------- The SAP format contains the original data and code used to playback the Atari music. SAP players actually run the program contained in the SAP file on an emulated or real (sapemu) 6502 processor. The program controls the POKEY chip, which generates the sound. -The same method is used on other platforms, for example the SID format for the C64 music. -Important advantages of SAP over, let’s say, MP3 are that SAP files are very small (about 5 KB on average) and play more accurately as new players improve their emulation. The downside is that SAP files are generally hard to create. Creating SAP files from Atari software is called ripping and requires some knowledge of the 6502 assembly language. On the other hand, Atari music in popular formats such as CMC or RMT can be easily converted to SAP (and back) using ASAP. -One SAP file may contain multiple independent tunes - these are called "subsongs". For example, a game containing many songs may be ripped into one SAP file. Over 90% SAP files contain just one song. Unfortunately many audio players do not support the concept of multiple subsongs per file. +Identical method is used with platforms other than Atari, for example the SID format for the C64 music. +Important advantages of SAP over, let’s say, MP3, are that SAP files are very small (about 5 KB on average) and play more accurately as new players improve their emulation. The downside is that SAP files are generally hard to create. Creating SAP files from Atari software is called ripping and requires knowledge of the 6502 assembly language. On the other hand, Atari music in popular formats such as CMC or RMT can be easily converted to SAP (and back) using ASAP. +One SAP file may contain multiple independent tunes - these are called "subsongs". For example, several songs from one game may be ripped into one SAP file. Over 90% SAP files contain just one song. Unfortunately many audio players do not support the concept of multiple subsongs per file. File Naming Conventions @@ -40,5 +40,5 @@ Part One - Text Header ---------------------- -This part consists of tags, one tag per line. Lines must be terminated by a CR/LF (0x0d, 0x0a) pair (required by ASAP, other SAP players may be more forgiving). A line consists of an uppercase tag name and an optional argument which may be a string, a decimal integer, a hexadecimal integer or a single letter. The argument should be separated from tag name with a single space. Extra whitespace is not allowed. +This part consists of tags, one tag per line. Lines must be terminated by a CR/LF (0x0d, 0x0a) pair (required by ASAP, other SAP players may be more forgiving). A line consists of an uppercase tag name and an optional argument, which may be a string, a decimal integer, a hexadecimal integer or a single letter. The argument should be separated from tag name with a single space. Extra whitespace is not allowed. Example of the header: SAP @@ -56,5 +56,5 @@ The first line must consist of the word "SAP" immediately followed by CR/LF, for format identification. It is recommended, but not required, that tags are specified in the order described here. Note that format identification in GStreamer requires the AUTHOR tag be placed right after the "SAP" line. -The arguments to AUTHOR, NAME and DATE must be wrapped in doublequotes. Allowed characters are those identical in ASCII and ATASCII (ATari ASCII), which are: characters with ASCII codes from space to underscore plus all lowercase letters plus the pipe (|). There are no backquote, tilde nor curly brackets in ATASCII. It is recommended to avoid doublequotes inside the arguments, as not all SAP players handle them. The arguments should be limited to 120 characters (plus the outer quotes). +The arguments to AUTHOR, NAME and DATE must be wrapped in doublequotes. Allowed characters are those identical in ASCII and ATASCII (ATari ASCII), which are: characters with ASCII codes from space to underscore plus all lowercase letters plus the pipe character (|). There are no backquote, tilde nor curly brackets in ATASCII. It is recommended to avoid doublequotes inside the arguments, as not all SAP players handle them. The arguments should be limited to 120 characters (plus the outer quotes). It is strongly recommended that all SAP files contain the AUTHOR, NAME and DATE tags. Use "" for unknown values. @@ -82,4 +82,8 @@ DATE "28/08/1997" DATE "12/2001" + DATE "23-26/07/2010" + DATE "199?" + + The last example means some unknown year in the 1990s. SONG @@ -87,5 +91,5 @@ DEFSONG - Zero-based index of the song that should be played when the file is opened. Defaults to zero. + Zero-based index of the subsong that should be played first when the file is opened. Defaults to zero. STEREO @@ -99,8 +103,8 @@ FASTPLAY - Number of scanlines between calls of the player routine. A scanline is defined to be 114 clock cycles. FASTPLAY defaults to one frame: 312 scanlines for PAL (about 50 Hz), 262 for NTSC (about 60 Hz). Most songs don’t include this tag. Common values are 156 (twice per frame), 104 (three times per frame) and 78 (four times per frame). ASAP 3.0.0 and above supports FASTPLAY up to 32767. Other SAP players may limit the value to 312. + Number of scanlines between calls of the player routine. A scanline is defined to be 114 Atari clock cycles. FASTPLAY defaults to one frame: 312 scanlines for PAL (about 50 Hz), 262 for NTSC (about 60 Hz). Most songs don’t include this tag. Common values are 156 (twice per frame), 104 (three times per frame) and 78 (four times per frame). ASAP 3.0.0 and above supports FASTPLAY up to 32767. Other SAP players may limit the value to 312. INIT - Hexadecimal address of a 6502 routine that initializes the player. Required for player types B, D and S. Invalid for type C. The address should be specified as four uppercase hexadecimal digits, although players usually forgive lowercase and less digits. + Hexadecimal address of a 6502 routine that initializes the player. Required for player types B, D and S. Invalid for type C. The address should be specified as four uppercase hexadecimal digits, although players usually forgive lowercase and fewer digits. MUSIC @@ -124,6 +128,6 @@ Part Two - Binary Data ---------------------- -This part contains the player routine and music data in the format of Atari executables. This format has a two-byte header 0xFF, 0xFF. The following two bytes are the starting memory address (little endian), the next two bytes are the ending address. Then data bytes follow. Usually there are multiple blocks (the 0xFF/0xFF header is only required for the first block). -The difference from Atari executables is that INIT (0x2e2) and RUN (0x2e0) blocks are not supported. +This part contains the player routine and music data in the format of Atari executables. This format has a two-byte header 0xFF, 0xFF. The two following bytes are the starting memory address (little endian), the next two bytes are the ending address. Then data bytes follow. Usually there are multiple blocks (the 0xFF/0xFF header is only required for the first block). +The difference from real Atari executables is that INIT (0x2e2) and RUN (0x2e0) blocks are not supported. Example: @@ -147,5 +151,5 @@ D000-D0FF - GTIA chip mirrored 8 times. ASAP maps just the PAL register at D014 for NTSC/PAL detection and the CONSOL register at D01F for 1-bit sounds, the rest is RAM. D100-D1FF - reserved for parallel devices connected to the Atari, do not use. - D200-D2FF - POKEY chip mirrored 16 times or two POKEY chips (stereo) mirrored 8 times. At least the AUDF1-4, AUDC1-4 and AUDCTL registers must be implemented in a SAP player. Emulation of timer interrupts via IRQEN and IRQST is strongly recommended. SAP by Adam Bienias emulates only timer 1 interrupts. + D200-D2FF - POKEY chip mirrored 16 times or two POKEY chips (stereo) mirrored 8 times. At least the AUDF1-4, AUDC1-4, AUDCTL and RANDOM registers must be implemented in a SAP player. Emulation of timer interrupts via IRQEN and IRQST is strongly recommended. SAP by Adam Bienias emulates only timer 1 interrupts. D300-D3FF - reserved for the PIA chip, do not use. D400-D4FF - ANTIC chip mirrored 16 times. SAP files may rely on WSYNC (D40A) and VCOUNT (D40B) registers. ASAP also implements NMIST/NMIRES (D40F), but not NMIEN (D40E). The playback routine should be driven by the PLAYER/FASTPLAY mechanism instead of directly programming ANTIC interrupts. @@ -165,5 +169,5 @@ TYPE C - This type is for convenience of handling CMC (Chaos Music Composer) music. The player is initialized using the values of MUSIC, PLAYER and DEFSONG as follows: + This type is for easy handling CMC (Chaos Music Composer) music. The player is initialized using the values of MUSIC, PLAYER and DEFSONG as follows: lda #$70 @@ -178,5 +182,5 @@ TYPE D - This is similar to TYPE B, but used for digitalized music. The difference is that the INIT routine must not return. It should play the digitalized music. It can use WSYNC and VCOUNT registers and/or POKEY timer interrupts for timing. The POKEY interrupts can be programmed via IRQEN/IRQST/AUDF1-4/AUDCTL registers, the FFFE/FFFF interrupt vector and the I 6502 flag. All 6502 registers (including flags) are saved when calling the PLAYER routine and restored when it returns to the running INIT routine. In ASAP 2.1.0 and above the PLAYER tag is optional for TYPE D. + This is similar to TYPE B, but used for digitalized music. The difference is that the INIT routine must not return. It should play the digitalized music. It can use WSYNC and VCOUNT registers and/or POKEY timer interrupts for timing. The POKEY interrupts can be programmed via IRQEN/IRQST/AUDF1-4/AUDCTL registers, the FFFE/FFFF interrupt vector and the I 6502 flag (which is initially clear, allowing interrupts). All 6502 registers (including flags) are saved when calling the PLAYER routine and restored when it returns to the running INIT routine. In ASAP 2.1.0 and above the PLAYER tag is optional for TYPE D. First call to PLAYER usually occurs before the first instruction of INIT gets executed. TYPE S @@ -187,2 +191,6 @@ Game_Music_Emu supports only types B and C. + +When 6502 routines get called, don't assume register values except for the specified above. For example, don't assume that the INIT routine starts with zero in the X register. Also, don't assume that 6502 registers are unchanged between the calls to PLAYER or from INIT to PLAYER. + +When starting a song, a SAP player must initialize POKEY registers to: AUDF1-4 = AUDC1-4 = AUDCTL = IRQEN = 0, SKCTL = 3.