|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryAudio
|
|
|
24 *
|
|
|
25 * Audio functionality for the SDL library.
|
|
|
26 *
|
|
|
27 * All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play
|
|
|
28 * or record audio, convert it, stream it, buffer it, or mix it, you're going
|
|
|
29 * to be passing it through an audio stream.
|
|
|
30 *
|
|
|
31 * Audio streams are quite flexible; they can accept any amount of data at a
|
|
|
32 * time, in any supported format, and output it as needed in any other format,
|
|
|
33 * even if the data format changes on either side halfway through.
|
|
|
34 *
|
|
|
35 * An app opens an audio device and binds any number of audio streams to it,
|
|
|
36 * feeding more data to the streams as available. When the device needs more
|
|
|
37 * data, it will pull it from all bound streams and mix them together for
|
|
|
38 * playback.
|
|
|
39 *
|
|
|
40 * Audio streams can also use an app-provided callback to supply data
|
|
|
41 * on-demand, which maps pretty closely to the SDL2 audio model.
|
|
|
42 *
|
|
|
43 * SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO
|
|
|
44 * if you aren't reading from a file) as a basic means to load sound data into
|
|
|
45 * your program.
|
|
|
46 *
|
|
|
47 * ## Logical audio devices
|
|
|
48 *
|
|
|
49 * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a
|
|
|
50 * logical device ID that you can bind audio streams to. In almost all cases,
|
|
|
51 * logical devices can be used anywhere in the API that a physical device is
|
|
|
52 * normally used. However, since each device opening generates a new logical
|
|
|
53 * device, different parts of the program (say, a VoIP library, or
|
|
|
54 * text-to-speech framework, or maybe some other sort of mixer on top of SDL)
|
|
|
55 * can have their own device opens that do not interfere with each other; each
|
|
|
56 * logical device will mix its separate audio down to a single buffer, fed to
|
|
|
57 * the physical device, behind the scenes. As many logical devices as you like
|
|
|
58 * can come and go; SDL will only have to open the physical device at the OS
|
|
|
59 * level once, and will manage all the logical devices on top of it
|
|
|
60 * internally.
|
|
|
61 *
|
|
|
62 * One other benefit of logical devices: if you don't open a specific physical
|
|
|
63 * device, instead opting for the default, SDL can automatically migrate those
|
|
|
64 * logical devices to different hardware as circumstances change: a user
|
|
|
65 * plugged in headphones? The system default changed? SDL can transparently
|
|
|
66 * migrate the logical devices to the correct physical device seamlessly and
|
|
|
67 * keep playing; the app doesn't even have to know it happened if it doesn't
|
|
|
68 * want to.
|
|
|
69 *
|
|
|
70 * ## Simplified audio
|
|
|
71 *
|
|
|
72 * As a simplified model for when a single source of audio is all that's
|
|
|
73 * needed, an app can use SDL_OpenAudioDeviceStream, which is a single
|
|
|
74 * function to open an audio device, create an audio stream, bind that stream
|
|
|
75 * to the newly-opened device, and (optionally) provide a callback for
|
|
|
76 * obtaining audio data. When using this function, the primary interface is
|
|
|
77 * the SDL_AudioStream and the device handle is mostly hidden away; destroying
|
|
|
78 * a stream created through this function will also close the device, stream
|
|
|
79 * bindings cannot be changed, etc. One other quirk of this is that the device
|
|
|
80 * is started in a _paused_ state and must be explicitly resumed; this is
|
|
|
81 * partially to offer a clean migration for SDL2 apps and partially because
|
|
|
82 * the app might have to do more setup before playback begins; in the
|
|
|
83 * non-simplified form, nothing will play until a stream is bound to a device,
|
|
|
84 * so they start _unpaused_.
|
|
|
85 *
|
|
|
86 * ## Channel layouts
|
|
|
87 *
|
|
|
88 * Audio data passing through SDL is uncompressed PCM data, interleaved. One
|
|
|
89 * can provide their own decompression through an MP3, etc, decoder, but SDL
|
|
|
90 * does not provide this directly. Each interleaved channel of data is meant
|
|
|
91 * to be in a specific order.
|
|
|
92 *
|
|
|
93 * Abbreviations:
|
|
|
94 *
|
|
|
95 * - FRONT = single mono speaker
|
|
|
96 * - FL = front left speaker
|
|
|
97 * - FR = front right speaker
|
|
|
98 * - FC = front center speaker
|
|
|
99 * - BL = back left speaker
|
|
|
100 * - BR = back right speaker
|
|
|
101 * - SR = surround right speaker
|
|
|
102 * - SL = surround left speaker
|
|
|
103 * - BC = back center speaker
|
|
|
104 * - LFE = low-frequency speaker
|
|
|
105 *
|
|
|
106 * These are listed in the order they are laid out in memory, so "FL, FR"
|
|
|
107 * means "the front left speaker is laid out in memory first, then the front
|
|
|
108 * right, then it repeats for the next audio frame".
|
|
|
109 *
|
|
|
110 * - 1 channel (mono) layout: FRONT
|
|
|
111 * - 2 channels (stereo) layout: FL, FR
|
|
|
112 * - 3 channels (2.1) layout: FL, FR, LFE
|
|
|
113 * - 4 channels (quad) layout: FL, FR, BL, BR
|
|
|
114 * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR
|
|
|
115 * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be
|
|
|
116 * SL, SR)
|
|
|
117 * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR
|
|
|
118 * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR
|
|
|
119 *
|
|
|
120 * This is the same order as DirectSound expects, but applied to all
|
|
|
121 * platforms; SDL will swizzle the channels as necessary if a platform expects
|
|
|
122 * something different.
|
|
|
123 *
|
|
|
124 * SDL_AudioStream can also be provided channel maps to change this ordering
|
|
|
125 * to whatever is necessary, in other audio processing scenarios.
|
|
|
126 */
|
|
|
127
|
|
|
128 #ifndef SDL_audio_h_
|
|
|
129 #define SDL_audio_h_
|
|
|
130
|
|
|
131 #include <SDL3/SDL_stdinc.h>
|
|
|
132 #include <SDL3/SDL_endian.h>
|
|
|
133 #include <SDL3/SDL_error.h>
|
|
|
134 #include <SDL3/SDL_mutex.h>
|
|
|
135 #include <SDL3/SDL_properties.h>
|
|
|
136 #include <SDL3/SDL_iostream.h>
|
|
|
137
|
|
|
138 #include <SDL3/SDL_begin_code.h>
|
|
|
139 /* Set up for C function definitions, even when using C++ */
|
|
|
140 #ifdef __cplusplus
|
|
|
141 extern "C" {
|
|
|
142 #endif
|
|
|
143
|
|
|
144 /**
|
|
|
145 * Mask of bits in an SDL_AudioFormat that contains the format bit size.
|
|
|
146 *
|
|
|
147 * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly.
|
|
|
148 *
|
|
|
149 * \since This macro is available since SDL 3.2.0.
|
|
|
150 */
|
|
|
151 #define SDL_AUDIO_MASK_BITSIZE (0xFFu)
|
|
|
152
|
|
|
153 /**
|
|
|
154 * Mask of bits in an SDL_AudioFormat that contain the floating point flag.
|
|
|
155 *
|
|
|
156 * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly.
|
|
|
157 *
|
|
|
158 * \since This macro is available since SDL 3.2.0.
|
|
|
159 */
|
|
|
160 #define SDL_AUDIO_MASK_FLOAT (1u<<8)
|
|
|
161
|
|
|
162 /**
|
|
|
163 * Mask of bits in an SDL_AudioFormat that contain the bigendian flag.
|
|
|
164 *
|
|
|
165 * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN
|
|
|
166 * instead of this macro directly.
|
|
|
167 *
|
|
|
168 * \since This macro is available since SDL 3.2.0.
|
|
|
169 */
|
|
|
170 #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12)
|
|
|
171
|
|
|
172 /**
|
|
|
173 * Mask of bits in an SDL_AudioFormat that contain the signed data flag.
|
|
|
174 *
|
|
|
175 * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly.
|
|
|
176 *
|
|
|
177 * \since This macro is available since SDL 3.2.0.
|
|
|
178 */
|
|
|
179 #define SDL_AUDIO_MASK_SIGNED (1u<<15)
|
|
|
180
|
|
|
181 /**
|
|
|
182 * Define an SDL_AudioFormat value.
|
|
|
183 *
|
|
|
184 * SDL does not support custom audio formats, so this macro is not of much use
|
|
|
185 * externally, but it can be illustrative as to what the various bits of an
|
|
|
186 * SDL_AudioFormat mean.
|
|
|
187 *
|
|
|
188 * For example, SDL_AUDIO_S32LE looks like this:
|
|
|
189 *
|
|
|
190 * ```c
|
|
|
191 * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32)
|
|
|
192 * ```
|
|
|
193 *
|
|
|
194 * \param signed 1 for signed data, 0 for unsigned data.
|
|
|
195 * \param bigendian 1 for bigendian data, 0 for littleendian data.
|
|
|
196 * \param flt 1 for floating point data, 0 for integer data.
|
|
|
197 * \param size number of bits per sample.
|
|
|
198 * \returns a format value in the style of SDL_AudioFormat.
|
|
|
199 *
|
|
|
200 * \threadsafety It is safe to call this macro from any thread.
|
|
|
201 *
|
|
|
202 * \since This macro is available since SDL 3.2.0.
|
|
|
203 */
|
|
|
204 #define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \
|
|
|
205 (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
|
|
|
206
|
|
|
207 /**
|
|
|
208 * Audio format.
|
|
|
209 *
|
|
|
210 * \since This enum is available since SDL 3.2.0.
|
|
|
211 *
|
|
|
212 * \sa SDL_AUDIO_BITSIZE
|
|
|
213 * \sa SDL_AUDIO_BYTESIZE
|
|
|
214 * \sa SDL_AUDIO_ISINT
|
|
|
215 * \sa SDL_AUDIO_ISFLOAT
|
|
|
216 * \sa SDL_AUDIO_ISBIGENDIAN
|
|
|
217 * \sa SDL_AUDIO_ISLITTLEENDIAN
|
|
|
218 * \sa SDL_AUDIO_ISSIGNED
|
|
|
219 * \sa SDL_AUDIO_ISUNSIGNED
|
|
|
220 */
|
|
|
221 typedef enum SDL_AudioFormat
|
|
|
222 {
|
|
|
223 SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */
|
|
|
224 SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */
|
|
|
225 /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */
|
|
|
226 SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */
|
|
|
227 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */
|
|
|
228 SDL_AUDIO_S16LE = 0x8010u, /**< Signed 16-bit samples */
|
|
|
229 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */
|
|
|
230 SDL_AUDIO_S16BE = 0x9010u, /**< As above, but big-endian byte order */
|
|
|
231 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */
|
|
|
232 SDL_AUDIO_S32LE = 0x8020u, /**< 32-bit integer samples */
|
|
|
233 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */
|
|
|
234 SDL_AUDIO_S32BE = 0x9020u, /**< As above, but big-endian byte order */
|
|
|
235 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */
|
|
|
236 SDL_AUDIO_F32LE = 0x8120u, /**< 32-bit floating point samples */
|
|
|
237 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */
|
|
|
238 SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */
|
|
|
239 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */
|
|
|
240
|
|
|
241 /* These represent the current system's byteorder. */
|
|
|
242 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
|
|
|
243 SDL_AUDIO_S16 = SDL_AUDIO_S16LE,
|
|
|
244 SDL_AUDIO_S32 = SDL_AUDIO_S32LE,
|
|
|
245 SDL_AUDIO_F32 = SDL_AUDIO_F32LE
|
|
|
246 #else
|
|
|
247 SDL_AUDIO_S16 = SDL_AUDIO_S16BE,
|
|
|
248 SDL_AUDIO_S32 = SDL_AUDIO_S32BE,
|
|
|
249 SDL_AUDIO_F32 = SDL_AUDIO_F32BE
|
|
|
250 #endif
|
|
|
251 } SDL_AudioFormat;
|
|
|
252
|
|
|
253
|
|
|
254 /**
|
|
|
255 * Retrieve the size, in bits, from an SDL_AudioFormat.
|
|
|
256 *
|
|
|
257 * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
|
|
|
258 *
|
|
|
259 * \param x an SDL_AudioFormat value.
|
|
|
260 * \returns data size in bits.
|
|
|
261 *
|
|
|
262 * \threadsafety It is safe to call this macro from any thread.
|
|
|
263 *
|
|
|
264 * \since This macro is available since SDL 3.2.0.
|
|
|
265 */
|
|
|
266 #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE)
|
|
|
267
|
|
|
268 /**
|
|
|
269 * Retrieve the size, in bytes, from an SDL_AudioFormat.
|
|
|
270 *
|
|
|
271 * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
|
|
|
272 *
|
|
|
273 * \param x an SDL_AudioFormat value.
|
|
|
274 * \returns data size in bytes.
|
|
|
275 *
|
|
|
276 * \threadsafety It is safe to call this macro from any thread.
|
|
|
277 *
|
|
|
278 * \since This macro is available since SDL 3.2.0.
|
|
|
279 */
|
|
|
280 #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8)
|
|
|
281
|
|
|
282 /**
|
|
|
283 * Determine if an SDL_AudioFormat represents floating point data.
|
|
|
284 *
|
|
|
285 * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
|
|
|
286 *
|
|
|
287 * \param x an SDL_AudioFormat value.
|
|
|
288 * \returns non-zero if format is floating point, zero otherwise.
|
|
|
289 *
|
|
|
290 * \threadsafety It is safe to call this macro from any thread.
|
|
|
291 *
|
|
|
292 * \since This macro is available since SDL 3.2.0.
|
|
|
293 */
|
|
|
294 #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT)
|
|
|
295
|
|
|
296 /**
|
|
|
297 * Determine if an SDL_AudioFormat represents bigendian data.
|
|
|
298 *
|
|
|
299 * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
|
|
|
300 *
|
|
|
301 * \param x an SDL_AudioFormat value.
|
|
|
302 * \returns non-zero if format is bigendian, zero otherwise.
|
|
|
303 *
|
|
|
304 * \threadsafety It is safe to call this macro from any thread.
|
|
|
305 *
|
|
|
306 * \since This macro is available since SDL 3.2.0.
|
|
|
307 */
|
|
|
308 #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
|
|
|
309
|
|
|
310 /**
|
|
|
311 * Determine if an SDL_AudioFormat represents littleendian data.
|
|
|
312 *
|
|
|
313 * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
|
|
|
314 *
|
|
|
315 * \param x an SDL_AudioFormat value.
|
|
|
316 * \returns non-zero if format is littleendian, zero otherwise.
|
|
|
317 *
|
|
|
318 * \threadsafety It is safe to call this macro from any thread.
|
|
|
319 *
|
|
|
320 * \since This macro is available since SDL 3.2.0.
|
|
|
321 */
|
|
|
322 #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
|
|
|
323
|
|
|
324 /**
|
|
|
325 * Determine if an SDL_AudioFormat represents signed data.
|
|
|
326 *
|
|
|
327 * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
|
|
|
328 *
|
|
|
329 * \param x an SDL_AudioFormat value.
|
|
|
330 * \returns non-zero if format is signed, zero otherwise.
|
|
|
331 *
|
|
|
332 * \threadsafety It is safe to call this macro from any thread.
|
|
|
333 *
|
|
|
334 * \since This macro is available since SDL 3.2.0.
|
|
|
335 */
|
|
|
336 #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED)
|
|
|
337
|
|
|
338 /**
|
|
|
339 * Determine if an SDL_AudioFormat represents integer data.
|
|
|
340 *
|
|
|
341 * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
|
|
|
342 *
|
|
|
343 * \param x an SDL_AudioFormat value.
|
|
|
344 * \returns non-zero if format is integer, zero otherwise.
|
|
|
345 *
|
|
|
346 * \threadsafety It is safe to call this macro from any thread.
|
|
|
347 *
|
|
|
348 * \since This macro is available since SDL 3.2.0.
|
|
|
349 */
|
|
|
350 #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
|
|
|
351
|
|
|
352 /**
|
|
|
353 * Determine if an SDL_AudioFormat represents unsigned data.
|
|
|
354 *
|
|
|
355 * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
|
|
|
356 *
|
|
|
357 * \param x an SDL_AudioFormat value.
|
|
|
358 * \returns non-zero if format is unsigned, zero otherwise.
|
|
|
359 *
|
|
|
360 * \threadsafety It is safe to call this macro from any thread.
|
|
|
361 *
|
|
|
362 * \since This macro is available since SDL 3.2.0.
|
|
|
363 */
|
|
|
364 #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
|
|
|
365
|
|
|
366
|
|
|
367 /**
|
|
|
368 * SDL Audio Device instance IDs.
|
|
|
369 *
|
|
|
370 * Zero is used to signify an invalid/null device.
|
|
|
371 *
|
|
|
372 * \since This datatype is available since SDL 3.2.0.
|
|
|
373 */
|
|
|
374 typedef Uint32 SDL_AudioDeviceID;
|
|
|
375
|
|
|
376 /**
|
|
|
377 * A value used to request a default playback audio device.
|
|
|
378 *
|
|
|
379 * Several functions that require an SDL_AudioDeviceID will accept this value
|
|
|
380 * to signify the app just wants the system to choose a default device instead
|
|
|
381 * of the app providing a specific one.
|
|
|
382 *
|
|
|
383 * \since This macro is available since SDL 3.2.0.
|
|
|
384 */
|
|
|
385 #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu)
|
|
|
386
|
|
|
387 /**
|
|
|
388 * A value used to request a default recording audio device.
|
|
|
389 *
|
|
|
390 * Several functions that require an SDL_AudioDeviceID will accept this value
|
|
|
391 * to signify the app just wants the system to choose a default device instead
|
|
|
392 * of the app providing a specific one.
|
|
|
393 *
|
|
|
394 * \since This macro is available since SDL 3.2.0.
|
|
|
395 */
|
|
|
396 #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu)
|
|
|
397
|
|
|
398 /**
|
|
|
399 * Format specifier for audio data.
|
|
|
400 *
|
|
|
401 * \since This struct is available since SDL 3.2.0.
|
|
|
402 *
|
|
|
403 * \sa SDL_AudioFormat
|
|
|
404 */
|
|
|
405 typedef struct SDL_AudioSpec
|
|
|
406 {
|
|
|
407 SDL_AudioFormat format; /**< Audio data format */
|
|
|
408 int channels; /**< Number of channels: 1 mono, 2 stereo, etc */
|
|
|
409 int freq; /**< sample rate: sample frames per second */
|
|
|
410 } SDL_AudioSpec;
|
|
|
411
|
|
|
412 /**
|
|
|
413 * Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
|
|
|
414 *
|
|
|
415 * This reports on the size of an audio sample frame: stereo Sint16 data (2
|
|
|
416 * channels of 2 bytes each) would be 4 bytes per frame, for example.
|
|
|
417 *
|
|
|
418 * \param x an SDL_AudioSpec to query.
|
|
|
419 * \returns the number of bytes used per sample frame.
|
|
|
420 *
|
|
|
421 * \threadsafety It is safe to call this macro from any thread.
|
|
|
422 *
|
|
|
423 * \since This macro is available since SDL 3.2.0.
|
|
|
424 */
|
|
|
425 #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
|
|
|
426
|
|
|
427 /**
|
|
|
428 * The opaque handle that represents an audio stream.
|
|
|
429 *
|
|
|
430 * SDL_AudioStream is an audio conversion interface.
|
|
|
431 *
|
|
|
432 * - It can handle resampling data in chunks without generating artifacts,
|
|
|
433 * when it doesn't have the complete buffer available.
|
|
|
434 * - It can handle incoming data in any variable size.
|
|
|
435 * - It can handle input/output format changes on the fly.
|
|
|
436 * - It can remap audio channels between inputs and outputs.
|
|
|
437 * - You push data as you have it, and pull it when you need it
|
|
|
438 * - It can also function as a basic audio data queue even if you just have
|
|
|
439 * sound that needs to pass from one place to another.
|
|
|
440 * - You can hook callbacks up to them when more data is added or requested,
|
|
|
441 * to manage data on-the-fly.
|
|
|
442 *
|
|
|
443 * Audio streams are the core of the SDL3 audio interface. You create one or
|
|
|
444 * more of them, bind them to an opened audio device, and feed data to them
|
|
|
445 * (or for recording, consume data from them).
|
|
|
446 *
|
|
|
447 * \since This struct is available since SDL 3.2.0.
|
|
|
448 *
|
|
|
449 * \sa SDL_CreateAudioStream
|
|
|
450 */
|
|
|
451 typedef struct SDL_AudioStream SDL_AudioStream;
|
|
|
452
|
|
|
453
|
|
|
454 /* Function prototypes */
|
|
|
455
|
|
|
456 /**
|
|
|
457 * Use this function to get the number of built-in audio drivers.
|
|
|
458 *
|
|
|
459 * This function returns a hardcoded number. This never returns a negative
|
|
|
460 * value; if there are no drivers compiled into this build of SDL, this
|
|
|
461 * function returns zero. The presence of a driver in this list does not mean
|
|
|
462 * it will function, it just means SDL is capable of interacting with that
|
|
|
463 * interface. For example, a build of SDL might have esound support, but if
|
|
|
464 * there's no esound server available, SDL's esound driver would fail if used.
|
|
|
465 *
|
|
|
466 * By default, SDL tries all drivers, in its preferred order, until one is
|
|
|
467 * found to be usable.
|
|
|
468 *
|
|
|
469 * \returns the number of built-in audio drivers.
|
|
|
470 *
|
|
|
471 * \threadsafety It is safe to call this function from any thread.
|
|
|
472 *
|
|
|
473 * \since This function is available since SDL 3.2.0.
|
|
|
474 *
|
|
|
475 * \sa SDL_GetAudioDriver
|
|
|
476 */
|
|
|
477 extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
|
|
|
478
|
|
|
479 /**
|
|
|
480 * Use this function to get the name of a built in audio driver.
|
|
|
481 *
|
|
|
482 * The list of audio drivers is given in the order that they are normally
|
|
|
483 * initialized by default; the drivers that seem more reasonable to choose
|
|
|
484 * first (as far as the SDL developers believe) are earlier in the list.
|
|
|
485 *
|
|
|
486 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
|
|
|
487 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
|
|
|
488 * meant to be proper names.
|
|
|
489 *
|
|
|
490 * \param index the index of the audio driver; the value ranges from 0 to
|
|
|
491 * SDL_GetNumAudioDrivers() - 1.
|
|
|
492 * \returns the name of the audio driver at the requested index, or NULL if an
|
|
|
493 * invalid index was specified.
|
|
|
494 *
|
|
|
495 * \threadsafety It is safe to call this function from any thread.
|
|
|
496 *
|
|
|
497 * \since This function is available since SDL 3.2.0.
|
|
|
498 *
|
|
|
499 * \sa SDL_GetNumAudioDrivers
|
|
|
500 */
|
|
|
501 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
|
|
|
502
|
|
|
503 /**
|
|
|
504 * Get the name of the current audio driver.
|
|
|
505 *
|
|
|
506 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
|
|
|
507 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
|
|
|
508 * meant to be proper names.
|
|
|
509 *
|
|
|
510 * \returns the name of the current audio driver or NULL if no driver has been
|
|
|
511 * initialized.
|
|
|
512 *
|
|
|
513 * \threadsafety It is safe to call this function from any thread.
|
|
|
514 *
|
|
|
515 * \since This function is available since SDL 3.2.0.
|
|
|
516 */
|
|
|
517 extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
|
|
|
518
|
|
|
519 /**
|
|
|
520 * Get a list of currently-connected audio playback devices.
|
|
|
521 *
|
|
|
522 * This returns of list of available devices that play sound, perhaps to
|
|
|
523 * speakers or headphones ("playback" devices). If you want devices that
|
|
|
524 * record audio, like a microphone ("recording" devices), use
|
|
|
525 * SDL_GetAudioRecordingDevices() instead.
|
|
|
526 *
|
|
|
527 * This only returns a list of physical devices; it will not have any device
|
|
|
528 * IDs returned by SDL_OpenAudioDevice().
|
|
|
529 *
|
|
|
530 * If this function returns NULL, to signify an error, `*count` will be set to
|
|
|
531 * zero.
|
|
|
532 *
|
|
|
533 * \param count a pointer filled in with the number of devices returned, may
|
|
|
534 * be NULL.
|
|
|
535 * \returns a 0 terminated array of device instance IDs or NULL on error; call
|
|
|
536 * SDL_GetError() for more information. This should be freed with
|
|
|
537 * SDL_free() when it is no longer needed.
|
|
|
538 *
|
|
|
539 * \threadsafety It is safe to call this function from any thread.
|
|
|
540 *
|
|
|
541 * \since This function is available since SDL 3.2.0.
|
|
|
542 *
|
|
|
543 * \sa SDL_OpenAudioDevice
|
|
|
544 * \sa SDL_GetAudioRecordingDevices
|
|
|
545 */
|
|
|
546 extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
|
|
|
547
|
|
|
548 /**
|
|
|
549 * Get a list of currently-connected audio recording devices.
|
|
|
550 *
|
|
|
551 * This returns of list of available devices that record audio, like a
|
|
|
552 * microphone ("recording" devices). If you want devices that play sound,
|
|
|
553 * perhaps to speakers or headphones ("playback" devices), use
|
|
|
554 * SDL_GetAudioPlaybackDevices() instead.
|
|
|
555 *
|
|
|
556 * This only returns a list of physical devices; it will not have any device
|
|
|
557 * IDs returned by SDL_OpenAudioDevice().
|
|
|
558 *
|
|
|
559 * If this function returns NULL, to signify an error, `*count` will be set to
|
|
|
560 * zero.
|
|
|
561 *
|
|
|
562 * \param count a pointer filled in with the number of devices returned, may
|
|
|
563 * be NULL.
|
|
|
564 * \returns a 0 terminated array of device instance IDs, or NULL on failure;
|
|
|
565 * call SDL_GetError() for more information. This should be freed
|
|
|
566 * with SDL_free() when it is no longer needed.
|
|
|
567 *
|
|
|
568 * \threadsafety It is safe to call this function from any thread.
|
|
|
569 *
|
|
|
570 * \since This function is available since SDL 3.2.0.
|
|
|
571 *
|
|
|
572 * \sa SDL_OpenAudioDevice
|
|
|
573 * \sa SDL_GetAudioPlaybackDevices
|
|
|
574 */
|
|
|
575 extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
|
|
|
576
|
|
|
577 /**
|
|
|
578 * Get the human-readable name of a specific audio device.
|
|
|
579 *
|
|
|
580 * **WARNING**: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
|
|
|
581 * and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default
|
|
|
582 * physical devices' names. However, as the default device may change at any
|
|
|
583 * time, it is likely better to show a generic name to the user, like "System
|
|
|
584 * default audio device" or perhaps "default [currently %s]". Do not store
|
|
|
585 * this name to disk to reidentify the device in a later run of the program,
|
|
|
586 * as the default might change in general, and the string will be the name of
|
|
|
587 * a specific device and not the abstract system default.
|
|
|
588 *
|
|
|
589 * \param devid the instance ID of the device to query.
|
|
|
590 * \returns the name of the audio device, or NULL on failure; call
|
|
|
591 * SDL_GetError() for more information.
|
|
|
592 *
|
|
|
593 * \threadsafety It is safe to call this function from any thread.
|
|
|
594 *
|
|
|
595 * \since This function is available since SDL 3.2.0.
|
|
|
596 *
|
|
|
597 * \sa SDL_GetAudioPlaybackDevices
|
|
|
598 * \sa SDL_GetAudioRecordingDevices
|
|
|
599 */
|
|
|
600 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
|
|
|
601
|
|
|
602 /**
|
|
|
603 * Get the current audio format of a specific audio device.
|
|
|
604 *
|
|
|
605 * For an opened device, this will report the format the device is currently
|
|
|
606 * using. If the device isn't yet opened, this will report the device's
|
|
|
607 * preferred format (or a reasonable default if this can't be determined).
|
|
|
608 *
|
|
|
609 * You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
|
|
|
610 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a
|
|
|
611 * reasonable recommendation before opening the system-recommended default
|
|
|
612 * device.
|
|
|
613 *
|
|
|
614 * You can also use this to request the current device buffer size. This is
|
|
|
615 * specified in sample frames and represents the amount of data SDL will feed
|
|
|
616 * to the physical hardware in each chunk. This can be converted to
|
|
|
617 * milliseconds of audio with the following equation:
|
|
|
618 *
|
|
|
619 * `ms = (int) ((((Sint64) frames) * 1000) / spec.freq);`
|
|
|
620 *
|
|
|
621 * Buffer size is only important if you need low-level control over the audio
|
|
|
622 * playback timing. Most apps do not need this.
|
|
|
623 *
|
|
|
624 * \param devid the instance ID of the device to query.
|
|
|
625 * \param spec on return, will be filled with device details.
|
|
|
626 * \param sample_frames pointer to store device buffer size, in sample frames.
|
|
|
627 * Can be NULL.
|
|
|
628 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
629 * information.
|
|
|
630 *
|
|
|
631 * \threadsafety It is safe to call this function from any thread.
|
|
|
632 *
|
|
|
633 * \since This function is available since SDL 3.2.0.
|
|
|
634 */
|
|
|
635 extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames);
|
|
|
636
|
|
|
637 /**
|
|
|
638 * Get the current channel map of an audio device.
|
|
|
639 *
|
|
|
640 * Channel maps are optional; most things do not need them, instead passing
|
|
|
641 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
|
|
|
642 *
|
|
|
643 * Audio devices usually have no remapping applied. This is represented by
|
|
|
644 * returning NULL, and does not signify an error.
|
|
|
645 *
|
|
|
646 * \param devid the instance ID of the device to query.
|
|
|
647 * \param count On output, set to number of channels in the map. Can be NULL.
|
|
|
648 * \returns an array of the current channel mapping, with as many elements as
|
|
|
649 * the current output spec's channels, or NULL if default. This
|
|
|
650 * should be freed with SDL_free() when it is no longer needed.
|
|
|
651 *
|
|
|
652 * \threadsafety It is safe to call this function from any thread.
|
|
|
653 *
|
|
|
654 * \since This function is available since SDL 3.2.0.
|
|
|
655 *
|
|
|
656 * \sa SDL_SetAudioStreamInputChannelMap
|
|
|
657 */
|
|
|
658 extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
|
|
|
659
|
|
|
660 /**
|
|
|
661 * Open a specific audio device.
|
|
|
662 *
|
|
|
663 * You can open both playback and recording devices through this function.
|
|
|
664 * Playback devices will take data from bound audio streams, mix it, and send
|
|
|
665 * it to the hardware. Recording devices will feed any bound audio streams
|
|
|
666 * with a copy of any incoming data.
|
|
|
667 *
|
|
|
668 * An opened audio device starts out with no audio streams bound. To start
|
|
|
669 * audio playing, bind a stream and supply audio data to it. Unlike SDL2,
|
|
|
670 * there is no audio callback; you only bind audio streams and make sure they
|
|
|
671 * have data flowing into them (however, you can simulate SDL2's semantics
|
|
|
672 * fairly closely by using SDL_OpenAudioDeviceStream instead of this
|
|
|
673 * function).
|
|
|
674 *
|
|
|
675 * If you don't care about opening a specific device, pass a `devid` of either
|
|
|
676 * `SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK` or
|
|
|
677 * `SDL_AUDIO_DEVICE_DEFAULT_RECORDING`. In this case, SDL will try to pick
|
|
|
678 * the most reasonable default, and may also switch between physical devices
|
|
|
679 * seamlessly later, if the most reasonable default changes during the
|
|
|
680 * lifetime of this opened device (user changed the default in the OS's system
|
|
|
681 * preferences, the default got unplugged so the system jumped to a new
|
|
|
682 * default, the user plugged in headphones on a mobile device, etc). Unless
|
|
|
683 * you have a good reason to choose a specific device, this is probably what
|
|
|
684 * you want.
|
|
|
685 *
|
|
|
686 * You may request a specific format for the audio device, but there is no
|
|
|
687 * promise the device will honor that request for several reasons. As such,
|
|
|
688 * it's only meant to be a hint as to what data your app will provide. Audio
|
|
|
689 * streams will accept data in whatever format you specify and manage
|
|
|
690 * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
|
|
|
691 * the preferred format for the device before opening and the actual format
|
|
|
692 * the device is using after opening.
|
|
|
693 *
|
|
|
694 * It's legal to open the same device ID more than once; each successful open
|
|
|
695 * will generate a new logical SDL_AudioDeviceID that is managed separately
|
|
|
696 * from others on the same physical device. This allows libraries to open a
|
|
|
697 * device separately from the main app and bind its own streams without
|
|
|
698 * conflicting.
|
|
|
699 *
|
|
|
700 * It is also legal to open a device ID returned by a previous call to this
|
|
|
701 * function; doing so just creates another logical device on the same physical
|
|
|
702 * device. This may be useful for making logical groupings of audio streams.
|
|
|
703 *
|
|
|
704 * This function returns the opened device ID on success. This is a new,
|
|
|
705 * unique SDL_AudioDeviceID that represents a logical device.
|
|
|
706 *
|
|
|
707 * Some backends might offer arbitrary devices (for example, a networked audio
|
|
|
708 * protocol that can connect to an arbitrary server). For these, as a change
|
|
|
709 * from SDL2, you should open a default device ID and use an SDL hint to
|
|
|
710 * specify the target if you care, or otherwise let the backend figure out a
|
|
|
711 * reasonable default. Most backends don't offer anything like this, and often
|
|
|
712 * this would be an end user setting an environment variable for their custom
|
|
|
713 * need, and not something an application should specifically manage.
|
|
|
714 *
|
|
|
715 * When done with an audio device, possibly at the end of the app's life, one
|
|
|
716 * should call SDL_CloseAudioDevice() on the returned device id.
|
|
|
717 *
|
|
|
718 * \param devid the device instance id to open, or
|
|
|
719 * SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
|
|
|
720 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable
|
|
|
721 * default device.
|
|
|
722 * \param spec the requested device configuration. Can be NULL to use
|
|
|
723 * reasonable defaults.
|
|
|
724 * \returns the device ID on success or 0 on failure; call SDL_GetError() for
|
|
|
725 * more information.
|
|
|
726 *
|
|
|
727 * \threadsafety It is safe to call this function from any thread.
|
|
|
728 *
|
|
|
729 * \since This function is available since SDL 3.2.0.
|
|
|
730 *
|
|
|
731 * \sa SDL_CloseAudioDevice
|
|
|
732 * \sa SDL_GetAudioDeviceFormat
|
|
|
733 */
|
|
|
734 extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
|
|
|
735
|
|
|
736 /**
|
|
|
737 * Determine if an audio device is physical (instead of logical).
|
|
|
738 *
|
|
|
739 * An SDL_AudioDeviceID that represents physical hardware is a physical
|
|
|
740 * device; there is one for each piece of hardware that SDL can see. Logical
|
|
|
741 * devices are created by calling SDL_OpenAudioDevice or
|
|
|
742 * SDL_OpenAudioDeviceStream, and while each is associated with a physical
|
|
|
743 * device, there can be any number of logical devices on one physical device.
|
|
|
744 *
|
|
|
745 * For the most part, logical and physical IDs are interchangeable--if you try
|
|
|
746 * to open a logical device, SDL understands to assign that effort to the
|
|
|
747 * underlying physical device, etc. However, it might be useful to know if an
|
|
|
748 * arbitrary device ID is physical or logical. This function reports which.
|
|
|
749 *
|
|
|
750 * This function may return either true or false for invalid device IDs.
|
|
|
751 *
|
|
|
752 * \param devid the device ID to query.
|
|
|
753 * \returns true if devid is a physical device, false if it is logical.
|
|
|
754 *
|
|
|
755 * \threadsafety It is safe to call this function from any thread.
|
|
|
756 *
|
|
|
757 * \since This function is available since SDL 3.2.0.
|
|
|
758 */
|
|
|
759 extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid);
|
|
|
760
|
|
|
761 /**
|
|
|
762 * Determine if an audio device is a playback device (instead of recording).
|
|
|
763 *
|
|
|
764 * This function may return either true or false for invalid device IDs.
|
|
|
765 *
|
|
|
766 * \param devid the device ID to query.
|
|
|
767 * \returns true if devid is a playback device, false if it is recording.
|
|
|
768 *
|
|
|
769 * \threadsafety It is safe to call this function from any thread.
|
|
|
770 *
|
|
|
771 * \since This function is available since SDL 3.2.0.
|
|
|
772 */
|
|
|
773 extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid);
|
|
|
774
|
|
|
775 /**
|
|
|
776 * Use this function to pause audio playback on a specified device.
|
|
|
777 *
|
|
|
778 * This function pauses audio processing for a given device. Any bound audio
|
|
|
779 * streams will not progress, and no audio will be generated. Pausing one
|
|
|
780 * device does not prevent other unpaused devices from running.
|
|
|
781 *
|
|
|
782 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
|
|
|
783 * has to bind a stream before any audio will flow. Pausing a paused device is
|
|
|
784 * a legal no-op.
|
|
|
785 *
|
|
|
786 * Pausing a device can be useful to halt all audio without unbinding all the
|
|
|
787 * audio streams. This might be useful while a game is paused, or a level is
|
|
|
788 * loading, etc.
|
|
|
789 *
|
|
|
790 * Physical devices can not be paused or unpaused, only logical devices
|
|
|
791 * created through SDL_OpenAudioDevice() can be.
|
|
|
792 *
|
|
|
793 * \param devid a device opened by SDL_OpenAudioDevice().
|
|
|
794 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
795 * information.
|
|
|
796 *
|
|
|
797 * \threadsafety It is safe to call this function from any thread.
|
|
|
798 *
|
|
|
799 * \since This function is available since SDL 3.2.0.
|
|
|
800 *
|
|
|
801 * \sa SDL_ResumeAudioDevice
|
|
|
802 * \sa SDL_AudioDevicePaused
|
|
|
803 */
|
|
|
804 extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID devid);
|
|
|
805
|
|
|
806 /**
|
|
|
807 * Use this function to unpause audio playback on a specified device.
|
|
|
808 *
|
|
|
809 * This function unpauses audio processing for a given device that has
|
|
|
810 * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
|
|
|
811 * bound audio streams will begin to progress again, and audio can be
|
|
|
812 * generated.
|
|
|
813 *
|
|
|
814 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
|
|
|
815 * has to bind a stream before any audio will flow. Unpausing an unpaused
|
|
|
816 * device is a legal no-op.
|
|
|
817 *
|
|
|
818 * Physical devices can not be paused or unpaused, only logical devices
|
|
|
819 * created through SDL_OpenAudioDevice() can be.
|
|
|
820 *
|
|
|
821 * \param devid a device opened by SDL_OpenAudioDevice().
|
|
|
822 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
823 * information.
|
|
|
824 *
|
|
|
825 * \threadsafety It is safe to call this function from any thread.
|
|
|
826 *
|
|
|
827 * \since This function is available since SDL 3.2.0.
|
|
|
828 *
|
|
|
829 * \sa SDL_AudioDevicePaused
|
|
|
830 * \sa SDL_PauseAudioDevice
|
|
|
831 */
|
|
|
832 extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID devid);
|
|
|
833
|
|
|
834 /**
|
|
|
835 * Use this function to query if an audio device is paused.
|
|
|
836 *
|
|
|
837 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
|
|
|
838 * has to bind a stream before any audio will flow.
|
|
|
839 *
|
|
|
840 * Physical devices can not be paused or unpaused, only logical devices
|
|
|
841 * created through SDL_OpenAudioDevice() can be. Physical and invalid device
|
|
|
842 * IDs will report themselves as unpaused here.
|
|
|
843 *
|
|
|
844 * \param devid a device opened by SDL_OpenAudioDevice().
|
|
|
845 * \returns true if device is valid and paused, false otherwise.
|
|
|
846 *
|
|
|
847 * \threadsafety It is safe to call this function from any thread.
|
|
|
848 *
|
|
|
849 * \since This function is available since SDL 3.2.0.
|
|
|
850 *
|
|
|
851 * \sa SDL_PauseAudioDevice
|
|
|
852 * \sa SDL_ResumeAudioDevice
|
|
|
853 */
|
|
|
854 extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID devid);
|
|
|
855
|
|
|
856 /**
|
|
|
857 * Get the gain of an audio device.
|
|
|
858 *
|
|
|
859 * The gain of a device is its volume; a larger gain means a louder output,
|
|
|
860 * with a gain of zero being silence.
|
|
|
861 *
|
|
|
862 * Audio devices default to a gain of 1.0f (no change in output).
|
|
|
863 *
|
|
|
864 * Physical devices may not have their gain changed, only logical devices, and
|
|
|
865 * this function will always return -1.0f when used on physical devices.
|
|
|
866 *
|
|
|
867 * \param devid the audio device to query.
|
|
|
868 * \returns the gain of the device or -1.0f on failure; call SDL_GetError()
|
|
|
869 * for more information.
|
|
|
870 *
|
|
|
871 * \threadsafety It is safe to call this function from any thread.
|
|
|
872 *
|
|
|
873 * \since This function is available since SDL 3.2.0.
|
|
|
874 *
|
|
|
875 * \sa SDL_SetAudioDeviceGain
|
|
|
876 */
|
|
|
877 extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid);
|
|
|
878
|
|
|
879 /**
|
|
|
880 * Change the gain of an audio device.
|
|
|
881 *
|
|
|
882 * The gain of a device is its volume; a larger gain means a louder output,
|
|
|
883 * with a gain of zero being silence.
|
|
|
884 *
|
|
|
885 * Audio devices default to a gain of 1.0f (no change in output).
|
|
|
886 *
|
|
|
887 * Physical devices may not have their gain changed, only logical devices, and
|
|
|
888 * this function will always return false when used on physical devices. While
|
|
|
889 * it might seem attractive to adjust several logical devices at once in this
|
|
|
890 * way, it would allow an app or library to interfere with another portion of
|
|
|
891 * the program's otherwise-isolated devices.
|
|
|
892 *
|
|
|
893 * This is applied, along with any per-audiostream gain, during playback to
|
|
|
894 * the hardware, and can be continuously changed to create various effects. On
|
|
|
895 * recording devices, this will adjust the gain before passing the data into
|
|
|
896 * an audiostream; that recording audiostream can then adjust its gain further
|
|
|
897 * when outputting the data elsewhere, if it likes, but that second gain is
|
|
|
898 * not applied until the data leaves the audiostream again.
|
|
|
899 *
|
|
|
900 * \param devid the audio device on which to change gain.
|
|
|
901 * \param gain the gain. 1.0f is no change, 0.0f is silence.
|
|
|
902 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
903 * information.
|
|
|
904 *
|
|
|
905 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
906 * a stream-specific mutex while running.
|
|
|
907 *
|
|
|
908 * \since This function is available since SDL 3.2.0.
|
|
|
909 *
|
|
|
910 * \sa SDL_GetAudioDeviceGain
|
|
|
911 */
|
|
|
912 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain);
|
|
|
913
|
|
|
914 /**
|
|
|
915 * Close a previously-opened audio device.
|
|
|
916 *
|
|
|
917 * The application should close open audio devices once they are no longer
|
|
|
918 * needed.
|
|
|
919 *
|
|
|
920 * This function may block briefly while pending audio data is played by the
|
|
|
921 * hardware, so that applications don't drop the last buffer of data they
|
|
|
922 * supplied if terminating immediately afterwards.
|
|
|
923 *
|
|
|
924 * \param devid an audio device id previously returned by
|
|
|
925 * SDL_OpenAudioDevice().
|
|
|
926 *
|
|
|
927 * \threadsafety It is safe to call this function from any thread.
|
|
|
928 *
|
|
|
929 * \since This function is available since SDL 3.2.0.
|
|
|
930 *
|
|
|
931 * \sa SDL_OpenAudioDevice
|
|
|
932 */
|
|
|
933 extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
|
|
|
934
|
|
|
935 /**
|
|
|
936 * Bind a list of audio streams to an audio device.
|
|
|
937 *
|
|
|
938 * Audio data will flow through any bound streams. For a playback device, data
|
|
|
939 * for all bound streams will be mixed together and fed to the device. For a
|
|
|
940 * recording device, a copy of recorded data will be provided to each bound
|
|
|
941 * stream.
|
|
|
942 *
|
|
|
943 * Audio streams can only be bound to an open device. This operation is
|
|
|
944 * atomic--all streams bound in the same call will start processing at the
|
|
|
945 * same time, so they can stay in sync. Also: either all streams will be bound
|
|
|
946 * or none of them will be.
|
|
|
947 *
|
|
|
948 * It is an error to bind an already-bound stream; it must be explicitly
|
|
|
949 * unbound first.
|
|
|
950 *
|
|
|
951 * Binding a stream to a device will set its output format for playback
|
|
|
952 * devices, and its input format for recording devices, so they match the
|
|
|
953 * device's settings. The caller is welcome to change the other end of the
|
|
|
954 * stream's format at any time with SDL_SetAudioStreamFormat(). If the other
|
|
|
955 * end of the stream's format has never been set (the audio stream was created
|
|
|
956 * with a NULL audio spec), this function will set it to match the device
|
|
|
957 * end's format.
|
|
|
958 *
|
|
|
959 * \param devid an audio device to bind a stream to.
|
|
|
960 * \param streams an array of audio streams to bind.
|
|
|
961 * \param num_streams number streams listed in the `streams` array.
|
|
|
962 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
963 * information.
|
|
|
964 *
|
|
|
965 * \threadsafety It is safe to call this function from any thread.
|
|
|
966 *
|
|
|
967 * \since This function is available since SDL 3.2.0.
|
|
|
968 *
|
|
|
969 * \sa SDL_BindAudioStreams
|
|
|
970 * \sa SDL_UnbindAudioStream
|
|
|
971 * \sa SDL_GetAudioStreamDevice
|
|
|
972 */
|
|
|
973 extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams);
|
|
|
974
|
|
|
975 /**
|
|
|
976 * Bind a single audio stream to an audio device.
|
|
|
977 *
|
|
|
978 * This is a convenience function, equivalent to calling
|
|
|
979 * `SDL_BindAudioStreams(devid, &stream, 1)`.
|
|
|
980 *
|
|
|
981 * \param devid an audio device to bind a stream to.
|
|
|
982 * \param stream an audio stream to bind to a device.
|
|
|
983 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
984 * information.
|
|
|
985 *
|
|
|
986 * \threadsafety It is safe to call this function from any thread.
|
|
|
987 *
|
|
|
988 * \since This function is available since SDL 3.2.0.
|
|
|
989 *
|
|
|
990 * \sa SDL_BindAudioStreams
|
|
|
991 * \sa SDL_UnbindAudioStream
|
|
|
992 * \sa SDL_GetAudioStreamDevice
|
|
|
993 */
|
|
|
994 extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
|
|
|
995
|
|
|
996 /**
|
|
|
997 * Unbind a list of audio streams from their audio devices.
|
|
|
998 *
|
|
|
999 * The streams being unbound do not all have to be on the same device. All
|
|
|
1000 * streams on the same device will be unbound atomically (data will stop
|
|
|
1001 * flowing through all unbound streams on the same device at the same time).
|
|
|
1002 *
|
|
|
1003 * Unbinding a stream that isn't bound to a device is a legal no-op.
|
|
|
1004 *
|
|
|
1005 * \param streams an array of audio streams to unbind. Can be NULL or contain
|
|
|
1006 * NULL.
|
|
|
1007 * \param num_streams number streams listed in the `streams` array.
|
|
|
1008 *
|
|
|
1009 * \threadsafety It is safe to call this function from any thread.
|
|
|
1010 *
|
|
|
1011 * \since This function is available since SDL 3.2.0.
|
|
|
1012 *
|
|
|
1013 * \sa SDL_BindAudioStreams
|
|
|
1014 */
|
|
|
1015 extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams);
|
|
|
1016
|
|
|
1017 /**
|
|
|
1018 * Unbind a single audio stream from its audio device.
|
|
|
1019 *
|
|
|
1020 * This is a convenience function, equivalent to calling
|
|
|
1021 * `SDL_UnbindAudioStreams(&stream, 1)`.
|
|
|
1022 *
|
|
|
1023 * \param stream an audio stream to unbind from a device. Can be NULL.
|
|
|
1024 *
|
|
|
1025 * \threadsafety It is safe to call this function from any thread.
|
|
|
1026 *
|
|
|
1027 * \since This function is available since SDL 3.2.0.
|
|
|
1028 *
|
|
|
1029 * \sa SDL_BindAudioStream
|
|
|
1030 */
|
|
|
1031 extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
|
|
|
1032
|
|
|
1033 /**
|
|
|
1034 * Query an audio stream for its currently-bound device.
|
|
|
1035 *
|
|
|
1036 * This reports the logical audio device that an audio stream is currently
|
|
|
1037 * bound to.
|
|
|
1038 *
|
|
|
1039 * If not bound, or invalid, this returns zero, which is not a valid device
|
|
|
1040 * ID.
|
|
|
1041 *
|
|
|
1042 * \param stream the audio stream to query.
|
|
|
1043 * \returns the bound audio device, or 0 if not bound or invalid.
|
|
|
1044 *
|
|
|
1045 * \threadsafety It is safe to call this function from any thread.
|
|
|
1046 *
|
|
|
1047 * \since This function is available since SDL 3.2.0.
|
|
|
1048 *
|
|
|
1049 * \sa SDL_BindAudioStream
|
|
|
1050 * \sa SDL_BindAudioStreams
|
|
|
1051 */
|
|
|
1052 extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream);
|
|
|
1053
|
|
|
1054 /**
|
|
|
1055 * Create a new audio stream.
|
|
|
1056 *
|
|
|
1057 * \param src_spec the format details of the input audio.
|
|
|
1058 * \param dst_spec the format details of the output audio.
|
|
|
1059 * \returns a new audio stream on success or NULL on failure; call
|
|
|
1060 * SDL_GetError() for more information.
|
|
|
1061 *
|
|
|
1062 * \threadsafety It is safe to call this function from any thread.
|
|
|
1063 *
|
|
|
1064 * \since This function is available since SDL 3.2.0.
|
|
|
1065 *
|
|
|
1066 * \sa SDL_PutAudioStreamData
|
|
|
1067 * \sa SDL_GetAudioStreamData
|
|
|
1068 * \sa SDL_GetAudioStreamAvailable
|
|
|
1069 * \sa SDL_FlushAudioStream
|
|
|
1070 * \sa SDL_ClearAudioStream
|
|
|
1071 * \sa SDL_SetAudioStreamFormat
|
|
|
1072 * \sa SDL_DestroyAudioStream
|
|
|
1073 */
|
|
|
1074 extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
|
|
|
1075
|
|
|
1076 /**
|
|
|
1077 * Get the properties associated with an audio stream.
|
|
|
1078 *
|
|
|
1079 * The application can hang any data it wants here, but the following
|
|
|
1080 * properties are understood by SDL:
|
|
|
1081 *
|
|
|
1082 * - `SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN`: if true (the default), the
|
|
|
1083 * stream be automatically cleaned up when the audio subsystem quits. If set
|
|
|
1084 * to false, the streams will persist beyond that. This property is ignored
|
|
|
1085 * for streams created through SDL_OpenAudioDeviceStream(), and will always
|
|
|
1086 * be cleaned up. Streams that are not cleaned up will still be unbound from
|
|
|
1087 * devices when the audio subsystem quits. This property was added in SDL
|
|
|
1088 * 3.4.0.
|
|
|
1089 *
|
|
|
1090 * \param stream the SDL_AudioStream to query.
|
|
|
1091 * \returns a valid property ID on success or 0 on failure; call
|
|
|
1092 * SDL_GetError() for more information.
|
|
|
1093 *
|
|
|
1094 * \threadsafety It is safe to call this function from any thread.
|
|
|
1095 *
|
|
|
1096 * \since This function is available since SDL 3.2.0.
|
|
|
1097 */
|
|
|
1098 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);
|
|
|
1099
|
|
|
1100 #define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN "SDL.audiostream.auto_cleanup"
|
|
|
1101
|
|
|
1102
|
|
|
1103 /**
|
|
|
1104 * Query the current format of an audio stream.
|
|
|
1105 *
|
|
|
1106 * \param stream the SDL_AudioStream to query.
|
|
|
1107 * \param src_spec where to store the input audio format; ignored if NULL.
|
|
|
1108 * \param dst_spec where to store the output audio format; ignored if NULL.
|
|
|
1109 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1110 * information.
|
|
|
1111 *
|
|
|
1112 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1113 * a stream-specific mutex while running.
|
|
|
1114 *
|
|
|
1115 * \since This function is available since SDL 3.2.0.
|
|
|
1116 *
|
|
|
1117 * \sa SDL_SetAudioStreamFormat
|
|
|
1118 */
|
|
|
1119 extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec);
|
|
|
1120
|
|
|
1121 /**
|
|
|
1122 * Change the input and output formats of an audio stream.
|
|
|
1123 *
|
|
|
1124 * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData
|
|
|
1125 * will reflect the new format, and future calls to SDL_PutAudioStreamData
|
|
|
1126 * must provide data in the new input formats.
|
|
|
1127 *
|
|
|
1128 * Data that was previously queued in the stream will still be operated on in
|
|
|
1129 * the format that was current when it was added, which is to say you can put
|
|
|
1130 * the end of a sound file in one format to a stream, change formats for the
|
|
|
1131 * next sound file, and start putting that new data while the previous sound
|
|
|
1132 * file is still queued, and everything will still play back correctly.
|
|
|
1133 *
|
|
|
1134 * If a stream is bound to a device, then the format of the side of the stream
|
|
|
1135 * bound to a device cannot be changed (src_spec for recording devices,
|
|
|
1136 * dst_spec for playback devices). Attempts to make a change to this side will
|
|
|
1137 * be ignored, but this will not report an error. The other side's format can
|
|
|
1138 * be changed.
|
|
|
1139 *
|
|
|
1140 * \param stream the stream the format is being changed.
|
|
|
1141 * \param src_spec the new format of the audio input; if NULL, it is not
|
|
|
1142 * changed.
|
|
|
1143 * \param dst_spec the new format of the audio output; if NULL, it is not
|
|
|
1144 * changed.
|
|
|
1145 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1146 * information.
|
|
|
1147 *
|
|
|
1148 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1149 * a stream-specific mutex while running.
|
|
|
1150 *
|
|
|
1151 * \since This function is available since SDL 3.2.0.
|
|
|
1152 *
|
|
|
1153 * \sa SDL_GetAudioStreamFormat
|
|
|
1154 * \sa SDL_SetAudioStreamFrequencyRatio
|
|
|
1155 */
|
|
|
1156 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
|
|
|
1157
|
|
|
1158 /**
|
|
|
1159 * Get the frequency ratio of an audio stream.
|
|
|
1160 *
|
|
|
1161 * \param stream the SDL_AudioStream to query.
|
|
|
1162 * \returns the frequency ratio of the stream or 0.0 on failure; call
|
|
|
1163 * SDL_GetError() for more information.
|
|
|
1164 *
|
|
|
1165 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1166 * a stream-specific mutex while running.
|
|
|
1167 *
|
|
|
1168 * \since This function is available since SDL 3.2.0.
|
|
|
1169 *
|
|
|
1170 * \sa SDL_SetAudioStreamFrequencyRatio
|
|
|
1171 */
|
|
|
1172 extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream);
|
|
|
1173
|
|
|
1174 /**
|
|
|
1175 * Change the frequency ratio of an audio stream.
|
|
|
1176 *
|
|
|
1177 * The frequency ratio is used to adjust the rate at which input data is
|
|
|
1178 * consumed. Changing this effectively modifies the speed and pitch of the
|
|
|
1179 * audio. A value greater than 1.0f will play the audio faster, and at a
|
|
|
1180 * higher pitch. A value less than 1.0f will play the audio slower, and at a
|
|
|
1181 * lower pitch. 1.0f means play at normal speed.
|
|
|
1182 *
|
|
|
1183 * This is applied during SDL_GetAudioStreamData, and can be continuously
|
|
|
1184 * changed to create various effects.
|
|
|
1185 *
|
|
|
1186 * \param stream the stream on which the frequency ratio is being changed.
|
|
|
1187 * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
|
|
|
1188 * and 100.
|
|
|
1189 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1190 * information.
|
|
|
1191 *
|
|
|
1192 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1193 * a stream-specific mutex while running.
|
|
|
1194 *
|
|
|
1195 * \since This function is available since SDL 3.2.0.
|
|
|
1196 *
|
|
|
1197 * \sa SDL_GetAudioStreamFrequencyRatio
|
|
|
1198 * \sa SDL_SetAudioStreamFormat
|
|
|
1199 */
|
|
|
1200 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio);
|
|
|
1201
|
|
|
1202 /**
|
|
|
1203 * Get the gain of an audio stream.
|
|
|
1204 *
|
|
|
1205 * The gain of a stream is its volume; a larger gain means a louder output,
|
|
|
1206 * with a gain of zero being silence.
|
|
|
1207 *
|
|
|
1208 * Audio streams default to a gain of 1.0f (no change in output).
|
|
|
1209 *
|
|
|
1210 * \param stream the SDL_AudioStream to query.
|
|
|
1211 * \returns the gain of the stream or -1.0f on failure; call SDL_GetError()
|
|
|
1212 * for more information.
|
|
|
1213 *
|
|
|
1214 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1215 * a stream-specific mutex while running.
|
|
|
1216 *
|
|
|
1217 * \since This function is available since SDL 3.2.0.
|
|
|
1218 *
|
|
|
1219 * \sa SDL_SetAudioStreamGain
|
|
|
1220 */
|
|
|
1221 extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream);
|
|
|
1222
|
|
|
1223 /**
|
|
|
1224 * Change the gain of an audio stream.
|
|
|
1225 *
|
|
|
1226 * The gain of a stream is its volume; a larger gain means a louder output,
|
|
|
1227 * with a gain of zero being silence.
|
|
|
1228 *
|
|
|
1229 * Audio streams default to a gain of 1.0f (no change in output).
|
|
|
1230 *
|
|
|
1231 * This is applied during SDL_GetAudioStreamData, and can be continuously
|
|
|
1232 * changed to create various effects.
|
|
|
1233 *
|
|
|
1234 * \param stream the stream on which the gain is being changed.
|
|
|
1235 * \param gain the gain. 1.0f is no change, 0.0f is silence.
|
|
|
1236 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1237 * information.
|
|
|
1238 *
|
|
|
1239 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1240 * a stream-specific mutex while running.
|
|
|
1241 *
|
|
|
1242 * \since This function is available since SDL 3.2.0.
|
|
|
1243 *
|
|
|
1244 * \sa SDL_GetAudioStreamGain
|
|
|
1245 */
|
|
|
1246 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain);
|
|
|
1247
|
|
|
1248 /**
|
|
|
1249 * Get the current input channel map of an audio stream.
|
|
|
1250 *
|
|
|
1251 * Channel maps are optional; most things do not need them, instead passing
|
|
|
1252 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
|
|
|
1253 *
|
|
|
1254 * Audio streams default to no remapping applied. This is represented by
|
|
|
1255 * returning NULL, and does not signify an error.
|
|
|
1256 *
|
|
|
1257 * \param stream the SDL_AudioStream to query.
|
|
|
1258 * \param count On output, set to number of channels in the map. Can be NULL.
|
|
|
1259 * \returns an array of the current channel mapping, with as many elements as
|
|
|
1260 * the current output spec's channels, or NULL if default. This
|
|
|
1261 * should be freed with SDL_free() when it is no longer needed.
|
|
|
1262 *
|
|
|
1263 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1264 * a stream-specific mutex while running.
|
|
|
1265 *
|
|
|
1266 * \since This function is available since SDL 3.2.0.
|
|
|
1267 *
|
|
|
1268 * \sa SDL_SetAudioStreamInputChannelMap
|
|
|
1269 */
|
|
|
1270 extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
|
|
|
1271
|
|
|
1272 /**
|
|
|
1273 * Get the current output channel map of an audio stream.
|
|
|
1274 *
|
|
|
1275 * Channel maps are optional; most things do not need them, instead passing
|
|
|
1276 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
|
|
|
1277 *
|
|
|
1278 * Audio streams default to no remapping applied. This is represented by
|
|
|
1279 * returning NULL, and does not signify an error.
|
|
|
1280 *
|
|
|
1281 * \param stream the SDL_AudioStream to query.
|
|
|
1282 * \param count On output, set to number of channels in the map. Can be NULL.
|
|
|
1283 * \returns an array of the current channel mapping, with as many elements as
|
|
|
1284 * the current output spec's channels, or NULL if default. This
|
|
|
1285 * should be freed with SDL_free() when it is no longer needed.
|
|
|
1286 *
|
|
|
1287 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1288 * a stream-specific mutex while running.
|
|
|
1289 *
|
|
|
1290 * \since This function is available since SDL 3.2.0.
|
|
|
1291 *
|
|
|
1292 * \sa SDL_SetAudioStreamInputChannelMap
|
|
|
1293 */
|
|
|
1294 extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
|
|
|
1295
|
|
|
1296 /**
|
|
|
1297 * Set the current input channel map of an audio stream.
|
|
|
1298 *
|
|
|
1299 * Channel maps are optional; most things do not need them, instead passing
|
|
|
1300 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
|
|
|
1301 *
|
|
|
1302 * The input channel map reorders data that is added to a stream via
|
|
|
1303 * SDL_PutAudioStreamData. Future calls to SDL_PutAudioStreamData must provide
|
|
|
1304 * data in the new channel order.
|
|
|
1305 *
|
|
|
1306 * Each item in the array represents an input channel, and its value is the
|
|
|
1307 * channel that it should be remapped to. To reverse a stereo signal's left
|
|
|
1308 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
|
|
|
1309 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
|
|
|
1310 * right channel to both channels of a stereo signal. An element in the
|
|
|
1311 * channel map set to -1 instead of a valid channel will mute that channel,
|
|
|
1312 * setting it to a silence value.
|
|
|
1313 *
|
|
|
1314 * You cannot change the number of channels through a channel map, just
|
|
|
1315 * reorder/mute them.
|
|
|
1316 *
|
|
|
1317 * Data that was previously queued in the stream will still be operated on in
|
|
|
1318 * the order that was current when it was added, which is to say you can put
|
|
|
1319 * the end of a sound file in one order to a stream, change orders for the
|
|
|
1320 * next sound file, and start putting that new data while the previous sound
|
|
|
1321 * file is still queued, and everything will still play back correctly.
|
|
|
1322 *
|
|
|
1323 * Audio streams default to no remapping applied. Passing a NULL channel map
|
|
|
1324 * is legal, and turns off remapping.
|
|
|
1325 *
|
|
|
1326 * SDL will copy the channel map; the caller does not have to save this array
|
|
|
1327 * after this call.
|
|
|
1328 *
|
|
|
1329 * If `count` is not equal to the current number of channels in the audio
|
|
|
1330 * stream's format, this will fail. This is a safety measure to make sure a
|
|
|
1331 * race condition hasn't changed the format while this call is setting the
|
|
|
1332 * channel map.
|
|
|
1333 *
|
|
|
1334 * Unlike attempting to change the stream's format, the input channel map on a
|
|
|
1335 * stream bound to a recording device is permitted to change at any time; any
|
|
|
1336 * data added to the stream from the device after this call will have the new
|
|
|
1337 * mapping, but previously-added data will still have the prior mapping.
|
|
|
1338 *
|
|
|
1339 * \param stream the SDL_AudioStream to change.
|
|
|
1340 * \param chmap the new channel map, NULL to reset to default.
|
|
|
1341 * \param count The number of channels in the map.
|
|
|
1342 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1343 * information.
|
|
|
1344 *
|
|
|
1345 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1346 * a stream-specific mutex while running. Don't change the
|
|
|
1347 * stream's format to have a different number of channels from a
|
|
|
1348 * different thread at the same time, though!
|
|
|
1349 *
|
|
|
1350 * \since This function is available since SDL 3.2.0.
|
|
|
1351 *
|
|
|
1352 * \sa SDL_SetAudioStreamInputChannelMap
|
|
|
1353 */
|
|
|
1354 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
|
|
|
1355
|
|
|
1356 /**
|
|
|
1357 * Set the current output channel map of an audio stream.
|
|
|
1358 *
|
|
|
1359 * Channel maps are optional; most things do not need them, instead passing
|
|
|
1360 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
|
|
|
1361 *
|
|
|
1362 * The output channel map reorders data that is leaving a stream via
|
|
|
1363 * SDL_GetAudioStreamData.
|
|
|
1364 *
|
|
|
1365 * Each item in the array represents an input channel, and its value is the
|
|
|
1366 * channel that it should be remapped to. To reverse a stereo signal's left
|
|
|
1367 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
|
|
|
1368 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
|
|
|
1369 * right channel to both channels of a stereo signal. An element in the
|
|
|
1370 * channel map set to -1 instead of a valid channel will mute that channel,
|
|
|
1371 * setting it to a silence value.
|
|
|
1372 *
|
|
|
1373 * You cannot change the number of channels through a channel map, just
|
|
|
1374 * reorder/mute them.
|
|
|
1375 *
|
|
|
1376 * The output channel map can be changed at any time, as output remapping is
|
|
|
1377 * applied during SDL_GetAudioStreamData.
|
|
|
1378 *
|
|
|
1379 * Audio streams default to no remapping applied. Passing a NULL channel map
|
|
|
1380 * is legal, and turns off remapping.
|
|
|
1381 *
|
|
|
1382 * SDL will copy the channel map; the caller does not have to save this array
|
|
|
1383 * after this call.
|
|
|
1384 *
|
|
|
1385 * If `count` is not equal to the current number of channels in the audio
|
|
|
1386 * stream's format, this will fail. This is a safety measure to make sure a
|
|
|
1387 * race condition hasn't changed the format while this call is setting the
|
|
|
1388 * channel map.
|
|
|
1389 *
|
|
|
1390 * Unlike attempting to change the stream's format, the output channel map on
|
|
|
1391 * a stream bound to a recording device is permitted to change at any time;
|
|
|
1392 * any data added to the stream after this call will have the new mapping, but
|
|
|
1393 * previously-added data will still have the prior mapping. When the channel
|
|
|
1394 * map doesn't match the hardware's channel layout, SDL will convert the data
|
|
|
1395 * before feeding it to the device for playback.
|
|
|
1396 *
|
|
|
1397 * \param stream the SDL_AudioStream to change.
|
|
|
1398 * \param chmap the new channel map, NULL to reset to default.
|
|
|
1399 * \param count The number of channels in the map.
|
|
|
1400 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1401 * information.
|
|
|
1402 *
|
|
|
1403 * \threadsafety It is safe to call this function from any thread, as it holds
|
|
|
1404 * a stream-specific mutex while running. Don't change the
|
|
|
1405 * stream's format to have a different number of channels from a
|
|
|
1406 * a different thread at the same time, though!
|
|
|
1407 *
|
|
|
1408 * \since This function is available since SDL 3.2.0.
|
|
|
1409 *
|
|
|
1410 * \sa SDL_SetAudioStreamInputChannelMap
|
|
|
1411 */
|
|
|
1412 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
|
|
|
1413
|
|
|
1414 /**
|
|
|
1415 * Add data to the stream.
|
|
|
1416 *
|
|
|
1417 * This data must match the format/channels/samplerate specified in the latest
|
|
|
1418 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
|
|
|
1419 * stream if it hasn't been changed.
|
|
|
1420 *
|
|
|
1421 * Note that this call simply copies the unconverted data for later. This is
|
|
|
1422 * different than SDL2, where data was converted during the Put call and the
|
|
|
1423 * Get call would just dequeue the previously-converted data.
|
|
|
1424 *
|
|
|
1425 * \param stream the stream the audio data is being added to.
|
|
|
1426 * \param buf a pointer to the audio data to add.
|
|
|
1427 * \param len the number of bytes to write to the stream.
|
|
|
1428 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1429 * information.
|
|
|
1430 *
|
|
|
1431 * \threadsafety It is safe to call this function from any thread, but if the
|
|
|
1432 * stream has a callback set, the caller might need to manage
|
|
|
1433 * extra locking.
|
|
|
1434 *
|
|
|
1435 * \since This function is available since SDL 3.2.0.
|
|
|
1436 *
|
|
|
1437 * \sa SDL_ClearAudioStream
|
|
|
1438 * \sa SDL_FlushAudioStream
|
|
|
1439 * \sa SDL_GetAudioStreamData
|
|
|
1440 * \sa SDL_GetAudioStreamQueued
|
|
|
1441 */
|
|
|
1442 extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
|
|
|
1443
|
|
|
1444 /**
|
|
|
1445 * A callback that fires for completed SDL_PutAudioStreamDataNoCopy() data.
|
|
|
1446 *
|
|
|
1447 * When using SDL_PutAudioStreamDataNoCopy() to provide data to an
|
|
|
1448 * SDL_AudioStream, it's not safe to dispose of the data until the stream has
|
|
|
1449 * completely consumed it. Often times it's difficult to know exactly when
|
|
|
1450 * this has happened.
|
|
|
1451 *
|
|
|
1452 * This callback fires once when the stream no longer needs the buffer,
|
|
|
1453 * allowing the app to easily free or reuse it.
|
|
|
1454 *
|
|
|
1455 * \param userdata an opaque pointer provided by the app for their personal
|
|
|
1456 * use.
|
|
|
1457 * \param buf the pointer provided to SDL_PutAudioStreamDataNoCopy().
|
|
|
1458 * \param buflen the size of buffer, in bytes, provided to
|
|
|
1459 * SDL_PutAudioStreamDataNoCopy().
|
|
|
1460 *
|
|
|
1461 * \threadsafety This callbacks may run from any thread, so if you need to
|
|
|
1462 * protect shared data, you should use SDL_LockAudioStream to
|
|
|
1463 * serialize access; this lock will be held before your callback
|
|
|
1464 * is called, so your callback does not need to manage the lock
|
|
|
1465 * explicitly.
|
|
|
1466 *
|
|
|
1467 * \since This datatype is available since SDL 3.4.0.
|
|
|
1468 *
|
|
|
1469 * \sa SDL_SetAudioStreamGetCallback
|
|
|
1470 * \sa SDL_SetAudioStreamPutCallback
|
|
|
1471 */
|
|
|
1472 typedef void (SDLCALL *SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen);
|
|
|
1473
|
|
|
1474 /**
|
|
|
1475 * Add external data to an audio stream without copying it.
|
|
|
1476 *
|
|
|
1477 * Unlike SDL_PutAudioStreamData(), this function does not make a copy of the
|
|
|
1478 * provided data, instead storing the provided pointer. This means that the
|
|
|
1479 * put operation does not need to allocate and copy the data, but the original
|
|
|
1480 * data must remain available until the stream is done with it, either by
|
|
|
1481 * being read from the stream in its entirety, or a call to
|
|
|
1482 * SDL_ClearAudioStream() or SDL_DestroyAudioStream().
|
|
|
1483 *
|
|
|
1484 * The data must match the format/channels/samplerate specified in the latest
|
|
|
1485 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
|
|
|
1486 * stream if it hasn't been changed.
|
|
|
1487 *
|
|
|
1488 * An optional callback may be provided, which is called when the stream no
|
|
|
1489 * longer needs the data. Once this callback fires, the stream will not access
|
|
|
1490 * the data again. This callback will fire for any reason the data is no
|
|
|
1491 * longer needed, including clearing or destroying the stream.
|
|
|
1492 *
|
|
|
1493 * Note that there is still an allocation to store tracking information, so
|
|
|
1494 * this function is more efficient for larger blocks of data. If you're
|
|
|
1495 * planning to put a few samples at a time, it will be more efficient to use
|
|
|
1496 * SDL_PutAudioStreamData(), which allocates and buffers in blocks.
|
|
|
1497 *
|
|
|
1498 * \param stream the stream the audio data is being added to.
|
|
|
1499 * \param buf a pointer to the audio data to add.
|
|
|
1500 * \param len the number of bytes to add to the stream.
|
|
|
1501 * \param callback the callback function to call when the data is no longer
|
|
|
1502 * needed by the stream. May be NULL.
|
|
|
1503 * \param userdata an opaque pointer provided to the callback for its own
|
|
|
1504 * personal use.
|
|
|
1505 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1506 * information.
|
|
|
1507 *
|
|
|
1508 * \threadsafety It is safe to call this function from any thread, but if the
|
|
|
1509 * stream has a callback set, the caller might need to manage
|
|
|
1510 * extra locking.
|
|
|
1511 *
|
|
|
1512 * \since This function is available since SDL 3.4.0.
|
|
|
1513 *
|
|
|
1514 * \sa SDL_ClearAudioStream
|
|
|
1515 * \sa SDL_FlushAudioStream
|
|
|
1516 * \sa SDL_GetAudioStreamData
|
|
|
1517 * \sa SDL_GetAudioStreamQueued
|
|
|
1518 */
|
|
|
1519 extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata);
|
|
|
1520
|
|
|
1521 /**
|
|
|
1522 * Add data to the stream with each channel in a separate array.
|
|
|
1523 *
|
|
|
1524 * This data must match the format/channels/samplerate specified in the latest
|
|
|
1525 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
|
|
|
1526 * stream if it hasn't been changed.
|
|
|
1527 *
|
|
|
1528 * The data will be interleaved and queued. Note that SDL_AudioStream only
|
|
|
1529 * operates on interleaved data, so this is simply a convenience function for
|
|
|
1530 * easily queueing data from sources that provide separate arrays. There is no
|
|
|
1531 * equivalent function to retrieve planar data.
|
|
|
1532 *
|
|
|
1533 * The arrays in `channel_buffers` are ordered as they are to be interleaved;
|
|
|
1534 * the first array will be the first sample in the interleaved data. Any
|
|
|
1535 * individual array may be NULL; in this case, silence will be interleaved for
|
|
|
1536 * that channel.
|
|
|
1537 *
|
|
|
1538 * `num_channels` specifies how many arrays are in `channel_buffers`. This can
|
|
|
1539 * be used as a safety to prevent overflow, in case the stream format has
|
|
|
1540 * changed elsewhere. If more channels are specified than the current input
|
|
|
1541 * spec, they are ignored. If less channels are specified, the missing arrays
|
|
|
1542 * are treated as if they are NULL (silence is written to those channels). If
|
|
|
1543 * the count is -1, SDL will assume the array count matches the current input
|
|
|
1544 * spec.
|
|
|
1545 *
|
|
|
1546 * Note that `num_samples` is the number of _samples per array_. This can also
|
|
|
1547 * be thought of as the number of _sample frames_ to be queued. A value of 1
|
|
|
1548 * with stereo arrays will queue two samples to the stream. This is different
|
|
|
1549 * than SDL_PutAudioStreamData, which wants the size of a single array in
|
|
|
1550 * bytes.
|
|
|
1551 *
|
|
|
1552 * \param stream the stream the audio data is being added to.
|
|
|
1553 * \param channel_buffers a pointer to an array of arrays, one array per
|
|
|
1554 * channel.
|
|
|
1555 * \param num_channels the number of arrays in `channel_buffers` or -1.
|
|
|
1556 * \param num_samples the number of _samples_ per array to write to the
|
|
|
1557 * stream.
|
|
|
1558 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1559 * information.
|
|
|
1560 *
|
|
|
1561 * \threadsafety It is safe to call this function from any thread, but if the
|
|
|
1562 * stream has a callback set, the caller might need to manage
|
|
|
1563 * extra locking.
|
|
|
1564 *
|
|
|
1565 * \since This function is available since SDL 3.4.0.
|
|
|
1566 *
|
|
|
1567 * \sa SDL_ClearAudioStream
|
|
|
1568 * \sa SDL_FlushAudioStream
|
|
|
1569 * \sa SDL_GetAudioStreamData
|
|
|
1570 * \sa SDL_GetAudioStreamQueued
|
|
|
1571 */
|
|
|
1572 extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples);
|
|
|
1573
|
|
|
1574 /**
|
|
|
1575 * Get converted/resampled data from the stream.
|
|
|
1576 *
|
|
|
1577 * The input/output data format/channels/samplerate is specified when creating
|
|
|
1578 * the stream, and can be changed after creation by calling
|
|
|
1579 * SDL_SetAudioStreamFormat.
|
|
|
1580 *
|
|
|
1581 * Note that any conversion and resampling necessary is done during this call,
|
|
|
1582 * and SDL_PutAudioStreamData simply queues unconverted data for later. This
|
|
|
1583 * is different than SDL2, where that work was done while inputting new data
|
|
|
1584 * to the stream and requesting the output just copied the converted data.
|
|
|
1585 *
|
|
|
1586 * \param stream the stream the audio is being requested from.
|
|
|
1587 * \param buf a buffer to fill with audio data.
|
|
|
1588 * \param len the maximum number of bytes to fill.
|
|
|
1589 * \returns the number of bytes read from the stream or -1 on failure; call
|
|
|
1590 * SDL_GetError() for more information.
|
|
|
1591 *
|
|
|
1592 * \threadsafety It is safe to call this function from any thread, but if the
|
|
|
1593 * stream has a callback set, the caller might need to manage
|
|
|
1594 * extra locking.
|
|
|
1595 *
|
|
|
1596 * \since This function is available since SDL 3.2.0.
|
|
|
1597 *
|
|
|
1598 * \sa SDL_ClearAudioStream
|
|
|
1599 * \sa SDL_GetAudioStreamAvailable
|
|
|
1600 * \sa SDL_PutAudioStreamData
|
|
|
1601 */
|
|
|
1602 extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len);
|
|
|
1603
|
|
|
1604 /**
|
|
|
1605 * Get the number of converted/resampled bytes available.
|
|
|
1606 *
|
|
|
1607 * The stream may be buffering data behind the scenes until it has enough to
|
|
|
1608 * resample correctly, so this number might be lower than what you expect, or
|
|
|
1609 * even be zero. Add more data or flush the stream if you need the data now.
|
|
|
1610 *
|
|
|
1611 * If the stream has so much data that it would overflow an int, the return
|
|
|
1612 * value is clamped to a maximum value, but no queued data is lost; if there
|
|
|
1613 * are gigabytes of data queued, the app might need to read some of it with
|
|
|
1614 * SDL_GetAudioStreamData before this function's return value is no longer
|
|
|
1615 * clamped.
|
|
|
1616 *
|
|
|
1617 * \param stream the audio stream to query.
|
|
|
1618 * \returns the number of converted/resampled bytes available or -1 on
|
|
|
1619 * failure; call SDL_GetError() for more information.
|
|
|
1620 *
|
|
|
1621 * \threadsafety It is safe to call this function from any thread.
|
|
|
1622 *
|
|
|
1623 * \since This function is available since SDL 3.2.0.
|
|
|
1624 *
|
|
|
1625 * \sa SDL_GetAudioStreamData
|
|
|
1626 * \sa SDL_PutAudioStreamData
|
|
|
1627 */
|
|
|
1628 extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream);
|
|
|
1629
|
|
|
1630
|
|
|
1631 /**
|
|
|
1632 * Get the number of bytes currently queued.
|
|
|
1633 *
|
|
|
1634 * This is the number of bytes put into a stream as input, not the number that
|
|
|
1635 * can be retrieved as output. Because of several details, it's not possible
|
|
|
1636 * to calculate one number directly from the other. If you need to know how
|
|
|
1637 * much usable data can be retrieved right now, you should use
|
|
|
1638 * SDL_GetAudioStreamAvailable() and not this function.
|
|
|
1639 *
|
|
|
1640 * Note that audio streams can change their input format at any time, even if
|
|
|
1641 * there is still data queued in a different format, so the returned byte
|
|
|
1642 * count will not necessarily match the number of _sample frames_ available.
|
|
|
1643 * Users of this API should be aware of format changes they make when feeding
|
|
|
1644 * a stream and plan accordingly.
|
|
|
1645 *
|
|
|
1646 * Queued data is not converted until it is consumed by
|
|
|
1647 * SDL_GetAudioStreamData, so this value should be representative of the exact
|
|
|
1648 * data that was put into the stream.
|
|
|
1649 *
|
|
|
1650 * If the stream has so much data that it would overflow an int, the return
|
|
|
1651 * value is clamped to a maximum value, but no queued data is lost; if there
|
|
|
1652 * are gigabytes of data queued, the app might need to read some of it with
|
|
|
1653 * SDL_GetAudioStreamData before this function's return value is no longer
|
|
|
1654 * clamped.
|
|
|
1655 *
|
|
|
1656 * \param stream the audio stream to query.
|
|
|
1657 * \returns the number of bytes queued or -1 on failure; call SDL_GetError()
|
|
|
1658 * for more information.
|
|
|
1659 *
|
|
|
1660 * \threadsafety It is safe to call this function from any thread.
|
|
|
1661 *
|
|
|
1662 * \since This function is available since SDL 3.2.0.
|
|
|
1663 *
|
|
|
1664 * \sa SDL_PutAudioStreamData
|
|
|
1665 * \sa SDL_ClearAudioStream
|
|
|
1666 */
|
|
|
1667 extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
|
|
|
1668
|
|
|
1669
|
|
|
1670 /**
|
|
|
1671 * Tell the stream that you're done sending data, and anything being buffered
|
|
|
1672 * should be converted/resampled and made available immediately.
|
|
|
1673 *
|
|
|
1674 * It is legal to add more data to a stream after flushing, but there may be
|
|
|
1675 * audio gaps in the output. Generally this is intended to signal the end of
|
|
|
1676 * input, so the complete output becomes available.
|
|
|
1677 *
|
|
|
1678 * \param stream the audio stream to flush.
|
|
|
1679 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1680 * information.
|
|
|
1681 *
|
|
|
1682 * \threadsafety It is safe to call this function from any thread.
|
|
|
1683 *
|
|
|
1684 * \since This function is available since SDL 3.2.0.
|
|
|
1685 *
|
|
|
1686 * \sa SDL_PutAudioStreamData
|
|
|
1687 */
|
|
|
1688 extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
|
|
|
1689
|
|
|
1690 /**
|
|
|
1691 * Clear any pending data in the stream.
|
|
|
1692 *
|
|
|
1693 * This drops any queued data, so there will be nothing to read from the
|
|
|
1694 * stream until more is added.
|
|
|
1695 *
|
|
|
1696 * \param stream the audio stream to clear.
|
|
|
1697 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1698 * information.
|
|
|
1699 *
|
|
|
1700 * \threadsafety It is safe to call this function from any thread.
|
|
|
1701 *
|
|
|
1702 * \since This function is available since SDL 3.2.0.
|
|
|
1703 *
|
|
|
1704 * \sa SDL_GetAudioStreamAvailable
|
|
|
1705 * \sa SDL_GetAudioStreamData
|
|
|
1706 * \sa SDL_GetAudioStreamQueued
|
|
|
1707 * \sa SDL_PutAudioStreamData
|
|
|
1708 */
|
|
|
1709 extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
|
|
|
1710
|
|
|
1711 /**
|
|
|
1712 * Use this function to pause audio playback on the audio device associated
|
|
|
1713 * with an audio stream.
|
|
|
1714 *
|
|
|
1715 * This function pauses audio processing for a given device. Any bound audio
|
|
|
1716 * streams will not progress, and no audio will be generated. Pausing one
|
|
|
1717 * device does not prevent other unpaused devices from running.
|
|
|
1718 *
|
|
|
1719 * Pausing a device can be useful to halt all audio without unbinding all the
|
|
|
1720 * audio streams. This might be useful while a game is paused, or a level is
|
|
|
1721 * loading, etc.
|
|
|
1722 *
|
|
|
1723 * \param stream the audio stream associated with the audio device to pause.
|
|
|
1724 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1725 * information.
|
|
|
1726 *
|
|
|
1727 * \threadsafety It is safe to call this function from any thread.
|
|
|
1728 *
|
|
|
1729 * \since This function is available since SDL 3.2.0.
|
|
|
1730 *
|
|
|
1731 * \sa SDL_ResumeAudioStreamDevice
|
|
|
1732 */
|
|
|
1733 extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream);
|
|
|
1734
|
|
|
1735 /**
|
|
|
1736 * Use this function to unpause audio playback on the audio device associated
|
|
|
1737 * with an audio stream.
|
|
|
1738 *
|
|
|
1739 * This function unpauses audio processing for a given device that has
|
|
|
1740 * previously been paused. Once unpaused, any bound audio streams will begin
|
|
|
1741 * to progress again, and audio can be generated.
|
|
|
1742 *
|
|
|
1743 * SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this
|
|
|
1744 * function call is required for audio playback to begin on such devices.
|
|
|
1745 *
|
|
|
1746 * \param stream the audio stream associated with the audio device to resume.
|
|
|
1747 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1748 * information.
|
|
|
1749 *
|
|
|
1750 * \threadsafety It is safe to call this function from any thread.
|
|
|
1751 *
|
|
|
1752 * \since This function is available since SDL 3.2.0.
|
|
|
1753 *
|
|
|
1754 * \sa SDL_PauseAudioStreamDevice
|
|
|
1755 */
|
|
|
1756 extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream);
|
|
|
1757
|
|
|
1758 /**
|
|
|
1759 * Use this function to query if an audio device associated with a stream is
|
|
|
1760 * paused.
|
|
|
1761 *
|
|
|
1762 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
|
|
|
1763 * has to bind a stream before any audio will flow.
|
|
|
1764 *
|
|
|
1765 * \param stream the audio stream associated with the audio device to query.
|
|
|
1766 * \returns true if device is valid and paused, false otherwise.
|
|
|
1767 *
|
|
|
1768 * \threadsafety It is safe to call this function from any thread.
|
|
|
1769 *
|
|
|
1770 * \since This function is available since SDL 3.2.0.
|
|
|
1771 *
|
|
|
1772 * \sa SDL_PauseAudioStreamDevice
|
|
|
1773 * \sa SDL_ResumeAudioStreamDevice
|
|
|
1774 */
|
|
|
1775 extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream);
|
|
|
1776
|
|
|
1777
|
|
|
1778 /**
|
|
|
1779 * Lock an audio stream for serialized access.
|
|
|
1780 *
|
|
|
1781 * Each SDL_AudioStream has an internal mutex it uses to protect its data
|
|
|
1782 * structures from threading conflicts. This function allows an app to lock
|
|
|
1783 * that mutex, which could be useful if registering callbacks on this stream.
|
|
|
1784 *
|
|
|
1785 * One does not need to lock a stream to use in it most cases, as the stream
|
|
|
1786 * manages this lock internally. However, this lock is held during callbacks,
|
|
|
1787 * which may run from arbitrary threads at any time, so if an app needs to
|
|
|
1788 * protect shared data during those callbacks, locking the stream guarantees
|
|
|
1789 * that the callback is not running while the lock is held.
|
|
|
1790 *
|
|
|
1791 * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
|
|
|
1792 * all the same attributes (recursive locks are allowed, etc).
|
|
|
1793 *
|
|
|
1794 * \param stream the audio stream to lock.
|
|
|
1795 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1796 * information.
|
|
|
1797 *
|
|
|
1798 * \threadsafety It is safe to call this function from any thread.
|
|
|
1799 *
|
|
|
1800 * \since This function is available since SDL 3.2.0.
|
|
|
1801 *
|
|
|
1802 * \sa SDL_UnlockAudioStream
|
|
|
1803 */
|
|
|
1804 extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
|
|
|
1805
|
|
|
1806
|
|
|
1807 /**
|
|
|
1808 * Unlock an audio stream for serialized access.
|
|
|
1809 *
|
|
|
1810 * This unlocks an audio stream after a call to SDL_LockAudioStream.
|
|
|
1811 *
|
|
|
1812 * \param stream the audio stream to unlock.
|
|
|
1813 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1814 * information.
|
|
|
1815 *
|
|
|
1816 * \threadsafety You should only call this from the same thread that
|
|
|
1817 * previously called SDL_LockAudioStream.
|
|
|
1818 *
|
|
|
1819 * \since This function is available since SDL 3.2.0.
|
|
|
1820 *
|
|
|
1821 * \sa SDL_LockAudioStream
|
|
|
1822 */
|
|
|
1823 extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
|
|
|
1824
|
|
|
1825 /**
|
|
|
1826 * A callback that fires when data passes through an SDL_AudioStream.
|
|
|
1827 *
|
|
|
1828 * Apps can (optionally) register a callback with an audio stream that is
|
|
|
1829 * called when data is added with SDL_PutAudioStreamData, or requested with
|
|
|
1830 * SDL_GetAudioStreamData.
|
|
|
1831 *
|
|
|
1832 * Two values are offered here: one is the amount of additional data needed to
|
|
|
1833 * satisfy the immediate request (which might be zero if the stream already
|
|
|
1834 * has enough data queued) and the other is the total amount being requested.
|
|
|
1835 * In a Get call triggering a Put callback, these values can be different. In
|
|
|
1836 * a Put call triggering a Get callback, these values are always the same.
|
|
|
1837 *
|
|
|
1838 * Byte counts might be slightly overestimated due to buffering or resampling,
|
|
|
1839 * and may change from call to call.
|
|
|
1840 *
|
|
|
1841 * This callback is not required to do anything. Generally this is useful for
|
|
|
1842 * adding/reading data on demand, and the app will often put/get data as
|
|
|
1843 * appropriate, but the system goes on with the data currently available to it
|
|
|
1844 * if this callback does nothing.
|
|
|
1845 *
|
|
|
1846 * \param stream the SDL audio stream associated with this callback.
|
|
|
1847 * \param additional_amount the amount of data, in bytes, that is needed right
|
|
|
1848 * now.
|
|
|
1849 * \param total_amount the total amount of data requested, in bytes, that is
|
|
|
1850 * requested or available.
|
|
|
1851 * \param userdata an opaque pointer provided by the app for their personal
|
|
|
1852 * use.
|
|
|
1853 *
|
|
|
1854 * \threadsafety This callbacks may run from any thread, so if you need to
|
|
|
1855 * protect shared data, you should use SDL_LockAudioStream to
|
|
|
1856 * serialize access; this lock will be held before your callback
|
|
|
1857 * is called, so your callback does not need to manage the lock
|
|
|
1858 * explicitly.
|
|
|
1859 *
|
|
|
1860 * \since This datatype is available since SDL 3.2.0.
|
|
|
1861 *
|
|
|
1862 * \sa SDL_SetAudioStreamGetCallback
|
|
|
1863 * \sa SDL_SetAudioStreamPutCallback
|
|
|
1864 */
|
|
|
1865 typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
|
|
|
1866
|
|
|
1867 /**
|
|
|
1868 * Set a callback that runs when data is requested from an audio stream.
|
|
|
1869 *
|
|
|
1870 * This callback is called _before_ data is obtained from the stream, giving
|
|
|
1871 * the callback the chance to add more on-demand.
|
|
|
1872 *
|
|
|
1873 * The callback can (optionally) call SDL_PutAudioStreamData() to add more
|
|
|
1874 * audio to the stream during this call; if needed, the request that triggered
|
|
|
1875 * this callback will obtain the new data immediately.
|
|
|
1876 *
|
|
|
1877 * The callback's `additional_amount` argument is roughly how many bytes of
|
|
|
1878 * _unconverted_ data (in the stream's input format) is needed by the caller,
|
|
|
1879 * although this may overestimate a little for safety. This takes into account
|
|
|
1880 * how much is already in the stream and only asks for any extra necessary to
|
|
|
1881 * resolve the request, which means the callback may be asked for zero bytes,
|
|
|
1882 * and a different amount on each call.
|
|
|
1883 *
|
|
|
1884 * The callback is not required to supply exact amounts; it is allowed to
|
|
|
1885 * supply too much or too little or none at all. The caller will get what's
|
|
|
1886 * available, up to the amount they requested, regardless of this callback's
|
|
|
1887 * outcome.
|
|
|
1888 *
|
|
|
1889 * Clearing or flushing an audio stream does not call this callback.
|
|
|
1890 *
|
|
|
1891 * This function obtains the stream's lock, which means any existing callback
|
|
|
1892 * (get or put) in progress will finish running before setting the new
|
|
|
1893 * callback.
|
|
|
1894 *
|
|
|
1895 * Setting a NULL function turns off the callback.
|
|
|
1896 *
|
|
|
1897 * \param stream the audio stream to set the new callback on.
|
|
|
1898 * \param callback the new callback function to call when data is requested
|
|
|
1899 * from the stream.
|
|
|
1900 * \param userdata an opaque pointer provided to the callback for its own
|
|
|
1901 * personal use.
|
|
|
1902 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1903 * information. This only fails if `stream` is NULL.
|
|
|
1904 *
|
|
|
1905 * \threadsafety It is safe to call this function from any thread.
|
|
|
1906 *
|
|
|
1907 * \since This function is available since SDL 3.2.0.
|
|
|
1908 *
|
|
|
1909 * \sa SDL_SetAudioStreamPutCallback
|
|
|
1910 */
|
|
|
1911 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
|
|
|
1912
|
|
|
1913 /**
|
|
|
1914 * Set a callback that runs when data is added to an audio stream.
|
|
|
1915 *
|
|
|
1916 * This callback is called _after_ the data is added to the stream, giving the
|
|
|
1917 * callback the chance to obtain it immediately.
|
|
|
1918 *
|
|
|
1919 * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
|
|
|
1920 * from the stream during this call.
|
|
|
1921 *
|
|
|
1922 * The callback's `additional_amount` argument is how many bytes of
|
|
|
1923 * _converted_ data (in the stream's output format) was provided by the
|
|
|
1924 * caller, although this may underestimate a little for safety. This value
|
|
|
1925 * might be less than what is currently available in the stream, if data was
|
|
|
1926 * already there, and might be less than the caller provided if the stream
|
|
|
1927 * needs to keep a buffer to aid in resampling. Which means the callback may
|
|
|
1928 * be provided with zero bytes, and a different amount on each call.
|
|
|
1929 *
|
|
|
1930 * The callback may call SDL_GetAudioStreamAvailable to see the total amount
|
|
|
1931 * currently available to read from the stream, instead of the total provided
|
|
|
1932 * by the current call.
|
|
|
1933 *
|
|
|
1934 * The callback is not required to obtain all data. It is allowed to read less
|
|
|
1935 * or none at all. Anything not read now simply remains in the stream for
|
|
|
1936 * later access.
|
|
|
1937 *
|
|
|
1938 * Clearing or flushing an audio stream does not call this callback.
|
|
|
1939 *
|
|
|
1940 * This function obtains the stream's lock, which means any existing callback
|
|
|
1941 * (get or put) in progress will finish running before setting the new
|
|
|
1942 * callback.
|
|
|
1943 *
|
|
|
1944 * Setting a NULL function turns off the callback.
|
|
|
1945 *
|
|
|
1946 * \param stream the audio stream to set the new callback on.
|
|
|
1947 * \param callback the new callback function to call when data is added to the
|
|
|
1948 * stream.
|
|
|
1949 * \param userdata an opaque pointer provided to the callback for its own
|
|
|
1950 * personal use.
|
|
|
1951 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1952 * information. This only fails if `stream` is NULL.
|
|
|
1953 *
|
|
|
1954 * \threadsafety It is safe to call this function from any thread.
|
|
|
1955 *
|
|
|
1956 * \since This function is available since SDL 3.2.0.
|
|
|
1957 *
|
|
|
1958 * \sa SDL_SetAudioStreamGetCallback
|
|
|
1959 */
|
|
|
1960 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
|
|
|
1961
|
|
|
1962
|
|
|
1963 /**
|
|
|
1964 * Free an audio stream.
|
|
|
1965 *
|
|
|
1966 * This will release all allocated data, including any audio that is still
|
|
|
1967 * queued. You do not need to manually clear the stream first.
|
|
|
1968 *
|
|
|
1969 * If this stream was bound to an audio device, it is unbound during this
|
|
|
1970 * call. If this stream was created with SDL_OpenAudioDeviceStream, the audio
|
|
|
1971 * device that was opened alongside this stream's creation will be closed,
|
|
|
1972 * too.
|
|
|
1973 *
|
|
|
1974 * \param stream the audio stream to destroy.
|
|
|
1975 *
|
|
|
1976 * \threadsafety It is safe to call this function from any thread.
|
|
|
1977 *
|
|
|
1978 * \since This function is available since SDL 3.2.0.
|
|
|
1979 *
|
|
|
1980 * \sa SDL_CreateAudioStream
|
|
|
1981 */
|
|
|
1982 extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
|
|
|
1983
|
|
|
1984
|
|
|
1985 /**
|
|
|
1986 * Convenience function for straightforward audio init for the common case.
|
|
|
1987 *
|
|
|
1988 * If all your app intends to do is provide a single source of PCM audio, this
|
|
|
1989 * function allows you to do all your audio setup in a single call.
|
|
|
1990 *
|
|
|
1991 * This is also intended to be a clean means to migrate apps from SDL2.
|
|
|
1992 *
|
|
|
1993 * This function will open an audio device, create a stream and bind it.
|
|
|
1994 * Unlike other methods of setup, the audio device will be closed when this
|
|
|
1995 * stream is destroyed, so the app can treat the returned SDL_AudioStream as
|
|
|
1996 * the only object needed to manage audio playback.
|
|
|
1997 *
|
|
|
1998 * Also unlike other functions, the audio device begins paused. This is to map
|
|
|
1999 * more closely to SDL2-style behavior, since there is no extra step here to
|
|
|
2000 * bind a stream to begin audio flowing. The audio device should be resumed
|
|
|
2001 * with SDL_ResumeAudioStreamDevice().
|
|
|
2002 *
|
|
|
2003 * This function works with both playback and recording devices.
|
|
|
2004 *
|
|
|
2005 * The `spec` parameter represents the app's side of the audio stream. That
|
|
|
2006 * is, for recording audio, this will be the output format, and for playing
|
|
|
2007 * audio, this will be the input format. If spec is NULL, the system will
|
|
|
2008 * choose the format, and the app can use SDL_GetAudioStreamFormat() to obtain
|
|
|
2009 * this information later.
|
|
|
2010 *
|
|
|
2011 * If you don't care about opening a specific audio device, you can (and
|
|
|
2012 * probably _should_), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and
|
|
|
2013 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording.
|
|
|
2014 *
|
|
|
2015 * One can optionally provide a callback function; if NULL, the app is
|
|
|
2016 * expected to queue audio data for playback (or unqueue audio data if
|
|
|
2017 * capturing). Otherwise, the callback will begin to fire once the device is
|
|
|
2018 * unpaused.
|
|
|
2019 *
|
|
|
2020 * Destroying the returned stream with SDL_DestroyAudioStream will also close
|
|
|
2021 * the audio device associated with this stream.
|
|
|
2022 *
|
|
|
2023 * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
|
|
|
2024 * or SDL_AUDIO_DEVICE_DEFAULT_RECORDING.
|
|
|
2025 * \param spec the audio stream's data format. Can be NULL.
|
|
|
2026 * \param callback a callback where the app will provide new data for
|
|
|
2027 * playback, or receive new data for recording. Can be NULL,
|
|
|
2028 * in which case the app will need to call
|
|
|
2029 * SDL_PutAudioStreamData or SDL_GetAudioStreamData as
|
|
|
2030 * necessary.
|
|
|
2031 * \param userdata app-controlled pointer passed to callback. Can be NULL.
|
|
|
2032 * Ignored if callback is NULL.
|
|
|
2033 * \returns an audio stream on success, ready to use, or NULL on failure; call
|
|
|
2034 * SDL_GetError() for more information. When done with this stream,
|
|
|
2035 * call SDL_DestroyAudioStream to free resources and close the
|
|
|
2036 * device.
|
|
|
2037 *
|
|
|
2038 * \threadsafety It is safe to call this function from any thread.
|
|
|
2039 *
|
|
|
2040 * \since This function is available since SDL 3.2.0.
|
|
|
2041 *
|
|
|
2042 * \sa SDL_GetAudioStreamDevice
|
|
|
2043 * \sa SDL_ResumeAudioStreamDevice
|
|
|
2044 */
|
|
|
2045 extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
|
|
|
2046
|
|
|
2047 /**
|
|
|
2048 * A callback that fires when data is about to be fed to an audio device.
|
|
|
2049 *
|
|
|
2050 * This is useful for accessing the final mix, perhaps for writing a
|
|
|
2051 * visualizer or applying a final effect to the audio data before playback.
|
|
|
2052 *
|
|
|
2053 * This callback should run as quickly as possible and not block for any
|
|
|
2054 * significant time, as this callback delays submission of data to the audio
|
|
|
2055 * device, which can cause audio playback problems.
|
|
|
2056 *
|
|
|
2057 * The postmix callback _must_ be able to handle any audio data format
|
|
|
2058 * specified in `spec`, which can change between callbacks if the audio device
|
|
|
2059 * changed. However, this only covers frequency and channel count; data is
|
|
|
2060 * always provided here in SDL_AUDIO_F32 format.
|
|
|
2061 *
|
|
|
2062 * The postmix callback runs _after_ logical device gain and audiostream gain
|
|
|
2063 * have been applied, which is to say you can make the output data louder at
|
|
|
2064 * this point than the gain settings would suggest.
|
|
|
2065 *
|
|
|
2066 * \param userdata a pointer provided by the app through
|
|
|
2067 * SDL_SetAudioPostmixCallback, for its own use.
|
|
|
2068 * \param spec the current format of audio that is to be submitted to the
|
|
|
2069 * audio device.
|
|
|
2070 * \param buffer the buffer of audio samples to be submitted. The callback can
|
|
|
2071 * inspect and/or modify this data.
|
|
|
2072 * \param buflen the size of `buffer` in bytes.
|
|
|
2073 *
|
|
|
2074 * \threadsafety This will run from a background thread owned by SDL. The
|
|
|
2075 * application is responsible for locking resources the callback
|
|
|
2076 * touches that need to be protected.
|
|
|
2077 *
|
|
|
2078 * \since This datatype is available since SDL 3.2.0.
|
|
|
2079 *
|
|
|
2080 * \sa SDL_SetAudioPostmixCallback
|
|
|
2081 */
|
|
|
2082 typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen);
|
|
|
2083
|
|
|
2084 /**
|
|
|
2085 * Set a callback that fires when data is about to be fed to an audio device.
|
|
|
2086 *
|
|
|
2087 * This is useful for accessing the final mix, perhaps for writing a
|
|
|
2088 * visualizer or applying a final effect to the audio data before playback.
|
|
|
2089 *
|
|
|
2090 * The buffer is the final mix of all bound audio streams on an opened device;
|
|
|
2091 * this callback will fire regularly for any device that is both opened and
|
|
|
2092 * unpaused. If there is no new data to mix, either because no streams are
|
|
|
2093 * bound to the device or all the streams are empty, this callback will still
|
|
|
2094 * fire with the entire buffer set to silence.
|
|
|
2095 *
|
|
|
2096 * This callback is allowed to make changes to the data; the contents of the
|
|
|
2097 * buffer after this call is what is ultimately passed along to the hardware.
|
|
|
2098 *
|
|
|
2099 * The callback is always provided the data in float format (values from -1.0f
|
|
|
2100 * to 1.0f), but the number of channels or sample rate may be different than
|
|
|
2101 * the format the app requested when opening the device; SDL might have had to
|
|
|
2102 * manage a conversion behind the scenes, or the playback might have jumped to
|
|
|
2103 * new physical hardware when a system default changed, etc. These details may
|
|
|
2104 * change between calls. Accordingly, the size of the buffer might change
|
|
|
2105 * between calls as well.
|
|
|
2106 *
|
|
|
2107 * This callback can run at any time, and from any thread; if you need to
|
|
|
2108 * serialize access to your app's data, you should provide and use a mutex or
|
|
|
2109 * other synchronization device.
|
|
|
2110 *
|
|
|
2111 * All of this to say: there are specific needs this callback can fulfill, but
|
|
|
2112 * it is not the simplest interface. Apps should generally provide audio in
|
|
|
2113 * their preferred format through an SDL_AudioStream and let SDL handle the
|
|
|
2114 * difference.
|
|
|
2115 *
|
|
|
2116 * This function is extremely time-sensitive; the callback should do the least
|
|
|
2117 * amount of work possible and return as quickly as it can. The longer the
|
|
|
2118 * callback runs, the higher the risk of audio dropouts or other problems.
|
|
|
2119 *
|
|
|
2120 * This function will block until the audio device is in between iterations,
|
|
|
2121 * so any existing callback that might be running will finish before this
|
|
|
2122 * function sets the new callback and returns.
|
|
|
2123 *
|
|
|
2124 * Setting a NULL callback function disables any previously-set callback.
|
|
|
2125 *
|
|
|
2126 * \param devid the ID of an opened audio device.
|
|
|
2127 * \param callback a callback function to be called. Can be NULL.
|
|
|
2128 * \param userdata app-controlled pointer passed to callback. Can be NULL.
|
|
|
2129 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2130 * information.
|
|
|
2131 *
|
|
|
2132 * \threadsafety It is safe to call this function from any thread.
|
|
|
2133 *
|
|
|
2134 * \since This function is available since SDL 3.2.0.
|
|
|
2135 */
|
|
|
2136 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata);
|
|
|
2137
|
|
|
2138
|
|
|
2139 /**
|
|
|
2140 * Load the audio data of a WAVE file into memory.
|
|
|
2141 *
|
|
|
2142 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
|
|
|
2143 * be valid pointers. The entire data portion of the file is then loaded into
|
|
|
2144 * memory and decoded if necessary.
|
|
|
2145 *
|
|
|
2146 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
|
|
|
2147 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
|
|
|
2148 * A-law and mu-law (8 bits). Other formats are currently unsupported and
|
|
|
2149 * cause an error.
|
|
|
2150 *
|
|
|
2151 * If this function succeeds, the return value is zero and the pointer to the
|
|
|
2152 * audio data allocated by the function is written to `audio_buf` and its
|
|
|
2153 * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
|
|
|
2154 * `channels`, and `format` are set to the values of the audio data in the
|
|
|
2155 * buffer.
|
|
|
2156 *
|
|
|
2157 * It's necessary to use SDL_free() to free the audio data returned in
|
|
|
2158 * `audio_buf` when it is no longer used.
|
|
|
2159 *
|
|
|
2160 * Because of the underspecification of the .WAV format, there are many
|
|
|
2161 * problematic files in the wild that cause issues with strict decoders. To
|
|
|
2162 * provide compatibility with these files, this decoder is lenient in regards
|
|
|
2163 * to the truncation of the file, the fact chunk, and the size of the RIFF
|
|
|
2164 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
|
|
|
2165 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
|
|
|
2166 * tune the behavior of the loading process.
|
|
|
2167 *
|
|
|
2168 * Any file that is invalid (due to truncation, corruption, or wrong values in
|
|
|
2169 * the headers), too big, or unsupported causes an error. Additionally, any
|
|
|
2170 * critical I/O error from the data source will terminate the loading process
|
|
|
2171 * with an error. The function returns NULL on error and in all cases (with
|
|
|
2172 * the exception of `src` being NULL), an appropriate error message will be
|
|
|
2173 * set.
|
|
|
2174 *
|
|
|
2175 * It is required that the data source supports seeking.
|
|
|
2176 *
|
|
|
2177 * Example:
|
|
|
2178 *
|
|
|
2179 * ```c
|
|
|
2180 * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len);
|
|
|
2181 * ```
|
|
|
2182 *
|
|
|
2183 * Note that the SDL_LoadWAV function does this same thing for you, but in a
|
|
|
2184 * less messy way:
|
|
|
2185 *
|
|
|
2186 * ```c
|
|
|
2187 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
|
|
|
2188 * ```
|
|
|
2189 *
|
|
|
2190 * \param src the data source for the WAVE data.
|
|
|
2191 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
|
|
|
2192 * in the case of an error.
|
|
|
2193 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
|
|
|
2194 * data's format details on successful return.
|
|
|
2195 * \param audio_buf a pointer filled with the audio data, allocated by the
|
|
|
2196 * function.
|
|
|
2197 * \param audio_len a pointer filled with the length of the audio data buffer
|
|
|
2198 * in bytes.
|
|
|
2199 * \returns true on success. `audio_buf` will be filled with a pointer to an
|
|
|
2200 * allocated buffer containing the audio data, and `audio_len` is
|
|
|
2201 * filled with the length of that audio buffer in bytes.
|
|
|
2202 *
|
|
|
2203 * This function returns false if the .WAV file cannot be opened,
|
|
|
2204 * uses an unknown data format, or is corrupt; call SDL_GetError()
|
|
|
2205 * for more information.
|
|
|
2206 *
|
|
|
2207 * When the application is done with the data returned in
|
|
|
2208 * `audio_buf`, it should call SDL_free() to dispose of it.
|
|
|
2209 *
|
|
|
2210 * \threadsafety It is safe to call this function from any thread.
|
|
|
2211 *
|
|
|
2212 * \since This function is available since SDL 3.2.0.
|
|
|
2213 *
|
|
|
2214 * \sa SDL_free
|
|
|
2215 * \sa SDL_LoadWAV
|
|
|
2216 */
|
|
|
2217 extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
|
|
|
2218
|
|
|
2219 /**
|
|
|
2220 * Loads a WAV from a file path.
|
|
|
2221 *
|
|
|
2222 * This is a convenience function that is effectively the same as:
|
|
|
2223 *
|
|
|
2224 * ```c
|
|
|
2225 * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len);
|
|
|
2226 * ```
|
|
|
2227 *
|
|
|
2228 * \param path the file path of the WAV file to open.
|
|
|
2229 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
|
|
|
2230 * data's format details on successful return.
|
|
|
2231 * \param audio_buf a pointer filled with the audio data, allocated by the
|
|
|
2232 * function.
|
|
|
2233 * \param audio_len a pointer filled with the length of the audio data buffer
|
|
|
2234 * in bytes.
|
|
|
2235 * \returns true on success. `audio_buf` will be filled with a pointer to an
|
|
|
2236 * allocated buffer containing the audio data, and `audio_len` is
|
|
|
2237 * filled with the length of that audio buffer in bytes.
|
|
|
2238 *
|
|
|
2239 * This function returns false if the .WAV file cannot be opened,
|
|
|
2240 * uses an unknown data format, or is corrupt; call SDL_GetError()
|
|
|
2241 * for more information.
|
|
|
2242 *
|
|
|
2243 * When the application is done with the data returned in
|
|
|
2244 * `audio_buf`, it should call SDL_free() to dispose of it.
|
|
|
2245 *
|
|
|
2246 * \threadsafety It is safe to call this function from any thread.
|
|
|
2247 *
|
|
|
2248 * \since This function is available since SDL 3.2.0.
|
|
|
2249 *
|
|
|
2250 * \sa SDL_free
|
|
|
2251 * \sa SDL_LoadWAV_IO
|
|
|
2252 */
|
|
|
2253 extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
|
|
|
2254
|
|
|
2255 /**
|
|
|
2256 * Mix audio data in a specified format.
|
|
|
2257 *
|
|
|
2258 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
|
|
|
2259 * it into `dst`, performing addition, volume adjustment, and overflow
|
|
|
2260 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
|
|
|
2261 * `format` data.
|
|
|
2262 *
|
|
|
2263 * This is provided for convenience -- you can mix your own audio data.
|
|
|
2264 *
|
|
|
2265 * Do not use this function for mixing together more than two streams of
|
|
|
2266 * sample data. The output from repeated application of this function may be
|
|
|
2267 * distorted by clipping, because there is no accumulator with greater range
|
|
|
2268 * than the input (not to mention this being an inefficient way of doing it).
|
|
|
2269 *
|
|
|
2270 * It is a common misconception that this function is required to write audio
|
|
|
2271 * data to an output stream in an audio callback. While you can do that,
|
|
|
2272 * SDL_MixAudio() is really only needed when you're mixing a single audio
|
|
|
2273 * stream with a volume adjustment.
|
|
|
2274 *
|
|
|
2275 * \param dst the destination for the mixed audio.
|
|
|
2276 * \param src the source audio buffer to be mixed.
|
|
|
2277 * \param format the SDL_AudioFormat structure representing the desired audio
|
|
|
2278 * format.
|
|
|
2279 * \param len the length of the audio buffer in bytes.
|
|
|
2280 * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
|
|
|
2281 * audio volume.
|
|
|
2282 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2283 * information.
|
|
|
2284 *
|
|
|
2285 * \threadsafety It is safe to call this function from any thread.
|
|
|
2286 *
|
|
|
2287 * \since This function is available since SDL 3.2.0.
|
|
|
2288 */
|
|
|
2289 extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume);
|
|
|
2290
|
|
|
2291 /**
|
|
|
2292 * Convert some audio data of one format to another format.
|
|
|
2293 *
|
|
|
2294 * Please note that this function is for convenience, but should not be used
|
|
|
2295 * to resample audio in blocks, as it will introduce audio artifacts on the
|
|
|
2296 * boundaries. You should only use this function if you are converting audio
|
|
|
2297 * data in its entirety in one call. If you want to convert audio in smaller
|
|
|
2298 * chunks, use an SDL_AudioStream, which is designed for this situation.
|
|
|
2299 *
|
|
|
2300 * Internally, this function creates and destroys an SDL_AudioStream on each
|
|
|
2301 * use, so it's also less efficient than using one directly, if you need to
|
|
|
2302 * convert multiple times.
|
|
|
2303 *
|
|
|
2304 * \param src_spec the format details of the input audio.
|
|
|
2305 * \param src_data the audio data to be converted.
|
|
|
2306 * \param src_len the len of src_data.
|
|
|
2307 * \param dst_spec the format details of the output audio.
|
|
|
2308 * \param dst_data will be filled with a pointer to converted audio data,
|
|
|
2309 * which should be freed with SDL_free(). On error, it will be
|
|
|
2310 * NULL.
|
|
|
2311 * \param dst_len will be filled with the len of dst_data.
|
|
|
2312 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2313 * information.
|
|
|
2314 *
|
|
|
2315 * \threadsafety It is safe to call this function from any thread.
|
|
|
2316 *
|
|
|
2317 * \since This function is available since SDL 3.2.0.
|
|
|
2318 */
|
|
|
2319 extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len);
|
|
|
2320
|
|
|
2321 /**
|
|
|
2322 * Get the human readable name of an audio format.
|
|
|
2323 *
|
|
|
2324 * \param format the audio format to query.
|
|
|
2325 * \returns the human readable name of the specified audio format or
|
|
|
2326 * "SDL_AUDIO_UNKNOWN" if the format isn't recognized.
|
|
|
2327 *
|
|
|
2328 * \threadsafety It is safe to call this function from any thread.
|
|
|
2329 *
|
|
|
2330 * \since This function is available since SDL 3.2.0.
|
|
|
2331 */
|
|
|
2332 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format);
|
|
|
2333
|
|
|
2334 /**
|
|
|
2335 * Get the appropriate memset value for silencing an audio format.
|
|
|
2336 *
|
|
|
2337 * The value returned by this function can be used as the second argument to
|
|
|
2338 * memset (or SDL_memset) to set an audio buffer in a specific format to
|
|
|
2339 * silence.
|
|
|
2340 *
|
|
|
2341 * \param format the audio data format to query.
|
|
|
2342 * \returns a byte value that can be passed to memset.
|
|
|
2343 *
|
|
|
2344 * \threadsafety It is safe to call this function from any thread.
|
|
|
2345 *
|
|
|
2346 * \since This function is available since SDL 3.2.0.
|
|
|
2347 */
|
|
|
2348 extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
|
|
|
2349
|
|
|
2350
|
|
|
2351 /* Ends C function definitions when using C++ */
|
|
|
2352 #ifdef __cplusplus
|
|
|
2353 }
|
|
|
2354 #endif
|
|
|
2355 #include <SDL3/SDL_close_code.h>
|
|
|
2356
|
|
|
2357 #endif /* SDL_audio_h_ */
|
