Mercurial > molko

annotate libmlk-core/mlk/core/music.h @ 634:3930234ab1f5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
examples: add basic gamepad
author David Demelier <markand@malikania.fr>
date Tue, 29 Aug 2023 13:34:10 +0200
parents 848897bfef2f
children fcd124e513ea
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * music.h -- music support
d3ef968745f5 core: rework audio 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>
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 341
diff changeset
19 #ifndef MLK_CORE_MUSIC_H
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 341
diff changeset
20 #define MLK_CORE_MUSIC_H
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
22 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
23 * \file mlk/core/music.h
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
24 * \brief Music support
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
25 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
26 * This module provides support for loading music files and play them with
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
27 * various features such as looping.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
28 */
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
29
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 #include <stddef.h>
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
31
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
32 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
33 * \enum mlk_music_flags
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
34 * \brief Music flags
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
35 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
36 * This enumeration is implemented as a bitmask.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
37 */
456
a6933cd252b7 core: music -> mlk_music
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
38 enum mlk_music_flags {
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
39 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
40 * No flags.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
41 */
464
b6b1162dafa3 core: forgot to refactor music enum
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
42 MLK_MUSIC_NONE = 0,
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
43
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
44 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
45 * Loop the music.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
46 */
464
b6b1162dafa3 core: forgot to refactor music enum
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
47 MLK_MUSIC_LOOP = (1 << 0)
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 };
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
49
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
50 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
51 * \struct mlk_music
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
52 * \brief Music structure
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
53 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
54 * This structure is non-opaque but has no public fields.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
55 */
456
a6933cd252b7 core: music -> mlk_music
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
56 struct mlk_music {
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
57 /** \cond MLK_PRIVATE_DECLS */
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 243
diff changeset
58 void *handle;
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
59 /** \endcond MLK_PRIVATE_DECLS */
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 };
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
61
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
62 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
63 extern "C" {
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
64 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
65
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
66 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
67 * Open a music from the file system path.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
68 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
69 * \pre music != NULL
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
70 * \pre path != NULL
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
71 * \param music the music to initialize
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
72 * \param path the path to the music file (e.g. .ogg, .wav, .mp3, etc)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
73 * \return 0 on success or an error code on failure
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
74 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
75 int
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
76 mlk_music_open(struct mlk_music *music, const char *path);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
77
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
78 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
79 * Open a music from a const binary data.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
80 *
536
848897bfef2f core: doxygenize sound
David Demelier <markand@malikania.fr>
parents: 531
diff changeset
81 * The binary data must be kept alive until the music is no longer used.
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
82 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
83 * \pre music != NULL
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
84 * \pre path != NULL
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
85 * \param music the music to initialize
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
86 * \param data the font content
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
87 * \param datasz the font content length
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
88 * \return 0 on success or an error code on failure
593703440a05 core: doxygenize music
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
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
91 mlk_music_openmem(struct mlk_music *music, const void *data, size_t datasz);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
93 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
94 * Tells if the music structure is usable.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
95 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
96 * \param music the music to check
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
97 * \return non-zero if the music structure is usable
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
98 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
99 int
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
100 mlk_music_ok(const struct mlk_music *music);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
101
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
102 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
103 * Start playing the music.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
104 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
105 * \pre mlk_music_ok(music)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
106 * \param music the music to play
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
107 * \param flags optional flags to pass
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
108 * \return 0 on success or an error code on failure
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
109 */
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
110 int
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
111 mlk_music_play(struct mlk_music *music, enum mlk_music_flags flags);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
112
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
113 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
114 * Pause the music playback.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
115 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
116 * \pre mlk_music_ok(music)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
117 * \param music the music to pause
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
118 * \sa ::mlk_music_resume
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
119 */
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 void
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
121 mlk_music_pause(struct mlk_music *music);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
122
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
123 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
124 * Resume the music where it was stopped.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
125 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
126 * \pre mlk_music_ok(music)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
127 * \param music the music to resume
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
128 * \sa ::mlk_music_pause
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
129 */
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 void
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
131 mlk_music_resume(struct mlk_music *music);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
132
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
133 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
134 * Stop and rewind the music.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
135 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
136 * Calling ::mlk_music_resume on it will restart from the beginning.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
137 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
138 * \pre mlk_music_ok(music)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
139 * \param music the music to stop
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
140 * \sa ::mlk_music_resume
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
141 * \sa ::mlk_music_play
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
142 */
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 void
531
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
144 mlk_music_stop(struct mlk_music *music);
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
145
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
146 /**
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
147 * Destroy this music.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
148 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
149 * If the music is being played, it is stopped immediately.
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
150 *
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
151 * \pre mlk_music_ok(music)
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
152 * \param music the music to destroy
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
153 */
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
154 void
593703440a05 core: doxygenize music
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
155 mlk_music_finish(struct mlk_music *music);
203
d3ef968745f5 core: rework audio API
David Demelier <markand@malikania.fr>
parents:
diff changeset
156
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
157 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
158 }
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 464
diff changeset
159 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
160
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 341
diff changeset
161 #endif /* !MLK_CORE_MUSIC_H */