Soundlib Version 0.1

soundlib Version 0.1

By Derek Nedelman
Released October 4, 2002
Home Page: http://www.playstation2-linux.com/projects/soundlib

Table Of Contents

About

Using

IMPORTANT Things To Know

General Sound Tips

Limitations

Sample Programs

•	32_sounds
•	instances
•	left_right
•	frequency
•	callback
•	callbacks
•	3d
•	sound_play

Release History

Reference

Functions

Initialization/Shutdown

•	soundlib_initialize
•	soundlib_shutdown

Updating

•

soundlib_update

Devices

•	soundlib_get_block_size
•	soundlib_get_num_outputs
•	soundlib_get_output_volume_step_size
•	soundlib_set_output_volume
•	soundlib_set_output_callback

Sounds

Creation/Destruction

•	soundlib_create_sound_from_file
•	soundlib_create_sound_from_memory
•	soundlib_create_sound_from_callback
•	soundlib_create_sound_instance
•	soundlib_destroy_sound
•	soundlib_destroy_all_sounds

Play

•	soundlib_play_sound
•	soundlib_stop_sound

Volume

•	soundlib_get_sound_volume_step_size
•	soundlib_set_sound_volumes
•	soundlib_set_sound_left_volume
•	soundlib_set_sound_right_volume

Playback Rate

•	soundlib_set_sound_frequency
•	soundlib_restore_sound_frequency

•	soundlib_enable_3d_sound
•	soundlib_set_3d_sound_position
•	soundlib_set_3d_sound_min_max_volume
•	soundlib_set_3d_sound_min_max_distance

Miscellaneous

•

soundlib_set_sound_callback

Listener

•	soundlib_set_listener
•	soundlib_set_listener_position
•	soundlib_set_listener_orientation

Utility

Sound Buffer

•	soundlib_open_sound_buffer_from_file
•	soundlib_open_sound_buffer_from_memory
•	soundlib_close_sound_buffer
•	soundlib_load_sound_buffer
•	soundlib_get_sound_buffer_bytes

Miscellaneous

•

soundlib_mix_buffers

Structures

•

soundlib_sound_buffer_t

About

This library provides a set of functions that allow for mixing and output of sound on the Playstation 2 Linux platform. Among the features provided by this library are:

•	Built-in support for (uncompressed) WAV, MP3, and OGG sound formats.
•	Streaming from memory (for higher performance) or disk (for reduced memory usage).
•	User-defined "callback" sounds.
•	Hooks for post-processing on individual sounds as well as device buffers.
•	3D sound processing.
•	Changeable volume and playback rate for sounds.
•	8 sample programs demonstrating features of the library.
•	And more.....

Using

•

soundlib is written in C and compiles under Playstation 2 Linux with the standard C or C++ compiler.

•

The library itself is entirely self contained within soundlib.c and soundlib.h. soundlib.c can be compiled and linked in with your project like any file you write yourself.

•

To enable MP3 support, you must:

1)	Compile and install the MAD library, if you haven't done so already.
2)	Near the top of soundlib.h there is #define SOUND_ENABLE_MP3. Define SOUND_ENABLE_MP3 to be 1.
3)	Link with mad by adding -lmad to your compile options.

Please be aware that by enabling MP3 support in your program you will have to follow MAD's licensing terms. It is distributed under the General Public License. See the MAD website for more details.

•

To enable Ogg support, you must:

1)	Compile and install the Ogg Vorgis Tremor library, if you haven't done so already. Here is a more direct link to what you need. You will need to get the tremor_cvs_snapshot.tgz file. Do NOT use the precompiled Playstation 2 Linux binaries that are available elsewhere on the Vorbis site. They are for the "standard" Vorbis decoder which is very slow and has a slightly different API than the much faster "Tremor" library.
2)	Near the top of soundlib.h there is #define SOUND_ENABLE_OGG. Define SOUND_ENABLE_OGG to be 1.
3)	Link with Tremor by adding -lvorbisidec to your compile options.

•

If you wish to disable all sound processing to see how much faster your program runs without sound, simply don't call soundlib_update. Otherwise, if you want sound, you MUST call soundlib_update periodically within your program to hear sound. See the sample programs for some examples.

IMPORTANT Things To Know

1)	Read all the documentation before using this library for the first time. Even though the interface provided by this library isn't very large, there are a lot of subtleties to be aware of.
2)	All sound sources must be 16-bit, 48000 Hz. Sounds of any other quality may sound noisy, may play too fast or slow, or even worse, may cause your program to crash.
3)	Sounds may have either 1 or 2 channels. Sounds with 1 channel are created as 3D sounds, while sounds with 2 channels are created as 2D sounds.
4)	Streaming sounds (MP3, OGG, streaming WAV, and callback sounds) can't have their play frequencies changed.
5)	Instances of streaming sounds always play at the same position of the original sound. This means that if, for example, there is an instance of a streaming sound, both sounds (the instance and the original) will be playing the exact same sound data, though at perhaps different volume levels.
6)	Destroying a sound that has instances destroys all instances of that sound as well.
7)	This library is written on top of the Linux sound system (OSS), but that doesn't make it generally portable to other systems. The endianness, reliance on two sound devices (/dev/dsp and /dev/dsp1), and assumptions made in various mixing and resampling routines would most likely cause something to break on any platform other than Playstation 2 Linux.
8)	soundlib_update MUST be called often if you wish to hear sound. In the current implementation, this amounts to about 47 times per second. The frequency that soundlib_update must be called can be modified by changing the SOUND_FRAGMENT_SIZE_LOG_2 constant in the "defines" section of soundlib.c. Increasing this value by 1 doubles the sound buffer size, which also doubles the sound latency, but has the effect of requiring fewer calls per second to soundlib_update. By the way, there is no harm in calling soundlib_update TOO often.
9)	All the sound functions that allow you to set a volume take a floating point parameter in the range [0, 1]. 0 indicates no sound while 1 indicates the full volume of the sound, that is, the original volume level of the sound. There is no facility for amplifying sound levels.

General Sound Tips

•

The 3D routines tend to make the sounds a little quieter than they would normally be. It may be necessary to amplify these sounds ahead of time in a sound editing program such as Sound Forge before using them with this library.

Limitations

•	Unlike most sound libraries, this one is not multithreaded. It must be notified of when to perform its processing with periodic calls to soundlib_update. The advantage of this, however, is better performance since the library doesn't need to do any thread synchronization.
•	Because of restrictions with the Playstation 2 Linux kit, this sound library does all of its mixing on the main CPU. Be aware of this when playing a lot of sounds. Each one has a cost.
•	Everything works fine when valid filenames/types are passed into the create_sound functions. If an invalid filename or file type is passed in, the library may cause a memory leak, or worse, a segmentation fault. This will be addressed shortly. In the meantime, make sure all of the files passed in truly exist, and that they are of types that are supported. If using an MP3 or OGG file, make sure you've enabled support for those formats. See Using for details on how to enable support for those formats.
•	The 3D calculations used by the library are very simple. They amount to no more than modifying intensity of the sounds' left/right volumes (these are not the same as the volumes set by soundlib_set_sound_volumes) based on their position relative to the listener. There is no pitch shifting applied, which is why there is no way to set the velocity of either the 3D sound or the listener.

Release History

October 4, 2002

First release.

-Support for WAV, MP3, and OGG formats.
-Normal, streaming, and callback sound types supported.
-Simple 3D functions provided.
-Hooks for sound callbacks and output callbacks provided.
-Utility functions for loading WAV files and mixing sounds provided, though not needed to use the core library effectively.
-8 sample programs to demonstrate library features.

Sample Programs

•

32_sounds

	Description: Loads and plays 32 sounds simultaneously.
	To compile: make main_32_sounds
	To run: ./main_32_sounds

•

instances

	Description: Loads 1 sound, creates 31 instances of it, and then plays all 32 sounds simultaneously.
	To compile: make main_instances
	To run: ./main_instances

•

left_right

	Description: Loads a sound (the phrase "left....right" coming out of the left and right speakers, respectively) and allows the left and right volumes to be modified with the sticks on the joypad.
	To compile: make main_left_right
	To run: ./main_left_right

•

frequency

	Description: Loads a sound and allows the playback frequency to be modified with the left stick on the joypad..
	To compile: make main_frequency
	To run: ./main_frequency

•

callback

	Description: Creates a callback-type sound and stitches together 5 sounds during play to create the impression of a single sound.
	To compile: make main_callback
	To run: ./main_callback

•

callbacks

	Description: Loads a sound and plays it, demonstrating the use of the callbacks to perform processing on the sound at various points during play.
	To compile: make main_callbacks
	To run: ./main_callbacks

•

	Description: Loads a sound and positions it in 3D space, allowing the user to move around the sound with the left stick.
	To compile: make main_3d
	To run: ./main_3d

•

sound_play

	Description: Plays the sound file specified on the command line. Can play WAV, MP3 and OGG files. The files should conform to the restrictions of this library. That is, they should be stereo, 16-bits per sample, 48000 Hz.
	To compile: Your compile environment and the soundlib.h file should be set to work with the OGG and MP3 format. See Using for details. Once they are set up... make main_sound_play
	To run: ./main_sound_play (filename)

Reference

Functions

Initialization/Shutdown

int soundlib_initialize(
     int max_sounds,
     void* (*buffer_malloc)(int num_bytes, void* user_data),
     void (*buffer_free)(void* bytes, void* user_data),
     void* malloc_user_data);

Parameters

max_sounds

[in]The maximum number of sounds to allow to be created. 32 is a good number, though there's nothing wrong with passing in 57 or 213 (or any other weird number). There is, however, a problem with playing 213 sounds at the same time since not only is that a lot of sound (it would probably sound terrible) but it will cause a large performance hit on the main program. If passing in a large number such as this you must make sure, as much as possible, that as few sounds are playing at any given time.

buffer_malloc

[in]Pointer to a function that will be used to allocate memory for buffers used by newly created sounds. An example function might look like this:
  void* my_malloc(int num_bytes, void* user_data)
  {
    void* memory = malloc(num_bytes);
    return memory;
  }
Instead of a pointer to a function, NULL may be passed in, in which case the library's default memory allocator (which looks just like the one above) is used.

When using MP3 or OGG files, this custom memory allocation scheme is subverted somewhat by libmad's and vorbis's internal memory allocation schemes.

buffer_free

[in]Pointer to a function that will be used to free memory used by newly destroyed sounds. An example function might look like this:
  void my_free(void* memory, void* user_data)
  {
    free(memory);
  }
Instead of a pointer to a function, NULL may be passed in. If NULL was passed in for buffer_malloc the library's default memory allocator (which looks just like the one above) is used. Otherwise, if you passed in a non-NULL value for buffer_malloc and a NULL value for buffer_free it's assumed that you really know what you doing with the memory allocation/deallocation.

user_data

[in]Pointer to user-defined data that is passed into both buffer_malloc and buffer_free.

Return Values

If the initialization succeeds, 1 is returned. Otherwise, some error occurred and 0 is returned.

Remarks

Call this function before calling any other function in the library - most likely when the program begins.

See Also

soundlib_shutdown

void soundlib_shutdown(void);

Remarks

Call this function when finished with the library - most likely right before the program terminates.

See Also

soundlib_initialize

Updating

void soundlib_update(void);

Remarks

Call this function often to update the state of the sound library. Updating the state of the sound library amounts to extracting sound from all of the playing sounds and mixing them together, finally placing the mixed sound into an output device buffer. If no output device buffer is free for the time being, this function returns quickly.

This function should be called often. In a game, it would be called within the main game loop.

To disable the playing of sound - to test a program's performance without sound, for example - simply do not call soundlib_update.

Devices

int soundlib_get_block_size(void);

Return Values

Returns the internal size, in bytes, of data blocks streamed to the sound devices.

Remarks

This function may be of use when initializing custom sound callbacks that need to allocate a few buffers for effects processing, among other things.

int soundlib_get_num_outputs(void);

Return Values

Returns the number of output devices available for the caller to use.

Remarks

Each output represents an output buffer that a sound can be played into. This function returns the number of such outputs available. Right now, the library parallels the Playstation 2 hardware and always returns 2.

See Also

soundlib_get_block_size, soundlib_get_output_volume_step_size

float soundlib_get_output_volume_step_size(void);

Return Values

Returns the difference, or step size, between volume levels on the output devices.

Remarks

The step size is the granularity of the volume adjustments that will correspond to some meaningful change in the volume level on the output device. This is useful because all of the volume functions use a float in the range of [0, 1] for volume values. Making a change that is less than soundlib_get_output_volume_step_size() will not result in a volume change. Note also that just because a meaningful change has been made to the volume level, that doesn't mean your ear will actually be able to detect that change.

This function is not to be confused with soundlib_get_sound_volume_step_size which returns the granularity of the volume levels for sounds.

void soundlib_set_output_volume(
int device,
float volume);

Parameters

device

[in]Index of the device to set the callback on. The valid range is 0 - (soundlib_get_num_outputs() - 1).

volume

[in]Volume level to set on the device. The valid range is [0, 1].

Remarks

This function allows an application to do processing on an output buffer just before it's actually played. This may be useful if you wish to simulate an echo or some other effect.

See Also

soundlib_get_output_volume_step_size

void soundlib_set_output_callback(
     int device,
     int callback,
     void (*callback_function)(int callback_id, char* buffer, int num_bytes, void* user_data),
     void* user_data);

Parameters

device

[in]Index of the device to set the callback on. The valid range is 0 - (soundlib_get_num_outputs() - 1).

callback

[in]Identifier of the callback to set. Valid values are:

SOUND_OUTPUT_CALLBACK_EFFECT

Sets the 'effect' callback. This callback will receive the mixed sound buffer just before it's about to played on the sound device.

callback_function

[in]Pointer to a function that will called at the appropriate time. An example function might look like this:
  void callback_function(int callback_id, char* buffer, int num_bytes, void* user_data)
  {
    switch (callback_id)
    {
      case SOUND_OUTPUT_CALLBACK_EFFECT:
    {
        //Do something to the sound data in buffer
        break;
      }
    }
  }

Instead of a pointer to a function, NULL may be passed in to clear the current callback.

user_data

[in]Pointer to user-defined data that is passed into callback_function.

Remarks

This function allows an application to do processing on an output buffer just before it's actually played. This may be useful if you wish to simulate an echo or some other effect.

Sounds

Creation/Destruction

int soundlib_create_sound_from_file(
     const char* file,
     int is_streaming,
     int force_into_memory);

Parameters

file

[in]Name of the sound file. Supported file types are WAV, OGG, and MP3.

is_streaming

[in]Whether or not to stream the sound. If the sound file specified by file is either an OGG or MP3 file, this parameter has no effect since those types are always streamed. So, at the moment, this parameter is only used when file refers to a WAV file, in which case the following values for is_streaming apply:

0

The WAV file is loaded entirely into memory. This should be the normal case for small sounds, such as screams, gunfire, explosions, etc. Not only is this the fastest option, but it provides more flexibility when instantiating the sound. See soundlib_create_sound_instance for more details.

The WAV file is streamed from disk. This should only be used for music or other large WAV files.

force_into_memory

[in]Whether or not to stream the sound from memory instead of disk. This parameter only applies when streaming the sound. This occurs when the sound file specified by file is an OGG or MP3 file, or when it's a WAV file and is_streaming is 1.

0

The file is streamed from disk.

The file is loaded from disk into memory and is then streamed from memory. This option is most useful if the sound is going to be played while there is a large amount of disk usage.

Return Values

If the sound is successfully created, a sound index >= 0 is returned. Otherwise, -1 is returned.

Remarks

Use the returned sound index in subsequent sound function calls such as soundlib_play_sound or soundlib_destroy_sound.

The number of channels in the sound determines the type of sound it is. If it has 1 channel (mono) it's created as a 3D sound. If it has 2 channels (stereo) it's created as a 2D sound.

int soundlib_create_sound_from_memory(
     const void* memory,
     int num_bytes,
     int is_streaming);

Parameters

memory

[in]Pointer to memory that contains an entire sound file. This is read from like a file. In other words, the library keeps no reference to the memory after the call.

num_bytes

[in]Number of bytes pointed to by memory.

is_streaming

[in]Whether or not to stream the sound. If the sound file specified by memory is either an OGG or MP3 file, this parameter has no effect since those types are always streamed. So, at the moment, this parameter is only used when file refers to a WAV file, in which case the following values for is_streaming apply:

0

The WAV file is loaded entirely into memory.

The WAV file is streamed from memory. This is a bit of a strange option since you need to have a really good reason to want to stream a WAV file from memory. It's more restrictive than helpful. The only feature that streaming a WAV file from memory provides is that all instances of the sound will play at the same position. See soundlib_create_sound_instance for more details.

Return Values

If the sound is successfully created, a sound index >= 0 is returned. Otherwise, -1 is returned.

Remarks

int soundlib_create_sound_from_callback(
     int (*callback)(int message, void* ptr, int data, void* user_data),
     void* user_data,
     int num_channels);

Parameters

callback

[in]Pointer to function that will be used to update the state of the sound. An example function might look like this:

int my_sound_callback(int message, void* ptr, int data, void* user_data)
{
   switch (message)
   {
     case SOUND_CALLBACK_MSG_OPEN:
    {
       //The message is a notification that the sound was created.
       //The return value is ignored.
       break;
     }
     case SOUND_CALLBACK_MSG_CLOSE:
     {
       //The message is a notification that the sound is being destroyed.
       //The return value is ignored.
       break;
     }
     case SOUND_CALLBACK_MSG_READ:
     {
       //This message is a command to return sound data.
       //ptr points to the output buffer.
       //data indicates the number of bytes to return.
       //This function needn't return the requested number of bytes. If it doesn't
       //silence is filled in where necessary.
       //The return value is the number of bytes read.
       return num_bytes;
     }
     case SOUND_CALLBACK_MSG_SEEK:
     {
       //This message is a command to seek somewhere into the sound.
       //data indicates the offset from the beginning of the sound to seek to.
       //The return value is ignored.
       break;
     }
     case SOUND_CALLBACK_MSG_IS_EOS:
     {
       //This message is a command to determine whether or not the
       //sound has reached the end-of-stream (EOS).
       //Return 0 to indicate it hasn't reached the end.
       //Return 1 to indicate it has reached the end.
       //It's perfectly okay to always return 0. In this case, the sound will always be played.
       return 0;
     }
  }

return 0;
}

user_data

[in]Pointer to user-defined data that is passed into the callback function.

num_channels

[in]1 for mono, 2 for stereo. As usual, the number of channels indicates whether a 2D or 3D sound is created. 1 channel indicates a 3D sound, and 2 channels indicates a 2D sound.

Return Values

If the sound is successfully created, a sound index >= 0 is returned. Otherwise, -1 is returned.

Remarks

int soundlib_create_sound_instance(
int sound);

Parameters

sound

[in]Index of sound to instantiate.

Return Values

If the sound is successfully instantiated, a sound index >= 0 is returned. Otherwise, -1 is returned.

Remarks

Any sound can be instantiated, even other instances. When instancing and instance, though, the instance becomes a "child" of the original sound, not the one being instanced (the one passed in as the sound parameter).

When instantiating a sound, it's important to be aware of the relationship between a source sound and all its instances.

•	Destroying a sound destroys all instances of that sound. It's okay to call soundlib_destroy_sound with a sound that's already been destroyed.
•	Instances of streaming sounds (sounds created with soundlib_create_sound_from_callback are streaming sounds as well), all play at the same position (play position, not 3D position). For example, if a sound created from an OGG file is being played and then it's instantiated, playing the instance will be like playing the original sound twice as loud. This is pretty much pointless for 2D sounds, though it may be very useful for 3D sounds. The original sound would be a sort of radio station, and all the instances could be like radios tuned into the same station.
•	Only instances of non-streaming WAV files may play at different positions.
•	Instances inherit all the properties of the original sound including: play frequency, play position, looping flag, left and right volumes, all 3D sound data, and callbacks set with soundlib_set_sound_callback. The only property that isn't inherited is the play flag. So, when instancing a playing sound, the new sound won't be playing.

void soundlib_destroy_sound(
int sound);

Parameters

sound

[in]Index of sound to destroy.

Remarks

Destroys a sound.

void soundlib_destroy_all_sounds(void);

Remarks

Destroys all sounds.

See Also

soundlib_destroy_sound

Play

void soundlib_play_sound(
     int sound,
     int device,
     int is_looping,
     int play_offset);

Parameters

sound

[in]Index of sound to play.

device

[in]Index of device to play sound into.

is_looping

[in]0 to play the sound once. 1 to loop the sound.

play_offset

[in]Offset, in bytes, from beginning of sound where the playing should begin. If playing a streaming sound or an instance of a streaming sound, this parameter is ignored.

SOUND_PLAY_BEGINNING

The same as passing in 0. Plays the sound from the beginning.

SOUND_PLAY_CONTINUE

Plays the sound from where it left off from last time. If playing a sound for the first time, it plays from the beginning.

any other value > 0

Offset from beginning of sound where the playing should begin. For non-instances, this works for WAV sound sources, either streaming or non-streaming, and callback sources (the callback receives the SOUND_CALLBACK_MSG_SEEK command which it can choose to respond to). If playing an instance, it only works for instances of non-streaming WAV sources.

Remarks

Plays a sound.

See Also

soundlib_stop_sound

void soundlib_stop_sound(
int sound);

Parameters

sound

[in]Index of sound to stop.

Remarks

Stops a sound immediately.

See Also

soundlib_play_sound

Volume

float soundlib_get_sound_volume_step_size(void);

Return Values

Returns the difference, or step size, between volume levels for sounds.

Remarks

The step size is the granularity of the volume adjustments that will correspond to some meaningful change in the volume level on a sound. This is useful because all of the volume functions use a float in the range of [0, 1] for volume values. Making a change that is less than soundlib_get_sound_volume_step_size() will not result in a volume change. Note also that just because a meaningful change has been made to the volume level, that doesn't mean your ear will actually be able to detect that change.

This function is not to be confused with soundlib_get_output_volume_step_size which returns the granularity of the volume levels for output devices.

See Also

soundlib_set_sound_volume

void soundlib_set_sound_volume(
int sound,
float volume);

Parameters

sound

[in]Index of the sound on which to set the volume.

volume

[in]Volume level to set on the sound. The valid range is [0, 1]. Remember, a sound volume of 1 indicates full volume.

Remarks

Sounds have independent volume controls on the left and right channels. This function sets them identically.

Note that the volumes set by this function are always applied, even if the sound is a 3D sound. For best results, it's recommended that all 3D sounds have their volume levels set to 1.0. This is the default.

See Also

soundlib_get_sound_volume_step_size, soundlib_set_sound_volumes

void soundlib_set_sound_volumes(
     int sound,
     float left_volume,
     float right_volume);

Parameters

sound

[in]Index of the sound on which to set the volume.

left_volume

[in]Volume level to set on the left channel of the sound. The valid range is [0, 1]. Remember, a sound volume of 1 indicates full volume.

right_volume

[in]Volume level to set on the right channel of the sound. The valid range is [0, 1]. Remember, a sound volume of 1 indicates full volume.

Remarks

Sounds have independent volume controls on the left and right channels. This function allows them to be set independently.

Note that the volumes set by this function are always applied, even if the sound is a 3D sound. For best results, it's recommended that all 3D sounds have their volume levels set to 1.0. This is the default.

void soundlib_set_sound_left_volume(
int sound,
float volume);

Parameters

sound

[in]Index of the sound on which to set the volume.

volume

[in]Volume level to set on the left channel of the sound. The valid range is [0, 1].

Remarks

Sounds have independent volume controls on the left and right channels. This function sets only the left channel.

Note that the volumes set by this function are always applied, even if the sound is a 3D sound. For best results, it's recommended that all 3D sounds have their volume levels set to 1.0. This is the default.

See Also

soundlib_get_sound_volume_step_size, soundlib_set_sound_right_volume

void soundlib_set_sound_right_volume(
int sound,
float volume);

Parameters

sound

[in]Index of the sound on which to set the volume.

volume

[in]Volume level to set on the right channel of the sound. The valid range is [0, 1].

Remarks

Sounds have independent volume controls on the left and right channels. This function sets only the right channel.

Note that the volumes set by this function are always applied, even if the sound is a 3D sound. For best results, it's recommended that all 3D sounds have their volume levels set to 1.0. This is the default.

See Also

soundlib_get_sound_volume_step_size, soundlib_set_sound_left_volume

Playback Rate

void soundlib_set_sound_frequency(
int sound,
int samples_per_sec);

Parameters

sound

[in]Index of the sound on which to set the playback frequency.

samples_per_sec

[in]Playback frequency for the sound. Can be any value > 0.

Remarks

The playback rate can be modified on non-streaming WAV sounds and instances of non-streaming WAV sounds.

The resampling that occurs as a result of changing the playback frequency is expensive. The frequency should only be changed on sounds that absolutely require it, such as engine noises.

See Also

soundlib_restore_sound_frequency

void soundlib_restore_sound_frequency(
int sound);

Parameters

sound

[in]Index of the sound on which to restore the playback frequency.

Remarks

Restores the playback rate to its original value.

See Also

soundlib_set_sound_frequency

void soundlib_enable_3d_sound(
int sound,
int enable);

Parameters

sound

[in]Index of the sound on which to enable 3D sound.

enable

[in]1 to enable 3D processing on the sound. 0 to disable it. When disabled, the sound is output as a mono sound.

Remarks

The ability to disabled 3D processing on a sound is useful in many cases. For example, in a two-player splitscreen first person shooter, effects that would be played with 3D processing in single player mode might sound strange with two players. Additionally, disabling 3D processing reduces the amount of processing that must be done on the sound.

Calling this function on a 2D sound has no effect.

See Also

soundlib_create_sound_from_file, soundlib_create_sound_from_memory, soundlib_create_sound_from_callback

void soundlib_set_3d_sound_position(
int sound,
const float* pos);

Parameters

sound

[in]Index of the sound on which to set the 3D sound's position.

pos

[in]Pointer to an array of 3 floating point values indicating the world position of the sound.

Remarks

Sets the world position of a 3D sound.

Calling this function on a 2D sound has no effect.

void soundlib_set_3d_sound_min_max_volume(
     int sound,
     float min_volume,
     float max_volume);

Parameters

sound

[in]Index of the sound on which to set the 3D sound's volumes.

min_volume

[in]Volume level of the sound at the maximum distance from the listener. The valid range is [0, 1].

max_volume

[in]Volume level of the sound at the minimum distance from the listener. The valid range is [0, 1], though 1 is the most usual value for this parameter. Remember, a sound volume of 1 indicates full volume.

Remarks

Sets the minimum and maximum volume levels for a 3D sound. When the listener is less than the minimum distance away from the sound, the sound is played at max_volume. When the listener is greater than the maximum distance away from the sound, the sound is muted. When the listener is between the minimum and maximum distance, a linear interpolation of min_volume and max_volume is used.

See Also

soundlib_set_3d_sound_min_max_distance

void soundlib_set_3d_sound_min_max_distance(
     int sound,
     float min_distance,
     float max_distance);

Parameters

sound

[in]Index of the sound on which to set the 3D sound's distances.

min_distance

[in]The minimum distance from the listener where the sound can be heard at full volume. Should be >= 0.

max_distance

[in]The maximum distance after which the sound can't be heard. Should be > 0 and > min_distance.

Remarks

Sets the minimum and maximum distances for a 3D sound. When the listener is less than min_distance away from the sound, the sound is played at the maximum volume. When the listener is greater than the max_distance away from the sound, the sound is muted. When the listener is between the min_distance and max_distance, a linear interpolation the minimum and maximum volume levels is used.

See Also

soundlib_set_3d_sound_min_max_volume

Miscelleneous

void soundlib_set_sound_callback(
     int sound,
     int callback,
     int (*callback_function)(int sound, int callback_id, char* buffer, int num_bytes, void* user_data),
     void* user_data);

Parameters

sound

[in]Index of the sound on which to set the callback.

callback

[in]Identifier of the callback to set. Valid values are:

SOUND_CALLBACK_END

Sets the 'end' callback. This callback is called when the sound ends. If the sound is looping, it never ends. When receiving this callback, buffer and num_bytes aren't used.

SOUND_CALLBACK_EFFECT

Sets the 'effect' callback. This callback will receive the chunk of sound data that is just about to be mixed into the device buffer. When receiving this callback, buffer and num_bytes are used.

callback_function

[in]Pointer to a callback function, or NULL.

user_data

[in]Pointer to user-defined data that is passed to the callback.

Remarks

Callbacks are inherited by instances.

Listener

void soundlib_set_listener(
     const float* pos,
     const float* up,
     const float* forward);

Parameters

pos

[in]Pointer to an array of 3 floating point values indicating the world position of the listener.

[in]Pointer to an array of 3 floating point values indicating the up direction of the listener. If the listener were a person, up would be a vector pointing staight up out of the top of the person's head.

forward

[in]Pointer to an array of 3 floating point values indicating the forward direction of the listener. If the listener were a person, forward would be a vector pointing away from the person's face, staight through the their nose.

Remarks

Sets up the listener's position and orientation. This is essential when using 3D sounds. If there are no 3D sounds being used, this function needn't ever be called.

void soundlib_set_listener_position(
const float* pos);

Parameters

pos

[in]Pointer to an array of 3 floating point values indicating the world position of the listener.

Remarks

Sets up the listener's position. This is essential when using 3D sounds. If there are no 3D sounds being used, this function needn't ever be called.

Only use this function when there's no need to update the listener's orientation.

void soundlib_set_listener_orientation(
const float* up,
const float* forward);

Parameters

forward

Remarks

Sets up the listener's orientation. This is essential when using 3D sounds. If there are no 3D sounds being used, this function needn't ever be called.

Only use this function when there's no need to update the listener's position.

Utility

Sound Buffer

int soundlib_open_sound_buffer_from_file(
soundlib_sound_buffer_t* buffer,
const char* file);

Parameters

buffer

[out]Pointer to a soundlib_sound_buffer_t structure that will receive information about the file.

file

[in]Name of a sound file to open.

Return Value

1 if the file was successfully opened. 0 if the file couldn't be opened or the file isn't of the right format.

Remarks

Initializes the passed-in structure by opening up the sound file specified by file. Only WAV files are currently supported.

Upon successfully returning from this function, the num_bytes, num_channels, samples_per_sec, and bits_per_sample members of buffer will have been set. The caller must then allocate (probably with malloc() or some similar function) the data member of buffer to point to a region of memory at least num_bytes in length. After the allocation, the caller will then call soundlib_load_sound_buffer to load the sound file and then soundlib_close_sound_buffer_file to close the opened file. Then, because the caller allocated the memory, the caller is also is responsible for freeing the memory pointed to by the data member of buffer. So, an example of how to use soundlib_sound_buffer_t is this:

soundlib_sound_buffer_t buffer;
if (soundlib_open_sound_buffer_from_file(&buffer, "somefile.wav"))
{
  buffer.data = (char*)malloc(buffer.num_bytes);
  soundlib_load_sound_buffer(&buffer);
  soundlib_close_sound_buffer_file(&buffer);
}

.....the program executes

free(buffer.data);

int soundlib_open_sound_buffer_from_memory(
     soundlib_sound_buffer_t* buffer,
     const void* memory,
     int num_bytes);

Parameters

buffer

[out]Pointer to a soundlib_sound_buffer_t structure that will receive information about the file.

memory

[in]Pointer to memory that contains an entire sound file.

num_bytes

[in]Number of bytes pointed to by memory.

Return Value

1 if the file was successfully read. 0 if the file isn't of the right format.

Remarks

Initializes the passed-in structure by opening up the sound file specified by file. Only WAV files are currently supported.

Upon successfully returning from this function, the num_bytes, num_channels, samples_per_sec, and bits_per_sample members of buffer will have been set. The caller must then allocate (probably with malloc() or some similar function) the data member of buffer to point to a region of memory at least num_bytes in length. After the allocation, the caller will then call soundlib_load_sound_buffer to load the sound file and then soundlib_close_sound_buffer_file to close the opened file. Then, because the caller allocated the memory, the caller is also is responsible for freeing the memory pointed to by the data member of buffer. So, an example of how to use soundlib_sound_buffer_t is this:

soundlib_sound_buffer_t buffer;
if (soundlib_open_sound_buffer_from_memory(&buffer, some_memory_that_has_the_sound, num_bytes)
{
buffer.data = (char*)malloc(buffer.num_bytes);
soundlib_load_sound_buffer(&buffer);
}

.....the program executes

free(buffer.data);

See Also

soundlib_open_sound_buffer_from_file

void soundlib_close_sound_buffer_file(
soundlib_sound_buffer_t* buffer);

Parameters

buffer

[in]Pointer to a soundlib_sound_buffer_t structure that was previously opened.

Remarks

Closes the file that was opened for the sound buffer. There's no need - though there's no harm in doing so - to call this if the buffer was loaded from memory.

See Also

soundlib_open_sound_buffer_from_file

int soundlib_load_sound_buffer(
soundlib_sound_buffer_t* buffer);

Parameters

buffer

[out]Pointer to a soundlib_sound_buffer_t structure that was previously opened and has had memory allocated for its data member.

Return Value

1 if the data was successfully loaded, 0 if there was some error.

Remarks

Loads the sound from file or memory, depending on how the sound buffer was opened, into the data member.

int soundlib_get_sound_buffer_bytes(
     soundlib_sound_buffer_t* buffer,
     int offset,
     int num_bytes,
     void** bytes,
     void** bytes2);

Parameters

buffer

[in]Pointer to a soundlib_sound_buffer_t structure that has been loaded.

offset

[in]Offset, in bytes, from beginning of the sound data.

num_bytes

[in]Number of bytes of sound data to retrieve.

bytes

[out]Pointer to a pointer that receives the first memory address of the sound data.

bytes2

[out]Pointer to a pointer that receives second memory address of the sound data. May be NULL.

Return Value

The number of bytes pointed to by bytes. This may be less thant num_bytes if offset + num_bytes goes past the end of the sound buffer. 0 is returned in offset is past the end of the sound buffer.

Remarks

This function does something that your own application could just as easily do. It returns pointers to data within the sound buffer.

The pointer put into bytes, assuming num_bytes is less than the size of the sound buffer, is just &buffer.data[offset]. Then, assuming num_bytes + offset goes past the end of the sound data, bytes2, if non-NULL, is just &buffer.data[0]. The number of bytes in bytes2 can be derived from num_bytes - the return value.

See Also

soundlib_sound_buffer_t

Miscellaneous

void soundlib_mix_buffers(
     void* out,
     const void* a,
     const void* b,
     int num_bytes);

Parameters

out

[out]Pointer to a buffer to receive the result of mixing the a and b buffers.

[in]First buffer to mix. Should contain a 16-byte aligned aligned address that points to an array of short ints.

[in]Second buffer to mix. Should contain a 16-byte aligned aligned address that points to an array of short ints.

num_bytes

[in]Number of bytes in a, b, and out. This number should be divisible by 8.

Remarks

Mixes together buffers a and b, which presumably have sound data, and puts the results in out. a and/or b may be the same as out.

Structures

typedef struct {
    char* data;
    int num_bytes;
    int num_channels;
    int samples_per_sec;
    int bits_per_sample;
}soundlib_sound_buffer_t;

Members

data

Contains the sound data.

num_bytes

Number of bytes in data

num_channels

Number of channels in the sound data. 1 for mono, 2 for stereo.

samples_per_sec

Sound data sample rate. The number of samples per second.

bits_per_sample

Bits per sample. 8 or 16.

Remarks

The memory pointed to by the data member is not managed. It must be allocated and freed by the user.