Mercurial > molko

annotate libmlk-core/mlk/core/sound.h @ 536:848897bfef2f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: doxygenize sound
author David Demelier <markand@malikania.fr>
date Sun, 05 Mar 2023 11:05:40 +0100
parents 6e8f6640e05b
children fcd124e513ea
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 */