Skip to content

darnit_sound.h

Jump to bottom Edit New page
Steven Arnow edited this page Jul 13, 2013 · 10 revisions

DARNIT_SOUND

A handle to a loaded sound resource. This would be either streamed from disk, or preloaded and rendrered to raw pcm data before playback, which is chosen when the resource is loaded. The latter option is recommended for sound effects where latency matters. Please note that there's a limited, hardcoded amount of playback channels. In the current version (v.0.2 beta,) this is set to 16.

DARNIT_AUDIO_MODE

Sets the playback mode when loading an audio resource.

typedef enum {
        DARNIT_AUDIO_PRELOAD = 0,
        DARNIT_AUDIO_STREAM = 1,
} DARNIT_AUDIO_MODE;

If set to preload, the entire sound file is loaded and rendered to raw PCM into RAM (this uses ca. 172 kB per second of audio for stereo sound, or half that for mono.) Use this for sound effects, as latency matters more than memory usage, but don't use it for music.

DARNIT_AUDIO_CHANNELS

Selects the number of channels to use for playback. This does not make a difference on the amount of playback slots it uses.

typedef enum {
        DARNIT_AUDIO_MONO = 1,
        DARNIT_AUDIO_STEREO = 2,
} DARNIT_AUDIO_CHANNELS;

If stereo is selected for a mono file or vice versa, the audio stream is converted to the desired channel count. If the file is streamed from disk, this will add some overhead when going from stereo->mono, but not when going from mono->sterero, as duplicating a channel is faster than decoding one.

d_sound_tracked_load

DARNIT_SOUND *d_sound_tracked_load(const char *fname, DARNIT_AUDIO_MODE mode, DARNIT_AUDIO_CHANNELS channels);

Loads a sound resource with libmodplug. libmodplug supports pretty much all tracked music formats using samples. Tracked music "streamed" from disk is the only way to automatically loop music in libdarnit at the moment.

Arguments

  • fname - File name of the file to load
  • mode - Whether to load and render the file into RAM or not. For tracked music, you should stream it.
  • channels - Whether or not to use stereo sound playback

Return value

Returns NULL on failure. Everything else is a valid DARNIT_SOUND

d_sound_streamed_load

DARNIT_SOUND *d_sound_streamed_load(const char *fname, DARNIT_AUDIO_MODE mode, DARNIT_AUDIO_CHANNELS channels);

Loads a sound resource with stb_vorbis. Only OGG/Vorbis files are supported.

Arguments

  • fname - File name of the file to load
  • mode - Whether to load and render the file into RAM or not.
  • channels - Whether or not to use stereo sound playback

Return value

Returns NULL on failure. Everything else is a valid DARNIT_SOUND

d_sound_callback_load

If you need to use your own sound synthesiser or playback code with libdarnit, but still want to use libdarnit's mixer, you can define a callback that fills a buffer provided by libdarnit.

Arguments

  • callback - The callback function to call when audio samples are needed. It should return the number of bytes written (if not equal to buff_len, end of stream is assumed.)
  • buff - The audio buffer you need to fill with data
  • buff_len - The length of the buffer in bytes
  • pos - The number of sound frames that has previously been decoded
  • data - The pointer data that you provided
  • data - A pointer that is passed on to the callback, without being touched by libdarnit
  • channels - The number of channels the callback generates audio for

Return value

Returns NULL on failure. Anything else is a valid DARNIT_SOUND.

d_sound_unload

DARNIT_SOUND *d_sound_unload(DARNIT_SOUND *sound_resource);

Unloads a DARNIT_SOUND resource and frees up the resources used. Unloading a resource while it's used by a playback channel will cause undefined behaviour (but most likely a segfault or memory corruption.)

Arguments

  • sound_resource - The sound resource to unload

Return value

Returns NULL for compact pointer clearing.

d_sound_stop_all

void d_sound_stop_all();

Stops all sound playback.

Arguments None.

Return value None.

d_sound_stop

void d_sound_stop(int playback_key);

Stops playback on the specified playback channel

Argument

  • playback_key - The value returned when you started playback

Return value None.

d_sound_play

int d_sound_play(DARNIT_SOUND *sound_resource, int loop, int vol_l, int vol_r, int jmpto);

Starts playback of a sound resource.

Arguments

  • sound_resource - The sound resource handle to start playback of
  • loop - Currently unimplemented, set to -1
  • vol_l - Volume to play at, left channel. Range is 0..128
  • vol_r - Volume to play at, right channel. Range is 0..128
  • jmpto - Currently unimplemented, set to 0

Return value

Returns the playback channel it's being played on. This number is re-used for other playbacks started after this one ends. Returns -1 if no playback channel was available.

d_sound_playback_status

int d_sound_playback_status(int playback_key);

Returns the status of the playback channel playback_key.

Arguments

  • playback_key - The playback key returned when playback was started

Return value

Returns 0 if the playback channel is active, -1 if not.

d_sound_playback_volume_set

void d_sound_playback_volume_set(unsigned int playback_key, int vol_l, int vol_r);

Sets the volume of a playback channel.

Arguments

  • playback_key - The playback channel to change volume on
  • vol_l - Left channel volume to use. Range is 0..128
  • vol_r - Right channel volume to use. Range is 0..128

Return value None.

d_sound_master_volume

void d_sound_master_volume(int volume);

Sets the master playback volume. This value is used for both left and right sound channels, and is applied after any audio compression, meaning it puts a definite cap on the volume.

Arguments

  • volume - The master sound volume to use. Range is 0..128

Return value None.

d_sound_mix_callback_set

void d_sound_mix_callback_set(void (*callback)(void *ignore, void *mixdata, int bytes));

Overrides libdarnits internal sound mixer and playback completely, and passes sound sample callbacks directly to the function you provide. It expects samples to be in S16_LE interleaved stereo format.

Arguments

  • callback - A function pointer to handle the audio generation. Set to NULL to revert back to libdarnit's mixer
  • ignore - Ignore this pointer
  • mixdata - The buffer you write the audio data to
  • The number of bytes you should fill the buffer with

d_sound_compression_enable

void d_sound_compression_enable();

Enables sound compression. Sound compression is enabled by default. Sound compression prevents clipping by temporary lowering the volume "expanding the range".

Arguments None.

Return value None.

d_sound_compression_disable

void d_sound_compression_disable();

Disables sound compression. If the mixed sound gets too loud, clipping will occur with compression turned off.

Arguments None.

Return value None.

Add a custom footer
Add a custom sidebar

Clone this wiki locally