====== audio_coprocessor.h ======

audio_coprocessor.h provides functions for interacting with the Audio Coprocessor, usually abbreviated as "ACP". It also allows for communication with the accompanying Audio Firmware given in "audio_fw.asm".

The current audio firmware uses a Frequency Modulation technique to produce sound. Working with these parameters directly requires a bit of really involved theory to be covered which is outside the scope of this page. For the most part developers can use functions from music.h to play music and sound effects; only needing init_audio_coprocessor from this page.

===== Functions =====

==== init_audio_coprocessor ====
<code C>
void init_audio_coprocessor();
</code>

Stops the audio coprocessor, copies the firmware binary into its RAM, starts it, and triggers a reset. Call this before any other audio or music code.

==== push_audio_param ====
<code C>
void push_audio_param(char param, char value);
</code>

Pushes a bufferd value to a particular audio parameter. Values sent with push_audio_param don't take effect until flush_audio_params is called. see below for value of "param"

==== flush_audio_params ====
<code C>
void flush_audio_params();
</code>

Alert the ACP to copy the buffered parameters to active use.

==== set_audio_param ====
<code C>
#define set_audio_param(param,value) aram[param]=value
</code>
Skips the buffer and sets the parameter immediately. Use this if speed is more important than accuracy.


===== Audio Params =====
<code C>
#define FEEDBACK_AMT 0x04

#define PITCH_MSB 0x10

#define PITCH_LSB 0x20

#define AMPLITUDE 0x30
</code>

These macros give the base addresses of audio parameters. The FM-based audio firmware has 16 operators across four channels. Parameters for an operator can be accessed by adding its value to the macro address. For instance:
<code C>
set_audio_param(PITCH_MSB+4, 0x02);
</code>
This sets the high byte of the frequency parameter for Operator 4, which is operator 0 of Channel 1.

FEEDBACK_AMT is per-channel so has only four entries, but PITCH_MSB, PITCH_LSB, and AMPLITUDE are per-operator having 16 entries.

==== Param values ====

=== Pitch ===

<code C>
extern char pitch_table[216];
</code>

The pitch table is an array of bytes that roughly translate MIDI note numbers to byte values to use with PITCH_MSB and PITCH_LSB. For midi note N, the MSB should be set to pitch_table[2N] and the LSB should be set to pitch_table[2N+1].


=== Amplitude ===

The value for AMPLITUDE is actually the high byte of a pointer to a sine lookup table.

What??

The FM audio firmware generates sine waves by referring to a lookup table, and it can change which table it checks to change the amplitude of the wave. It has eight different sine tables, and since each one is 256 bytes long only the high byte of the pointer to that table has to be changed.

AMPLITUDE should be set like this

<code C>
set_audio_param(AMPLITUDE+op, sine_offset+n);
</code>
Where "op" is the operator number and "n" is a number from 0 through 8, where 7 is full volume and 8 is double full volume. (Which is only really useful for the first 3 "phasing" operators per channel, not the last "emitter" operator that contributes to the output waveform.)