Changeset 469 for trunk/asma/Docs


Ignore:
Timestamp:
Jul 30, 2012, 9:53:11 PM (12 years ago)
Author:
pfusik
Message:

Sap.txt: rewordings and more details.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/asma/Docs/Sap.txt

    r62 r469  
    66History
    77-------
    8 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.
     8The 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.
    99
    1010At the time of writing there are four independent players of the SAP format:
    … …  
    1919-------
    2020The 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.
    21 The same method is used on other platforms, for example the SID format for the C64 music.
    22 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.
    23 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.
     21Identical method is used with platforms other than Atari, for example the SID format for the C64 music.
     22Important 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.
     23One 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.
    2424
    2525File Naming Conventions
    … …  
    4040Part One - Text Header
    4141----------------------
    42 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.
     42This 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.
    4343Example of the header:
    4444SAP
    … …  
    5656The first line must consist of the word "SAP" immediately followed by CR/LF, for format identification.
    5757It 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.
    58 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).
     58The 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).
    5959It is strongly recommended that all SAP files contain the AUTHOR, NAME and DATE tags. Use "<?>" for unknown values.
    6060
    … …  
    8282    DATE "28/08/1997"
    8383    DATE "12/2001"
     84    DATE "23-26/07/2010"
     85    DATE "199?"
     86
     87    The last example means some unknown year in the 1990s.
    8488
    8589SONG
    … …  
    8791
    8892DEFSONG
    89     Zero-based index of the song that should be played when the file is opened. Defaults to zero.
     93    Zero-based index of the subsong that should be played first when the file is opened. Defaults to zero.
    9094
    9195STEREO
    … …  
    99103
    100104FASTPLAY
    101     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.
     105    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.
    102106
    103107INIT
    104     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.
     108    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.
    105109
    106110MUSIC
    … …  
    124128Part Two - Binary Data
    125129----------------------
    126 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).
    127 The difference from Atari executables is that INIT (0x2e2) and RUN (0x2e0) blocks are not supported.
     130This 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).
     131The difference from real Atari executables is that INIT (0x2e2) and RUN (0x2e0) blocks are not supported.
    128132
    129133Example:
    … …  
    147151    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.
    148152    D100-D1FF - reserved for parallel devices connected to the Atari, do not use.
    149     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.
     153    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.
    150154    D300-D3FF - reserved for the PIA chip, do not use.
    151155    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.
    … …  
    165169
    166170TYPE C
    167     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:
     171    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:
    168172
    169173        lda #$70
    … …  
    178182
    179183TYPE D
    180     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.
     184    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.
    181185
    182186TYPE S
    … …  
    187191
    188192Game_Music_Emu supports only types B and C.
     193
     194When 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.
     195
     196When starting a song, a SAP player must initialize POKEY registers to: AUDF1-4 = AUDC1-4 = AUDCTL = IRQEN = 0, SKCTL = 3.
Note: See TracChangeset for help on using the changeset viewer.