Mercurial > molko
changeset 536:848897bfef2f
core: doxygenize sound
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 05 Mar 2023 11:05:40 +0100 |
parents | 7d6a879901e0 |
children | 1546a92c51f6 |
files | libmlk-core/mlk/core/music.h libmlk-core/mlk/core/sound.h |
diffstat | 2 files changed, 96 insertions(+), 15 deletions(-) [+] |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/music.h Sun Mar 05 10:53:05 2023 +0100 +++ b/libmlk-core/mlk/core/music.h Sun Mar 05 11:05:40 2023 +0100 @@ -78,7 +78,7 @@ /** * Open a music from a const binary data. * - * The binary data must be kept alive until the font is no longer used. + * The binary data must be kept alive until the music is no longer used. * * \pre music != NULL * \pre path != NULL
--- a/libmlk-core/mlk/core/sound.h Sun Mar 05 10:53:05 2023 +0100 +++ b/libmlk-core/mlk/core/sound.h Sun Mar 05 11:05:40 2023 +0100 @@ -19,42 +19,123 @@ #ifndef MLK_CORE_SOUND_H #define MLK_CORE_SOUND_H +/** + * \file mlk/core/sound.h + * \brief Sound support + * + * This module provides API to play sounds. + * + * In contrast to music.h module, multiple sounds can be played at a time and + * can't be looped. + */ + #include <stddef.h> -#define MLK_SOUND_CHANNELS_MAX (256) - +/** + * \struct mlk_music + * \brief Music structure + * + * This structure is non-opaque but has no public fields. + */ struct mlk_sound { + /** \cond MLK_PRIVATE_DECLS */ void *handle; - int channel; + /** \endcond MLK_PRIVATE_DECLS */ }; #if defined(__cplusplus) extern "C" { #endif +/** + * Open a sound file from the file system path. + * + * \pre music != NULL + * \pre path != NULL + * \param sound the sound to initialize + * \param path the path to the music file (e.g. .ogg, .wav, .mp3, etc) + * \return 0 on success or an error code on failure + */ int -mlk_sound_open(struct mlk_sound *, const char *); - -int -mlk_sound_openmem(struct mlk_sound *, const void *, size_t); +mlk_sound_open(struct mlk_sound *sound, const char *path); +/** + * Open a sound from a const binary data. + * + * The binary data must be kept alive until the sound is no longer used. + * + * \pre music != NULL + * \pre path != NULL + * \param sound the sound to initialize + * \param data the font content + * \param datasz the font content length + * \return 0 on success or an error code on failure + */ int -mlk_sound_ok(const struct mlk_sound *); +mlk_sound_openmem(struct mlk_sound *sound, const void *data, size_t datasz); +/** + * Tells if the sound structure is usable. + * + * \param sound the sound to check + * \return non-zero if the sound structure is usable + */ int -mlk_sound_play(struct mlk_sound *); +mlk_sound_ok(const struct mlk_sound *sound); -void -mlk_sound_pause(struct mlk_sound *); +/** + * Start playing the sound. + * + * \pre mlk_sound_ok(sound) + * \param sound the sound to play + * \return 0 on success or an error code on failure + */ +int +mlk_sound_play(struct mlk_sound *sound); +/** + * Pause the sound playback. + * + * \pre mlk_sound_ok(sound) + * \param sound the sound to pause + * \sa ::mlk_sound_resume + */ void -mlk_sound_resume(struct mlk_sound *); +mlk_sound_pause(struct mlk_sound *sound); +/** + * Resume the sound where it was stopped. + * + * \pre mlk_sound_ok(sound) + * \param sound the sound to resume + * \sa ::mlk_sound_pause + */ void -mlk_sound_stop(struct mlk_sound *); +mlk_sound_resume(struct mlk_sound *sound); +/** + * Stop and rewind the sound. + * + * Calling ::mlk_sound_resume on it will restart from the beginning. + * + * \pre mlk_sound_ok(sound) + * \param sound the sound to stop + * \sa ::mlk_sound_resume + * \sa ::mlk_sound_play + */ void -mlk_sound_finish(struct mlk_sound *); +mlk_sound_stop(struct mlk_sound *sound); + +/** + * Destroy this sound. + * + * If the sound is being played, it is stopped immediately. + * + * \pre mlk_sound_ok(sound) + * \param sound the sound to destroy + */ +void +mlk_sound_finish(struct mlk_sound *sound); #if defined(__cplusplus) }