Declaring Sounds

Before you can play a sample array, you must AHI_LoadSound() it. Why? Because if AHI knows what kind of sounds that will be played later, tables and stuff can be set up in advance. Some drivers may even upload the samples to the sound cards local RAM and play all samples from there, drastically reducing CPU and bus load.

You should AHI_LoadSound() the most important sounds first, since the sound cards RAM may not be large enough to hold all your sounds.

AHI_LoadSound() also associates each sound or sample array with a number, which is later used to refer to that particular sound.

There are 2 types of sounds, namely AHIST_SAMPLE and AHIST_DYNAMICSAMPLE.

AHIST_SAMPLE

This is used for static samples. Most sounds that will be played are of this type. Once the samples has been "loaded", you may not alter the memory where the samples are located. You may, however, read from it.

AHIST_DYNAMICSAMPLE

If you wish to play samples that you calculate in realtime, or load in portions from disk, you must use this type. These samples will never be uploaded to a sound cards local RAM, but always played from the normal memory. There is a catch, however. Because of the fact that the sound is mixed in chunks, you must have a certain number of samples in memory before you start a sound of this type. To calculate the size of the buffer (in samples), use the following formula:

@math{size = samples * Fs / Fm}

where samples is the value returned from AHI_GetAudioAttrsA() when called with the AHIDB_MaxPlaySamples tag, Fs is the highest frequency the sound will be played at and Fm is the actual mixing frequency (AHI_ControlAudioA()/AHIC_MixFreq_Query).

The samples can be in one of four different formats, named AHIST_M8S, AHIST_S8S, AHIST_M16S, and AHIST_S16S.

AHIST_M8S

This is an 8 bit mono sound. Each sample frame is just one signed byte.

AHIST_S8S

This is an 8 bit stereo sound. Each sample frame is one signed byte representing the left channel, followed by another one for the right channel.

AHIST_M16S

This is a 16 bit mono sound. Each sample frame is just one signed 16 bit word, in big endian/network order format (most significant byte first).

AHIST_S16S

This is a 16 bit stereo sound. Each sample frame is one signed 16 bit word, in big endian/network order format (most significant byte first) representing the left channel, followed by another one for the right channel.

If you know that you won't use a sound anymore, call AHI_UnloadSound(). AHI_FreeAudio() will also do that for you for any sounds left when called.

There is no need to place a sample array in Chip memory, but it must not be swapped out! Allocate your sample memory with the MEMF_PUBLIC flag set. If you wish to have your samples in virtual memory, you have to write a double-buffer routine that copies a chunk of memory to a MEMF_PUBLIC buffer. The SoundFunc should signal a task to do the transfer, since it may run in supervisor mode (see AHI_AllocAudioA()).

Go to the first, previous, next, last section, table of contents.