Files | Defines | Functions

Audio Subsystem
[libdragon]

Interface to the N64 audio hardware. More...

Files

file  audio.c
 

Audio Subsystem.


file  audio.h
 

Audio Subsystem.


Defines

#define TV_TYPE_LOC   0x80000300
 Memory location to read which determines the TV type.
#define NUM_BUFFERS   4
 Number of buffers the audio subsytem allocates and manages.
#define CALC_BUFFER(x)   ( ( ( ( x ) / 25 ) >> 3 ) << 3 )
 Macro that calculates the size of a buffer based on frequency.

Functions

void audio_init (const int frequency, int numbuffers)
 Initialize the audio subsystem.
void audio_close ()
 Close the audio subsystem.
void audio_write (const short *const buffer)
 Write a chunk of audio data.
void audio_write_silence ()
 Write a chunk of silence.
volatile int audio_can_write ()
 Return whether there is an empty buffer to write to.
int audio_get_frequency ()
 Return actual frequency of audio playback.
int audio_get_buffer_length ()
 Get the number of stereo samples that fit into an allocated buffer.

DAC rates for different regions



#define AI_NTSC_DACRATE   48681812
 NTSC DAC rate.
#define AI_PAL_DACRATE   49656530
 PAL DAC rate.
#define AI_MPAL_DACRATE   48628316
 MPAL DAC rate.

AI Status Register Values



#define AI_STATUS_BUSY   ( 1 << 30 )
 Bit representing that the AI is busy.
#define AI_STATUS_FULL   ( 1 << 31 )
 Bit representing that the AI is full.

Detailed Description

Interface to the N64 audio hardware.

The audio subsystem handles queueing up chunks of audio data for playback using the N64 audio DAC. The audio subsystem handles DMAing chunks of data to the audio DAC as well as audio callbacks when there is room for another chunk to be written. Buffer size is calculated automatically based on the requested audio frequency. The audio subsystem accomplishes this by interfacing with the audio interface (AI) registers.

Because the audio DAC is timed off of the master clock of the N64, the audio subsystem needs to know what region the N64 is from. This is due to the fact that the master clock is timed differently for PAL, NTSC and MPAL regions. This is handled automatically by the audio subsystem based on settings left by the bootloader.

Code attempting to output audio on the N64 should initialize the audio subsystem at the desired frequency and with the desired number of buffers using audio_init. More audio buffers allows for smaller chances of audio glitches but means that there will be more latency in sound output. When new data is available to be output, code should check to see if there is room in the output buffers using audio_can_write. Code can probe the current frequency and buffer size using audio_get_frequency and audio_get_buffer_length respectively. When there is additional room, code can add new data to the output buffers using audio_write. Be careful as this is a blocking operation, so if code doesn't check for adequate room first, this function will not return until there is room and the samples have been written. When all audio has been written, code should call audio_close to shut down the audio subsystem cleanly.


Define Documentation

#define CALC_BUFFER (   x  )     ( ( ( ( x ) / 25 ) >> 3 ) << 3 )

Macro that calculates the size of a buffer based on frequency.

Parameters:
[in] x Frequency the AI is running at
Returns:
The size of the buffer in bytes rounded to an 8 byte boundary
#define TV_TYPE_LOC   0x80000300

Memory location to read which determines the TV type.

Values read include 0 for PAL, 1 for NTSC and 2 for MPAL


Function Documentation

volatile int audio_can_write (  ) 

Return whether there is an empty buffer to write to.

This function will check to see if there are any buffers that are not full to write data to. If all buffers are full, wait until the AI has played back the next buffer in its queue and try writing again.

void audio_close (  ) 

Close the audio subsystem.

This function closes the audio system and cleans up any internal memory allocated by audio_init.

int audio_get_buffer_length (  ) 

Get the number of stereo samples that fit into an allocated buffer.

Note:
To get the number of bytes to allocate, multiply the return by 2 * sizeof( short )
Returns:
The number of stereo samples in an allocated buffer
int audio_get_frequency (  ) 

Return actual frequency of audio playback.

Returns:
Frequency in Hz of the audio playback
void audio_init ( const int  frequency,
int  numbuffers 
)

Initialize the audio subsystem.

This function will set up the AI to play at a given frequency and allocate a number of back buffers to write data to.

Note:
Before re-initializing the audio subsystem to a new playback frequency, remember to call audio_close.
Parameters:
[in] frequency The frequency in Hz to play back samples at
[in] numbuffers The number of buffers to allocate internally
void audio_write ( const short *const   buffer  ) 

Write a chunk of audio data.

This function takes a chunk of audio data and writes it to an internal buffer which will be played back by the audio system as soon as room becomes available in the AI. The buffer should contain stereo interleaved samples and be exactly audio_get_buffer_length stereo samples long.

Note:
This function will block until there is room to write an audio sample. If you do not want to block, check to see if there is room by calling audio_can_write.
Parameters:
[in] buffer Buffer containing stereo samples to be played
void audio_write_silence (  ) 

Write a chunk of silence.

This function will write silence to be played back by the audio system. It writes exactly audio_get_buffer_length stereo samples.

Note:
This function will block until there is room to write an audio sample. If you do not want to block, check to see if there is room by calling audio_can_write.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines