Direct Sound Control Functions


Functions
sample_info *	ham_InitSample (u8 *data, u32 length, u16 bitrate)
	Initialize a Waveform Sample for playback.
void	ham_ChangeSampleBitrate (sample_info *sample, u16 bitrate)
	Changes the Playback Rate (playing speed) of a sample.
void	ham_DeInitSample (sample_info *sample)
	Removes an initialized sample from memory.
void	ham_PlaySample (sample_info *sample)
	Starts playback of an initialized Sample.
void	ham_KillSample (sample_info *sample)
	Force End of Output for a Sample.
void	ham_InitMixer (u16 bitrate)
	Initialize the HAM Direct sound mixer.
void	ham_DeInitMixer ()
	Deinitialize the HAM Direct sound mixer.
void	ham_SyncMixer ()
	Synchronize the Mixer with the GBA hardware.
void	ham_UpdateMixer ()
	Update and mix all channels for next frame.

Detailed Description

In this section, you will find HAMs internal Direct Sound functions. IMPORTANT: These functions are deprecated and are only provided in future version for backward compatiblity. It is suggested that you use Krawall (see the Glossary ) for all Direct Sound functionality. Krawall (freeware version) is included in all HAM versions >2.52 . For details on how to register Krawall (to get XM playback support and other advanced features, see http://mind.riot.org )

Function Documentation

void ham_ChangeSampleBitrate ( sample_info * sample,

u16 bitrate

)

Changes the Playback Rate (playing speed) of a sample.

Parameters:

sample a pointer to a sample_info structure previously obtained by ham_InitSample()

bitrate the desired playback bitrate of the sample in Hz (bytes/sec)

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
This function will change the current bítrate of the sample in question to the new value given (in Hz)
See also: ham_InitMixer() ham_InitSample()

void ham_DeInitMixer ( )

Deinitialize the HAM Direct sound mixer.

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
Deinitializes HAM Direct Sound functionality. This is the function you should call after you are done with using the HAM direct sound audio functions.
See also: ham_InitMixer()

void ham_DeInitSample ( sample_info * sample )

Removes an initialized sample from memory.

Parameters:

sample a pointer to a sample_info structure previously obtained by ham_InitSample()

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
This function deinitalizes the sample supplied. This will not delete the samples data itslef, but all the configuration data that was previously created by ham_InitSample()
See also: ham_InitSample()

void ham_InitMixer ( u16 bitrate )

Initialize the HAM Direct sound mixer.

Parameters:

bitrate The bitrate of the mixer in Hz (see below)

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
Initializes the HAM Direct Sound mixer. To ensure click less playback, set your Mixer to a frequency outlined below. Other frequencies might play back fine, but these are safer to use, the ones above fit the timing of the GBA best. After you Initialized your Mixer, you must call ham_SyncMixer() in your VBL handler, at the very top, and also ham_UpdateMixer() once per frame, where does not matter. See the example sources included with HAM for more information.
You are advised to use one of the following bitrates for your mixer (You can play any bitrate samples up to the mixer frequency itself, but using a higher mixer bitrate will require more CPU power):

5733 Hz
6689 Hz
10512 Hz
11467 Hz
13379 Hz
18157 Hz
20068 Hz
21024 Hz
26757 Hz
31536 Hz
36314 Hz
40136 Hz
42048 Hz
54471 Hz
See also: ham_InitSample() ham_PlaySample() ham_DeInitMixer()

sample_info* ham_InitSample ( u8 * data,

u32 length,

u16 bitrate

)

Initialize a Waveform Sample for playback.

Parameters:

data a pointer to the data of the sample you want to initialize

length the length of the sample in bytes

bitrate the desired playback bitrate of the sample in Hz (bytes/sec)

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
This function will initialize an 8bit Waveform for playback within the HAM Direct Sound system. It will return a pointer to a so-called sample_info structure. This pointer can later be used to start playbeck of this sample.
See also: ham_InitMixer() ham_PlaySample() ham_DeInitSample()

void ham_KillSample ( sample_info * sample )

Force End of Output for a Sample.

Parameters:

sample a pointer to a sample_info structure previously obtained by ham_InitSample()

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
This function will force the playback of the supplied sample to end immediately. Caution: this function is not 100% tested.
See also: ham_InitSample() ham_DeInitSample()

void ham_PlaySample ( sample_info * sample )

Starts playback of an initialized Sample.

Parameters:

sample a pointer to a sample_info structure previously obtained by ham_InitSample()

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
This function starts the Playback of the sample specified. Note that you can play more than one sample simultaneously, so you can start playback of a sample while another one is still playing.
See also: ham_InitSample() ham_DeInitSample()

void ham_SyncMixer ( )

Synchronize the Mixer with the GBA hardware.

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
After you initialized your Mixer, you must call this function at the start of each VBL. This function transmits one frame worth of sound data from the mixer to the GBA sound circuit. You can set up a VBL interrupt handler using ham_StartIntHandler() . The call to this function should be the first thing you do in the VBL handler function. See the dsound1 example source code for more information.
See also: ham_InitMixer()

void ham_UpdateMixer ( )

Update and mix all channels for next frame.

Warning:
this function is deprecated in favour of Krawall audio. See Krawall Notes for more information.
Use this function to mix new sound data once per frame, which will get played on the next call to ham_SyncMixer() . You must invoke this function once per frame, where does not really matter, as long as the function will be done before the next call to ham_SyncMixer() .
See also: ham_InitMixer() ham_SyncMixer()

Documentation Homepage | HAMLib reference | Back to HAM Homepage

documentation created with Doxygen