HAM Documentation

Home · Downloads · Your Account · Submit News

Documentation Homepage HAMLib reference Back to HAM Homepage |

# 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