Structure of sequence data
Describes the structure of the sequence data of the RareWare Sound Driver used in Donkey Kong Country 2/3, Diddy’s Kong Quest and Dixie Kong’s Double Trouble.
For the addresses of each variable in APU RAM, see APU RAM map.
Notation
In this manual, command syntax is written as follows.
0x02, sbyte left, sbyte right
The first item is the command’s byte value, followed by the parameter types and names in the order they appear in the data. The types are byte (unsigned 8-bit), sbyte (signed 8-bit) and ushort (unsigned 16-bit, little-endian). The only exception is when note lengths are specified in 16 bits, which are big-endian.
All addresses are absolute addresses in APU RAM, not offsets within the sequence data.
Layout of sequence data
Sequence data is placed starting at $1300 in APU RAM.
Header
The music track header is placed at the start of the sequence data.
| Offset | Type | Contents |
|---|---|---|
| +$00 | ushort[8] | Start address of the sequence of each BGM channel (0-7) |
| +$10 | byte | Initial tempo |
| +$11 | byte | Initial SE tempo |
| +$12 | ushort[] | Table of music track header addresses (CPU command $83 uses its argument as the index to select the next track to play) |
When a track is initialized, all 8 channels start running. Even unused channels must point to a valid sequence, such as one consisting only of command 0x00.
Sound effects
Sound effects $00-$5F are read from the table in the SE data area ($2410), and $60-$7F from the table in the additional SE data area ($2E94).
| Offset | Type | Contents |
|---|---|---|
| +$00 | byte | Number of sound effects registered in the table |
| +$02 | ushort[] | Start address of each sound effect’s sequence (in the additional SE data area, indexed by sound effect number - $60) |
If a number equal to or greater than the registered count is specified, it is treated as sound effect number $00.
A sound effect is played on SE channel n+8, which corresponds to the BGM channel n specified by the CPU. Sound effect sequences have the same format as BGM and can use the same commands.
When a sound effect starts, the SE channel volume is initialized to $7F for both left and right, and the ADSR to ADSR1 = $8E, ADSR2 = $E0. While the sound effect is playing, BGM channel n continues only processing its sequence and does not write to the DSP.
Events
A sequence is a series of events. The first byte of an event determines its type.
| First byte | Type |
|---|---|
| 0x00-0x32 | Command. The number of parameters is fixed for each command |
| 0x80 | Rest |
| 0x81-0xFF | Note |
Commands take no time to process, and the following event is read within the same tick. Time advances only with note events and rest events. Therefore, creating an infinite loop that contains no notes or rests will stall the driver.
Executing 0x33-0x7F or an undefined command jumps outside the range of the command handler table or to an invalid address, and the driver runs out of control.
Note lengths
The lengths of note events and rest events are specified in ticks. There are three modes for specifying lengths, switched per channel.
| Mode | Length specification | Switching commands |
|---|---|---|
| Normal | 1 byte in each event | - |
| Default duration | Not specified in each event; the length set by command 0x06 is used | 0x06, 0x07 |
| 16-bit duration | 2 bytes in each event (big-endian) | 0x2B, 0x2C |
If default duration mode and 16-bit duration mode are enabled at the same time, the argument of command 0x06 becomes 2 bytes, and no length is specified in each event.
Below is an example of the same content written in the three modes.
// Normal
A5 10 A7 08 A9 08 AA 08 B1 10 00
// Default duration
A5 10 06 08 A7 A9 AA 07 B1 10 00
// 16-bit duration
2B A5 00 10 A7 00 08 A9 00 08 AA 00 08 B1 00 10 00
Tempo and ticks
The driver runs on the timer 0 period. The timer 0 divider is fixed at 100 (80Hz, 12.5ms period).
On each timer period, the BGM and SE tempos are each added to their tempo accumulators as 8-bit values, and the sequence on the side that overflowed advances by 1 tick.
Therefore, the number of ticks per second is 80 × tempo / 256. For example, if a quarter note is 16 ticks, the tempo (BPM) is about 1.17 × tempo.
Time unit of effects
The times (delays and intervals) of pitch bend and vibrato are counted in timer periods, not in tempo. Therefore, changing the tempo does not change the speed of effects.
Subroutines
Subroutines are called with command 0x04 and 0x21, and return with command 0x05. The call stack is 8 levels deep per channel, and the depth is not checked.
Use command 0x03 to loop a track.
Processing flow
On each timer period, the following processing is performed for BGM channels 0-7.
- If a BGM tick has occurred, decrement the remaining tick count by 1, and if it reaches 0, read an event. Commands are read one after another, stopping at a note event or rest event.
- Process effects (pitch bend, vibrato).
- If a sound effect is playing on the corresponding SE channel, perform the same processing for the SE tick.