Mercurial > molko
annotate libcore/core/music.h @ 229:e71039d820a7
doc: improve documentation
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Thu, 19 Nov 2020 16:46:26 +0100 |
| parents | dd7c8d4321a3 |
| children |
| rev | line source |
|---|---|
| 203 | 1 /* |
| 2 * music.h -- music support | |
| 3 * | |
| 4 * Copyright (c) 2020 David Demelier <markand@malikania.fr> | |
| 5 * | |
| 6 * Permission to use, copy, modify, and/or distribute this software for any | |
| 7 * purpose with or without fee is hereby granted, provided that the above | |
| 8 * copyright notice and this permission notice appear in all copies. | |
| 9 * | |
| 10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 17 */ | |
| 18 | |
| 19 #ifndef MOLKO_CORE_MUSIC_H | |
| 20 #define MOLKO_CORE_MUSIC_H | |
| 21 | |
| 22 /** | |
| 23 * \file music.h | |
| 24 * \brief Music support. | |
| 25 * | |
| 26 * This module provide support for playing music. In contrast to sounds only one | |
| 27 * music can be played at a time. | |
| 28 */ | |
| 29 | |
| 30 #include <stdbool.h> | |
| 31 #include <stddef.h> | |
| 32 | |
| 33 /** | |
| 34 * \brief Music flags. | |
| 35 */ | |
| 36 enum music_flags { | |
| 37 MUSIC_NONE, /*!< No flags. */ | |
| 38 MUSIC_LOOP = (1 << 0) /*!< Loop the music. */ | |
| 39 }; | |
| 40 | |
| 41 /** | |
| 42 * \brief Music object handle. | |
| 43 */ | |
| 44 struct music { | |
| 45 void *handle; /*!< (*) Implementation handle. */ | |
| 46 }; | |
| 47 | |
| 48 /** | |
| 49 * Open a music file. | |
| 50 * | |
| 51 * \pre mus != NULL | |
| 52 * \pre path != NULL | |
| 53 * \param mus the music object to initialize | |
| 54 * \param path the path to the music file | |
| 55 * \return False on errors. | |
| 56 */ | |
| 57 bool | |
|
226
dd7c8d4321a3
misc: miscellaneous cleanups
David Demelier <markand@malikania.fr>
parents:
203
diff
changeset
|
58 music_open(struct music *mus, const char *path); |
| 203 | 59 |
| 60 /** | |
| 61 * Open a music from a buffer. | |
| 62 * | |
| 63 * \pre mus != NULL | |
| 64 * \pre buffer != NULL | |
| 65 * \param mus the music object to initialize | |
| 66 * \param buffer the buffer | |
| 67 * \param buffersz the buffer size | |
| 68 * \return False on errors. | |
| 69 * \warning The buffer must exists until the sound object is closed. | |
| 70 */ | |
| 71 bool | |
|
226
dd7c8d4321a3
misc: miscellaneous cleanups
David Demelier <markand@malikania.fr>
parents:
203
diff
changeset
|
72 music_openmem(struct music *mus, const void *buffer, size_t buffersz); |
| 203 | 73 |
| 74 /** | |
| 75 * Check if this music handle is properly loaded. | |
| 76 * | |
| 77 * \param mus the music to check (may be NULL) | |
| 78 */ | |
| 79 bool | |
| 80 music_ok(const struct music *mus); | |
| 81 | |
| 82 /** | |
| 83 * Start playing the given music | |
| 84 * | |
| 85 * This function will resume the playback since the beginning and will stop the | |
| 86 * current music. If the music playing is currently fading out this function | |
| 87 * will block until it has finished. | |
| 88 * | |
| 89 * \pre mus != NULL | |
| 90 * \param mus the music to start | |
| 91 * \param flags optional flags | |
| 92 * \param fadein a fade in delay in milliseconds (0 to disable) | |
| 93 * \return False on errors. | |
| 94 */ | |
| 95 bool | |
| 96 music_play(struct music *mus, enum music_flags flags, unsigned int fadein); | |
| 97 | |
| 98 /** | |
| 99 * Tells if music is playing. | |
| 100 * | |
| 101 * You can call this function with any music even one that is not currently | |
| 102 * playing. | |
| 103 */ | |
| 104 bool | |
| 105 music_playing(void); | |
| 106 | |
| 107 /** | |
| 108 * Pause the music playback. | |
| 109 */ | |
| 110 void | |
| 111 music_pause(void); | |
| 112 | |
| 113 /** | |
| 114 * Resume the music playback. | |
| 115 */ | |
| 116 void | |
| 117 music_resume(void); | |
| 118 | |
| 119 /** | |
| 120 * Stop the sound music. | |
| 121 * | |
| 122 * \param fadeout a fade out delay in milliseconds (0 to disable) | |
| 123 */ | |
| 124 void | |
| 125 music_stop(unsigned int fadeout); | |
| 126 | |
| 127 /** | |
| 128 * Close the associated resources. | |
| 129 * | |
|
229
e71039d820a7
doc: improve documentation
David Demelier <markand@malikania.fr>
parents:
226
diff
changeset
|
130 * \pre mus != NULL |
|
e71039d820a7
doc: improve documentation
David Demelier <markand@malikania.fr>
parents:
226
diff
changeset
|
131 * \param mus the music object |
| 203 | 132 */ |
| 133 void | |
| 134 music_finish(struct music *mus); | |
| 135 | |
| 136 #endif /* !MOLKO_CORE_MUSIC_H */ |