source: trunk/asma/Docs/Sap.txt @ 20

Last change on this file since 20 was 8, checked in by pfusik, 25 years ago

Imported ASMA 0.8
File size: 5.2 KB
RevLine 
[4]1SAP file divides into two parts. First part (in text format) describes
2player/music type. Second part (in binary format) contains player and music
3data formed into Atari Binary File Format. This format has two bytes header
4FF,FF. Next two bytes tell loader, where to load data, and next two bytes
5describes where the data end.
6Init data block ($02E2,$02E3) is not supported.
7
[8]8A little example:
[4]9
[8]10FF FF 00 20 05 20 01 42 A3 04 D5
11\___/ \_________/ \____________/
12  A        B            C
13
14A - Binary file header identification (always FF FF)
15B - Load addres (StartAddr, EndAddr in LO,HI order - $2000 to $2005)
16C - Data (that will be loaded from StartAddr)
17
18This example will load values 01,42,A3,04,D5 into memory from $2000 to
19$2005.
20
21
[4]22Player Description format (first part of .sap file)
23~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
24This description (in text format) is loaded line per line. Each line contains
25command with parameters. Other lines which are not recognized are treated as
26comment lines. Right now only these commands are supported:
27
28   TYPE      - player type
29   PLAYER    - address of player part which will be executed in 1/50 sec
30               intervals
31   MUSIC     - address with data
32   INIT      - address of player part which will init player
33   SONGS     - number of songs
34   DEFSONG   - first song which will be played when .sap will be loaded
[6]35   FASTPLAY  - number of lines between each call of playing routine (312 by
36               default, which is one screen - 1/50 of sec.). For example for
37               double-speed tune put here the value 156 (312/2). 99% of tunes
38               are single-speed which means that you don't have to define the
[8]39               FASTPLAY variable for them. Works for player TYPE "B".
40
[4]41commands PLAYER, MUSIC, INIT contain addresses in hexadecimal format:
42
43PLAYER A000
44PLAYER 1234
45MUSIC  F400
46
47commands SONGS, DEFSONG contain decimal numbers:
48
49SONGS 10
50DEFSONG 9
51
52command TYPE contains single character which describes player type. Right now
53only the following characters are supported:
54
55TYPE C
56TYPE B
57TYPE M
[8]58TYPE S
59TYPE D
60TYPE R
[4]61
62TYPE C - player from CMC (Chaos Music Composer). In this case, also these
63         commands must appear: PLAYER, MUSIC, SONGS, and DEFSONG. Player will
64         be initialized as follows:
65
66         lda #$70
67         ldx #<MUSIC
68         ldy #>MUSIC
69         jsr PLAYER+6
70         lda #$00
71         ldx #DEFSONG
72         jsr PLAYER+6
73
74         in 1/50 intervals will be executed:
75
76         jsr PLAYER+3
77
78TYPE M - player from ???????? (this player was used by composers like Adam
79         Gilmore, David Whittaker, etc). In this case, also these commands
80         must appear: PLAYER, INIT, SONGS, and DEFSONG. Player will be
81         initialized as follows:
82
83         lda #DEFSONG
84         jsr INIT
85
86         in 1/50 intervals will be executed:
87
88         jsr PLAYER
89
90TYPE B - any player. In this case, also these commands must appear: PLAYER,
91         INIT, SONGS, and DEFSONG. Player will be initialized as follows:
92
93         lda #DEFSONG
94         jsr INIT
95
96         in 1/50 intervals will be executed:
97
98         jsr PLAYER
99
100         TYPE B is right now exactly the same like TYPE M but this
101         distinguish is for future SAP releases.
102
[8]103TYPE S - SoftSynth. Like type "C", this type is temporary, and is used only
104         for special type of songs, that where composed using program
105         SoftSynth.
106TYPE D - Digital. In SAP file with this type, must be also defined commands
107         "INIT" and "PLAYER". "PLAYER" (like in type "B") sets address of
108         procedure that will be called in 1/50s intervals and (like in type
109         "B") must end with RTS opcode. INIT this time is a bit different. It
110         sets address of procedure that will be called (with number of song
111         in register A) to initialize program, but it can't end with RTS. It
112         should start playing digis in endless loop. In SAP player there are
113         emulated two ANTIC registers $D40A and $D40B that can help playing
114         samples. D40B register increases its contents each two screen lines.
115         D40A holds CPU till the end of actually created line. SAP emulates
116         Atari in PAL with disabled screen. It means that we have 312 PAL
117         lines, while each lines has 105 CPU cycles and 9 cycles of memory
118         refresh (114 cycles per line).
[4]119
[8]120Planned features:
121TYPE R - Registers. In this type, binary part is not an Atari binary file.
122         This part contains values that will be directly written to Pokey
123         registers ($D200-$D208) in 1/50s intervals.
124TIME xx:xx - song duration
125
[4]126How to create .SAP file
127~~~~~~~~~~~~~~~~~~~~~~~
128First of all we need to rip music from a game or a demo and save it in atari
129binary file. Next we can create text file with commands (described above),
130then we can make .sap file by linking thwse two files. We can do that using
131DOS command "copy", e.g.:
132
133copy /b music.txt+music.bin music.sap
134
[8]135The file is done now!
136If you didn't find that song in ASMA, feel free to send it to pg@pinknet.cz
137with all needed information (see ASMA.TXT for detailed information). The song
138should be included in the nearest ASMA update.
Note: See TracBrowser for help on using the repository browser.