Mercurial > molko
annotate libmlk-core/mlk/core/sound.h @ 602:7e168493f0bd
cmake: fix NLS required
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 10 Aug 2023 21:16:05 +0200 |
parents | 848897bfef2f |
children | fcd124e513ea |
rev | line source |
---|---|
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 /* |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 * sound.h -- sound support |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 * |
445
773a082f0b91
misc: update copyright years
David Demelier <markand@malikania.fr>
parents:
431
diff
changeset
|
4 * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr> |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 * |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 * Permission to use, copy, modify, and/or distribute this software for any |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 * purpose with or without fee is hereby granted, provided that the above |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 * copyright notice and this permission notice appear in all copies. |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 * |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 */ |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
343
diff
changeset
|
19 #ifndef MLK_CORE_SOUND_H |
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
343
diff
changeset
|
20 #define MLK_CORE_SOUND_H |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
22 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
23 * \file mlk/core/sound.h |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
24 * \brief Sound support |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
25 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
26 * This module provides API to play sounds. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
27 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
28 * In contrast to music.h module, multiple sounds can be played at a time and |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
29 * can't be looped. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
30 */ |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
31 |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 #include <stddef.h> |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
34 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
35 * \struct mlk_music |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
36 * \brief Music structure |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
37 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
38 * This structure is non-opaque but has no public fields. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
39 */ |
467
7420c78018dc
core: sound -> mlk_sound
David Demelier <markand@malikania.fr>
parents:
462
diff
changeset
|
40 struct mlk_sound { |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
41 /** \cond MLK_PRIVATE_DECLS */ |
253
c4da052c0def
core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
243
diff
changeset
|
42 void *handle; |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
43 /** \endcond MLK_PRIVATE_DECLS */ |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 }; |
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 |
517
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
46 #if defined(__cplusplus) |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
47 extern "C" { |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
48 #endif |
292
08ab73b32832
misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
49 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
50 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
51 * Open a sound file from the file system path. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
52 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
53 * \pre music != NULL |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
54 * \pre path != NULL |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
55 * \param sound the sound to initialize |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
56 * \param path the path to the music file (e.g. .ogg, .wav, .mp3, etc) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
57 * \return 0 on success or an error code on failure |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
58 */ |
298
196264679079
misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents:
292
diff
changeset
|
59 int |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
60 mlk_sound_open(struct mlk_sound *sound, const char *path); |
203
d3ef968745f5
core: rework audio API
David Demelier <markand@malikania.fr>
parents:
169
diff
changeset
|
61 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
62 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
63 * Open a sound from a const binary data. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
64 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
65 * The binary data must be kept alive until the sound is no longer used. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
66 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
67 * \pre music != NULL |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
68 * \pre path != NULL |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
69 * \param sound the sound to initialize |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
70 * \param data the font content |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
71 * \param datasz the font content length |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
72 * \return 0 on success or an error code on failure |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
73 */ |
298
196264679079
misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents:
292
diff
changeset
|
74 int |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
75 mlk_sound_openmem(struct mlk_sound *sound, const void *data, size_t datasz); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
77 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
78 * Tells if the sound structure is usable. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
79 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
80 * \param sound the sound to check |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
81 * \return non-zero if the sound structure is usable |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
82 */ |
298
196264679079
misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents:
292
diff
changeset
|
83 int |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
84 mlk_sound_ok(const struct mlk_sound *sound); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
85 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
86 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
87 * Start playing the sound. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
88 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
89 * \pre mlk_sound_ok(sound) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
90 * \param sound the sound to play |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
91 * \return 0 on success or an error code on failure |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
92 */ |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
93 int |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
94 mlk_sound_play(struct mlk_sound *sound); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
95 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
96 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
97 * Pause the sound playback. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
98 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
99 * \pre mlk_sound_ok(sound) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
100 * \param sound the sound to pause |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
101 * \sa ::mlk_sound_resume |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
102 */ |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
103 void |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
104 mlk_sound_pause(struct mlk_sound *sound); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
105 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
106 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
107 * Resume the sound where it was stopped. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
108 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
109 * \pre mlk_sound_ok(sound) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
110 * \param sound the sound to resume |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
111 * \sa ::mlk_sound_pause |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
112 */ |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
113 void |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
114 mlk_sound_resume(struct mlk_sound *sound); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
115 |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
116 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
117 * Stop and rewind the sound. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
118 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
119 * Calling ::mlk_sound_resume on it will restart from the beginning. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
120 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
121 * \pre mlk_sound_ok(sound) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
122 * \param sound the sound to stop |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
123 * \sa ::mlk_sound_resume |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
124 * \sa ::mlk_sound_play |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
125 */ |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
126 void |
536
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
127 mlk_sound_stop(struct mlk_sound *sound); |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
128 |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
129 /** |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
130 * Destroy this sound. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
131 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
132 * If the sound is being played, it is stopped immediately. |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
133 * |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
134 * \pre mlk_sound_ok(sound) |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
135 * \param sound the sound to destroy |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
136 */ |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
137 void |
848897bfef2f
core: doxygenize sound
David Demelier <markand@malikania.fr>
parents:
517
diff
changeset
|
138 mlk_sound_finish(struct mlk_sound *sound); |
103
68ce8e02061a
sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
139 |
517
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
140 #if defined(__cplusplus) |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
141 } |
6e8f6640e05b
misc: use extern C manually
David Demelier <markand@malikania.fr>
parents:
467
diff
changeset
|
142 #endif |
292
08ab73b32832
misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
143 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
343
diff
changeset
|
144 #endif /* !MLK_CORE_SOUND_H */ |