PocketSprite Sound Mixer¶
The PocketSprite SDK comes with a sound mixer and decoder, capable of decoding mono wave files and music modules in .mod/.s3m/.xm format. It can decode and play multiple of these files simultaneously, mixing them using different volumes.
(ToDo: detail memory use, note that .xm is more intensive than .mod/.s3m)
Functions¶
-
int
sndmixer_init
(int no_channels, int samplerate)¶ Initialize the sound mixer.
- Note
- This function internally calls kchal_sound_start, there is no need to do this in your program if you use this function to initialize the sound mixer.
- Parameters
no_channels
: Amount if sounds to be able to be played simultaneously.samplerate
: Sample rate to mix all sources to
-
int
sndmixer_queue_wav
(const void *wav_start, const void *wav_end, int evictable)¶ Queue the data of a .wav file to be played.
This queues a sound to be played. It will not be actually played until sndmixer_play is called.
- Return
- The ID of the queued sound, for use with the other functions.
- Parameters
wav_start
: Start of the wav-file datawav_end
: End of the wav-file dataevictable
: If true, if all audio channels are filled and a new sound is queued, this sound can be stopped to make room for the new sound.
-
int
sndmixer_queue_mod
(const void *mod_start, const void *mod_end)¶ Queue the data of a .mod/.xm/.s3m file to be played.
This queues a piece of tracked music to be played. It will not be actually played until sndmixer_play is called.
- Return
- The ID of the queued sound, for use with the other functions.
- Parameters
wav_start
: Start of the filedatawav_end
: End of the filedata
-
void
sndmixer_set_loop
(int id, int loop)¶ Set or unset a sound to looping mode.
- Warning
- This may not be implemented yet. TODO: remove this warning when implemented.
- Parameters
id
: ID of the sound, obtained when queueing itloop
: If true, the sound will loop back to the beginning when it ends.
-
void
sndmixer_set_volume
(int id, int volume)¶ Set volume of a sound.
A queued sound will always start off with a volume setting of 255 (max volume). This call can be used to adjust the volume of the sound at any time afterwards.
- Parameters
id
: ID of the sound, obtained when queueing itvolume
: New volume, between 0 (muted) and 255 (full sound).
-
void
sndmixer_play
(int id)¶ Play a sound.
When a sound is queued, it is not playing yet. Use this call to start playback. You can also use this call to resume a sound paused by sndmixer_pause or sndmixer_pause_all.
- Parameters
id
: ID of the sound, obtained when queueing it
-
void
sndmixer_pause
(int id)¶ Pause a sound.
Stops playback of the sound. The sound can be resumed with sndmixer_play().
- Parameters
id
: ID of the sound, obtained when queueing it
-
void
sndmixer_stop
(int id)¶ Stop a sound, free the sound source and channel it used.
Stops playback of the sound and frees all associated structures.
- Parameters
id
: ID of the sound, obtained when queueing it
-
void
sndmixer_pause_all
()¶ Pause all playing sounds.
This can be used when e.g. the game is paused. Sounds can be individually un-paused afterwards and new sounds can still be queued and played, given enough free/evictable channels.
-
void
sndmixer_resume_all
()¶ Resume all paused sounds.
This can be used to undo a sndmixer_pause_all() call.
Structures¶
-
struct
sndmixer_source_t
¶ Structure describing a sound source.
Public Members
-
int (*
init_source
)(const void *data_start, const void *data_end, int req_sample_rate, void **ctx)¶ Initialize the sound source. Returns size of data returned per call of fill_buffer.
-
int (*
get_sample_rate
)(void *ctx)¶ Get the actual sample rate at which the source returns data
-
int (*
fill_buffer
)(void *ctx, int8_t *buffer)¶ Decode a bufferful of data. Returns 0 when file ended or something went wrong. Returns amount of bytes in buffer (normally what init_source returned) otherwise.
-
void (*
deinit_source
)(void *ctx)¶ Destroy source, free resources
-
int (*