Mercurial > molko

annotate libmlk-core/mlk/core/sound.h @ 641:fcd124e513ea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: reintroduce VFS
author David Demelier <markand@malikania.fr>
date Sun, 01 Oct 2023 09:18:01 +0200
parents 848897bfef2f
children
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
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
34 struct mlk_vfs_file;
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
35
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
36 /**
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
37 * \struct mlk_music
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
38 * \brief Music structure
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
39 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
40 * This structure is non-opaque but has no public fields.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
41 */
467
7420c78018dc core: sound -> mlk_sound
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
42 struct mlk_sound {
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
43 /** \cond MLK_PRIVATE_DECLS */
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 243
diff changeset
44 void *handle;
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
45 /** \endcond MLK_PRIVATE_DECLS */
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 };
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
47
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
48 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
49 extern "C" {
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
50 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
51
536
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 * Open a sound file from the file system path.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
54 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
55 * \pre music != NULL
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
56 * \pre path != NULL
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
57 * \param sound the sound to initialize
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
58 * \param path the path to the music file (e.g. .ogg, .wav, .mp3, etc)
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
59 * \return 0 on success or -1 on error
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
60 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
61 int
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
62 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
63
536
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 * Open a sound from a const binary data.
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 * 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
68 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
69 * \pre music != NULL
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
70 * \pre path != NULL
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
71 * \param sound the sound to initialize
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
72 * \param data the sound data
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
73 * \param datasz the sound data length
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
74 * \return 0 on success or -1 on error
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
75 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
76 int
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
77 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
78
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
79 /**
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
80 * Open a sound from a virtual file system.
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
81 *
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
82 * The VFS file can be discarded after loading the sound.
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
83 *
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
84 * \pre sound != NULL
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
85 * \pre file != NULL
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
86 * \param sound the sound to initialize
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
87 * \param file the VFS file
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
88 * \return 0 on success or -1 on error
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
89 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
90 int
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
91 mlk_sound_openvfs(struct mlk_sound *snd, struct mlk_vfs_file *file);
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
93 /**
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
94 * Start playing the sound.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
95 *
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
96 * \pre sound != NULL
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
97 * \param sound the sound to play
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
98 * \return 0 on success or -1 on error
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
99 */
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
100 int
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
101 mlk_sound_play(struct mlk_sound *sound);
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
103 /**
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
104 * Pause the sound playback.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
105 *
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
106 * \pre sound != NULL
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
107 * \param sound the sound to pause
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
108 * \sa ::mlk_sound_resume
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
109 */
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 void
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
111 mlk_sound_pause(struct mlk_sound *sound);
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
112
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
113 /**
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
114 * Resume the sound where it was stopped.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
115 *
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
116 * \pre sound != NULL
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
117 * \param sound the sound to resume
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
118 * \sa ::mlk_sound_pause
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
119 */
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 void
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
121 mlk_sound_resume(struct mlk_sound *sound);
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
122
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
123 /**
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
124 * Stop and rewind the sound.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
125 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
126 * Calling ::mlk_sound_resume on it will restart from the beginning.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
127 *
641
fcd124e513ea core: reintroduce VFS
David Demelier <markand@malikania.fr>
parents: 536
diff changeset
128 * \pre sound != NULL
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
129 * \param sound the sound to stop
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
130 * \sa ::mlk_sound_resume
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
131 * \sa ::mlk_sound_play
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
132 */
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 void
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
134 mlk_sound_stop(struct mlk_sound *sound);
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
135
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 * Destroy this sound.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
138 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
139 * If the sound is being played, it is stopped immediately.
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
140 *
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
141 * \pre mlk_sound_ok(sound)
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
142 * \param sound the sound to destroy
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
143 */
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
144 void
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
145 mlk_sound_finish(struct mlk_sound *sound);
103
68ce8e02061a sound: add basic sound API
David Demelier <markand@malikania.fr>
parents:
diff changeset
146
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
147 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
148 }
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 467
diff changeset
149 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
150
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 343
diff changeset
151 #endif /* !MLK_CORE_SOUND_H */