gosu 1.4.6 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/COPYING +2 -1
- data/dependencies/SDL/include/SDL3/SDL.h +91 -0
- data/dependencies/SDL/include/SDL3/SDL_assert.h +710 -0
- data/dependencies/SDL/include/SDL3/SDL_asyncio.h +550 -0
- data/dependencies/SDL/include/SDL3/SDL_atomic.h +692 -0
- data/dependencies/SDL/include/SDL3/SDL_audio.h +2382 -0
- data/dependencies/SDL/include/SDL3/SDL_begin_code.h +553 -0
- data/dependencies/SDL/include/{SDL_bits.h → SDL3/SDL_bits.h} +47 -27
- data/dependencies/SDL/include/{SDL_blendmode.h → SDL3/SDL_blendmode.h} +59 -55
- data/dependencies/SDL/include/SDL3/SDL_camera.h +535 -0
- data/dependencies/SDL/include/SDL3/SDL_clipboard.h +331 -0
- data/dependencies/SDL/include/{close_code.h → SDL3/SDL_close_code.h} +9 -8
- data/dependencies/SDL/include/{SDL_types.h → SDL3/SDL_copying.h} +2 -9
- data/dependencies/SDL/include/SDL3/SDL_cpuinfo.h +374 -0
- data/dependencies/SDL/include/SDL3/SDL_dialog.h +343 -0
- data/dependencies/SDL/include/SDL3/SDL_dlopennote.h +234 -0
- data/dependencies/SDL/include/{SDL_egl.h → SDL3/SDL_egl.h} +11 -8
- data/dependencies/SDL/include/SDL3/SDL_endian.h +645 -0
- data/dependencies/SDL/include/SDL3/SDL_error.h +226 -0
- data/dependencies/SDL/include/SDL3/SDL_events.h +1651 -0
- data/dependencies/SDL/include/SDL3/SDL_filesystem.h +537 -0
- data/dependencies/SDL/include/SDL3/SDL_gamepad.h +1657 -0
- data/dependencies/SDL/include/SDL3/SDL_gpu.h +4637 -0
- data/dependencies/SDL/include/SDL3/SDL_guid.h +106 -0
- data/dependencies/SDL/include/SDL3/SDL_haptic.h +1461 -0
- data/dependencies/SDL/include/SDL3/SDL_hidapi.h +571 -0
- data/dependencies/SDL/include/SDL3/SDL_hints.h +5041 -0
- data/dependencies/SDL/include/SDL3/SDL_init.h +508 -0
- data/dependencies/SDL/include/SDL3/SDL_intrin.h +410 -0
- data/dependencies/SDL/include/SDL3/SDL_iostream.h +1379 -0
- data/dependencies/SDL/include/SDL3/SDL_joystick.h +1385 -0
- data/dependencies/SDL/include/SDL3/SDL_keyboard.h +615 -0
- data/dependencies/SDL/include/SDL3/SDL_keycode.h +348 -0
- data/dependencies/SDL/include/SDL3/SDL_loadso.h +145 -0
- data/dependencies/SDL/include/{SDL_locale.h → SDL3/SDL_locale.h} +40 -24
- data/dependencies/SDL/include/SDL3/SDL_log.h +541 -0
- data/dependencies/SDL/include/SDL3/SDL_main.h +704 -0
- data/dependencies/SDL/include/SDL3/SDL_main_impl.h +149 -0
- data/dependencies/SDL/include/{SDL_messagebox.h → SDL3/SDL_messagebox.h} +85 -48
- data/dependencies/SDL/include/{SDL_metal.h → SDL3/SDL_metal.h} +29 -29
- data/dependencies/SDL/include/{SDL_misc.h → SDL3/SDL_misc.h} +13 -12
- data/dependencies/SDL/include/SDL3/SDL_mouse.h +813 -0
- data/dependencies/SDL/include/SDL3/SDL_mutex.h +1117 -0
- data/dependencies/SDL/include/SDL3/SDL_oldnames.h +1339 -0
- data/dependencies/SDL/include/{SDL_opengl.h → SDL3/SDL_opengl.h} +1247 -278
- data/dependencies/SDL/include/{SDL_opengl_glext.h → SDL3/SDL_opengl_glext.h} +5 -1
- data/dependencies/SDL/include/{SDL_opengles.h → SDL3/SDL_opengles.h} +6 -7
- data/dependencies/SDL/include/{SDL_opengles2.h → SDL3/SDL_opengles2.h} +10 -11
- data/dependencies/SDL/include/SDL3/SDL_pen.h +198 -0
- data/dependencies/SDL/include/SDL3/SDL_pixels.h +1441 -0
- data/dependencies/SDL/include/{SDL_test_log.h → SDL3/SDL_platform.h} +25 -26
- data/dependencies/SDL/include/SDL3/SDL_platform_defines.h +497 -0
- data/dependencies/SDL/include/{SDL_power.h → SDL3/SDL_power.h} +40 -20
- data/dependencies/SDL/include/SDL3/SDL_process.h +441 -0
- data/dependencies/SDL/include/SDL3/SDL_properties.h +572 -0
- data/dependencies/SDL/include/SDL3/SDL_rect.h +528 -0
- data/dependencies/SDL/include/SDL3/SDL_render.h +3034 -0
- data/dependencies/SDL/include/SDL3/SDL_revision.h +56 -0
- data/dependencies/SDL/include/{SDL_scancode.h → SDL3/SDL_scancode.h} +60 -68
- data/dependencies/SDL/include/SDL3/SDL_sensor.h +321 -0
- data/dependencies/SDL/include/SDL3/SDL_stdinc.h +6186 -0
- data/dependencies/SDL/include/SDL3/SDL_storage.h +686 -0
- data/dependencies/SDL/include/SDL3/SDL_surface.h +1769 -0
- data/dependencies/SDL/include/SDL3/SDL_system.h +840 -0
- data/dependencies/SDL/include/{SDL_test.h → SDL3/SDL_test.h} +16 -22
- data/dependencies/SDL/include/{SDL_test_assert.h → SDL3/SDL_test_assert.h} +27 -34
- data/dependencies/SDL/include/{SDL_test_common.h → SDL3/SDL_test_common.h} +109 -52
- data/dependencies/SDL/include/{SDL_test_compare.h → SDL3/SDL_test_compare.h} +22 -14
- data/dependencies/SDL/include/{SDL_test_crc32.h → SDL3/SDL_test_crc32.h} +27 -30
- data/dependencies/SDL/include/{SDL_test_font.h → SDL3/SDL_test_font.h} +50 -49
- data/dependencies/SDL/include/{SDL_test_fuzzer.h → SDL3/SDL_test_fuzzer.h} +64 -79
- data/dependencies/SDL/include/{SDL_test_harness.h → SDL3/SDL_test_harness.h} +47 -30
- data/dependencies/SDL/include/SDL3/SDL_test_log.h +83 -0
- data/dependencies/SDL/include/{SDL_test_md5.h → SDL3/SDL_test_md5.h} +21 -28
- data/dependencies/SDL/include/{SDL_test_memory.h → SDL3/SDL_test_memory.h} +19 -16
- data/dependencies/SDL/include/SDL3/SDL_thread.h +602 -0
- data/dependencies/SDL/include/SDL3/SDL_time.h +249 -0
- data/dependencies/SDL/include/SDL3/SDL_timer.h +454 -0
- data/dependencies/SDL/include/SDL3/SDL_touch.h +184 -0
- data/dependencies/SDL/include/SDL3/SDL_tray.h +544 -0
- data/dependencies/SDL/include/SDL3/SDL_version.h +198 -0
- data/dependencies/SDL/include/SDL3/SDL_video.h +3497 -0
- data/dependencies/SDL/include/SDL3/SDL_vulkan.h +287 -0
- data/dependencies/SDL/lib/x64/libSDL3.dll.a +0 -0
- data/dependencies/SDL/lib/x86/libSDL3.dll.a +0 -0
- data/dependencies/SDL_sound/SDL3_sound/SDL_sound.h +755 -0
- data/dependencies/SDL_sound/SDL_sound.c +136 -215
- data/dependencies/SDL_sound/SDL_sound_aiff.c +55 -54
- data/dependencies/SDL_sound/SDL_sound_au.c +32 -32
- data/dependencies/SDL_sound/SDL_sound_coreaudio.c +24 -41
- data/dependencies/SDL_sound/SDL_sound_flac.c +32 -12
- data/dependencies/SDL_sound/SDL_sound_internal.h +33 -48
- data/dependencies/SDL_sound/SDL_sound_modplug.c +21 -29
- data/dependencies/SDL_sound/SDL_sound_mp3.c +35 -13
- data/dependencies/SDL_sound/SDL_sound_raw.c +14 -15
- data/dependencies/SDL_sound/SDL_sound_shn.c +82 -82
- data/dependencies/SDL_sound/SDL_sound_voc.c +30 -30
- data/dependencies/SDL_sound/SDL_sound_vorbis.c +34 -25
- data/dependencies/SDL_sound/SDL_sound_wav.c +86 -82
- data/dependencies/SDL_sound/dr_flac.h +1890 -1301
- data/dependencies/SDL_sound/dr_mp3.h +1098 -660
- data/dependencies/SDL_sound/libmodplug/fastmix.c +1 -1
- data/dependencies/SDL_sound/libmodplug/libmodplug.h +5 -4
- data/dependencies/SDL_sound/libmodplug/load_ams.c +6 -3
- data/dependencies/SDL_sound/libmodplug/load_dsm.c +2 -1
- data/dependencies/SDL_sound/libmodplug/load_mt2.c +2 -2
- data/dependencies/SDL_sound/libmodplug/modplug.h +2 -1
- data/dependencies/SDL_sound/libmodplug/snd_fx.c +3 -3
- data/dependencies/SDL_sound/libmodplug/sndfile.c +3 -0
- data/dependencies/SDL_sound/libmodplug/sndmix.c +7 -3
- data/dependencies/SDL_sound/stb_vorbis.h +397 -342
- data/dependencies/mojoAL/AL/alc.h +2 -2
- data/dependencies/mojoAL/mojoal.c +2120 -1885
- data/dependencies/stb/stb_image.h +1190 -1379
- data/dependencies/stb/stb_image_write.h +329 -129
- data/dependencies/stb/stb_truetype.h +304 -60
- data/dependencies/utf8proc/utf8proc.c +133 -75
- data/dependencies/utf8proc/utf8proc.h +131 -50
- data/dependencies/utf8proc/utf8proc_data.h +16213 -15658
- data/ext/gosu-ffi/extconf.rb +103 -0
- data/ext/gosu-ffi/gosu-ffi.def +467 -0
- data/ffi/Gosu.cpp +330 -0
- data/ffi/Gosu.h +84 -0
- data/ffi/Gosu_Channel.cpp +62 -0
- data/ffi/Gosu_Channel.h +17 -0
- data/ffi/Gosu_Color.cpp +176 -0
- data/ffi/Gosu_Color.h +31 -0
- data/ffi/Gosu_Constants.cpp +334 -0
- data/ffi/Gosu_FFI.h +34 -0
- data/ffi/Gosu_FFI_internal.h +160 -0
- data/ffi/Gosu_Font.cpp +97 -0
- data/ffi/Gosu_Font.h +32 -0
- data/ffi/Gosu_Image.cpp +239 -0
- data/ffi/Gosu_Image.h +71 -0
- data/ffi/Gosu_Sample.cpp +29 -0
- data/ffi/Gosu_Sample.h +14 -0
- data/ffi/Gosu_Song.cpp +69 -0
- data/ffi/Gosu_Song.h +18 -0
- data/ffi/Gosu_TextInput.cpp +94 -0
- data/ffi/Gosu_TextInput.h +25 -0
- data/ffi/Gosu_Window.cpp +314 -0
- data/ffi/Gosu_Window.h +78 -0
- data/include/Gosu/Audio.hpp +6 -11
- data/include/Gosu/Bitmap.hpp +38 -53
- data/include/Gosu/Buffer.hpp +54 -0
- data/include/Gosu/Color.hpp +29 -36
- data/include/Gosu/Directories.hpp +25 -28
- data/include/Gosu/Drawable.hpp +58 -0
- data/include/Gosu/Font.hpp +6 -5
- data/include/Gosu/Fwd.hpp +4 -6
- data/include/Gosu/Gosu.hpp +5 -5
- data/include/Gosu/Graphics.hpp +53 -61
- data/include/Gosu/GraphicsBase.hpp +1 -11
- data/include/Gosu/Image.hpp +12 -15
- data/include/Gosu/Math.hpp +50 -72
- data/include/Gosu/Transform.hpp +32 -0
- data/include/Gosu/Utility.hpp +77 -1
- data/include/Gosu/Version.hpp +2 -2
- data/include/Gosu/Window.hpp +15 -9
- data/lib/SDL3.dll +0 -0
- data/lib/gosu/channel.rb +50 -0
- data/lib/gosu/color.rb +173 -0
- data/lib/gosu/compat.rb +130 -17
- data/lib/gosu/constants.rb +386 -0
- data/lib/gosu/ffi.rb +269 -0
- data/lib/gosu/font.rb +62 -0
- data/lib/gosu/gl_tex_info.rb +33 -0
- data/lib/gosu/gosu.rb +250 -0
- data/lib/gosu/image.rb +179 -0
- data/lib/gosu/numeric.rb +17 -0
- data/lib/gosu/preview.rb +6 -6
- data/lib/gosu/sample.rb +25 -0
- data/lib/gosu/song.rb +57 -0
- data/lib/gosu/text_input.rb +83 -0
- data/lib/gosu/window.rb +249 -0
- data/lib/gosu.rb +29 -8
- data/lib64/SDL3.dll +0 -0
- data/rdoc/gosu.rb +2 -2
- data/src/Audio.cpp +30 -24
- data/src/AudioFile.hpp +5 -4
- data/src/AudioFileAudioToolbox.cpp +8 -8
- data/src/AudioFileSDLSound.cpp +12 -15
- data/src/BinPacker.cpp +188 -0
- data/src/BinPacker.hpp +55 -0
- data/src/Bitmap.cpp +172 -143
- data/src/BitmapIO.cpp +60 -86
- data/src/Buffer.cpp +150 -0
- data/src/ClipRectStack.cpp +38 -0
- data/src/ClipRectStack.hpp +17 -83
- data/src/Color.cpp +75 -80
- data/src/Directories.cpp +47 -0
- data/src/DirectoriesUIKit.cpp +50 -0
- data/src/DrawOp.hpp +20 -18
- data/src/DrawOpQueue.hpp +27 -33
- data/src/Drawable.cpp +95 -0
- data/src/EmptyDrawable.hpp +38 -0
- data/src/FPS.cpp +31 -0
- data/src/Font.cpp +104 -74
- data/src/GosuGLView.cpp +13 -11
- data/src/GosuViewController.cpp +2 -10
- data/src/Graphics.cpp +86 -145
- data/src/GraphicsImpl.hpp +14 -68
- data/src/Image.cpp +41 -35
- data/src/Input.cpp +73 -78
- data/src/Macro.cpp +46 -29
- data/src/Macro.hpp +23 -17
- data/src/MarkupParser.cpp +5 -5
- data/src/Math.cpp +48 -22
- data/src/OffScreenTarget.cpp +47 -50
- data/src/OffScreenTarget.hpp +13 -11
- data/src/OpenGLContext.cpp +116 -0
- data/src/OpenGLContext.hpp +41 -0
- data/src/RenderState.hpp +49 -71
- data/src/Resolution.cpp +65 -53
- data/src/TexChunk.cpp +35 -80
- data/src/TexChunk.hpp +44 -35
- data/src/Text.cpp +1 -1
- data/src/TextBuilder.cpp +35 -21
- data/src/TextBuilder.hpp +6 -9
- data/src/TextInput.cpp +9 -9
- data/src/Texture.cpp +62 -80
- data/src/Texture.hpp +25 -23
- data/src/TiledDrawable.cpp +149 -0
- data/src/TiledDrawable.hpp +47 -0
- data/src/TimingApple.cpp +1 -1
- data/src/Transform.cpp +45 -50
- data/src/TransformStack.hpp +16 -16
- data/src/TrueTypeFont.cpp +59 -51
- data/src/TrueTypeFont.hpp +6 -7
- data/src/TrueTypeFontApple.cpp +28 -19
- data/src/TrueTypeFontUnix.cpp +39 -32
- data/src/TrueTypeFontWin.cpp +30 -30
- data/src/Utility.cpp +113 -37
- data/src/UtilityWin.cpp +49 -0
- data/src/Window.cpp +121 -151
- data/src/WindowUIKit.cpp +14 -14
- metadata +165 -118
- data/dependencies/SDL/include/SDL.h +0 -233
- data/dependencies/SDL/include/SDL_assert.h +0 -320
- data/dependencies/SDL/include/SDL_atomic.h +0 -415
- data/dependencies/SDL/include/SDL_audio.h +0 -1500
- data/dependencies/SDL/include/SDL_clipboard.h +0 -141
- data/dependencies/SDL/include/SDL_config.h +0 -331
- data/dependencies/SDL/include/SDL_cpuinfo.h +0 -594
- data/dependencies/SDL/include/SDL_endian.h +0 -348
- data/dependencies/SDL/include/SDL_error.h +0 -163
- data/dependencies/SDL/include/SDL_events.h +0 -1166
- data/dependencies/SDL/include/SDL_filesystem.h +0 -149
- data/dependencies/SDL/include/SDL_gamecontroller.h +0 -1074
- data/dependencies/SDL/include/SDL_gesture.h +0 -117
- data/dependencies/SDL/include/SDL_guid.h +0 -100
- data/dependencies/SDL/include/SDL_haptic.h +0 -1341
- data/dependencies/SDL/include/SDL_hidapi.h +0 -451
- data/dependencies/SDL/include/SDL_hints.h +0 -2569
- data/dependencies/SDL/include/SDL_joystick.h +0 -1066
- data/dependencies/SDL/include/SDL_keyboard.h +0 -353
- data/dependencies/SDL/include/SDL_keycode.h +0 -358
- data/dependencies/SDL/include/SDL_loadso.h +0 -115
- data/dependencies/SDL/include/SDL_log.h +0 -404
- data/dependencies/SDL/include/SDL_main.h +0 -275
- data/dependencies/SDL/include/SDL_mouse.h +0 -465
- data/dependencies/SDL/include/SDL_mutex.h +0 -471
- data/dependencies/SDL/include/SDL_name.h +0 -33
- data/dependencies/SDL/include/SDL_pixels.h +0 -644
- data/dependencies/SDL/include/SDL_platform.h +0 -261
- data/dependencies/SDL/include/SDL_quit.h +0 -58
- data/dependencies/SDL/include/SDL_rect.h +0 -376
- data/dependencies/SDL/include/SDL_render.h +0 -1919
- data/dependencies/SDL/include/SDL_revision.h +0 -7
- data/dependencies/SDL/include/SDL_rwops.h +0 -841
- data/dependencies/SDL/include/SDL_sensor.h +0 -322
- data/dependencies/SDL/include/SDL_shape.h +0 -155
- data/dependencies/SDL/include/SDL_stdinc.h +0 -830
- data/dependencies/SDL/include/SDL_surface.h +0 -997
- data/dependencies/SDL/include/SDL_system.h +0 -623
- data/dependencies/SDL/include/SDL_syswm.h +0 -386
- data/dependencies/SDL/include/SDL_test_images.h +0 -78
- data/dependencies/SDL/include/SDL_test_random.h +0 -115
- data/dependencies/SDL/include/SDL_thread.h +0 -464
- data/dependencies/SDL/include/SDL_timer.h +0 -222
- data/dependencies/SDL/include/SDL_touch.h +0 -150
- data/dependencies/SDL/include/SDL_version.h +0 -204
- data/dependencies/SDL/include/SDL_video.h +0 -2150
- data/dependencies/SDL/include/SDL_vulkan.h +0 -215
- data/dependencies/SDL/include/begin_code.h +0 -187
- data/dependencies/SDL/lib/x64/libSDL2.dll.a +0 -0
- data/dependencies/SDL/lib/x86/libSDL2.dll.a +0 -0
- data/dependencies/SDL_sound/SDL_sound.h +0 -725
- data/ext/gosu/extconf.rb +0 -119
- data/include/Gosu/IO.hpp +0 -254
- data/include/Gosu/ImageData.hpp +0 -53
- data/include/Gosu/Inspection.hpp +0 -7
- data/lib/SDL2.dll +0 -0
- data/lib/gosu/patches.rb +0 -66
- data/lib/gosu/run.rb +0 -20
- data/lib/gosu/swig_patches.rb +0 -110
- data/lib64/SDL2.dll +0 -0
- data/src/BlockAllocator.cpp +0 -131
- data/src/BlockAllocator.hpp +0 -32
- data/src/DirectoriesApple.cpp +0 -69
- data/src/DirectoriesUnix.cpp +0 -46
- data/src/DirectoriesWin.cpp +0 -65
- data/src/EmptyImageData.hpp +0 -52
- data/src/FileUnix.cpp +0 -99
- data/src/FileWin.cpp +0 -88
- data/src/IO.cpp +0 -60
- data/src/Iconv.hpp +0 -51
- data/src/Inspection.cpp +0 -27
- data/src/LargeImageData.cpp +0 -215
- data/src/LargeImageData.hpp +0 -39
- data/src/Log.hpp +0 -19
- data/src/RubyGosu.cxx +0 -13100
- data/src/RubyGosu.h +0 -49
- data/src/WinUtility.cpp +0 -61
- data/src/WinUtility.hpp +0 -27
- /data/dependencies/SDL/include/{SDL_opengles2_gl2.h → SDL3/SDL_opengles2_gl2.h} +0 -0
- /data/dependencies/SDL/include/{SDL_opengles2_gl2ext.h → SDL3/SDL_opengles2_gl2ext.h} +0 -0
- /data/dependencies/SDL/include/{SDL_opengles2_gl2platform.h → SDL3/SDL_opengles2_gl2platform.h} +0 -0
- /data/dependencies/SDL/include/{SDL_opengles2_khrplatform.h → SDL3/SDL_opengles2_khrplatform.h} +0 -0
|
@@ -0,0 +1,755 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* SDL_sound; An abstract sound format decoding API.
|
|
3
|
+
*
|
|
4
|
+
* Please see the file LICENSE.txt in the source's root directory.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/* WIKI CATEGORY: SDLSound */
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* # CategorySDLSound
|
|
11
|
+
*
|
|
12
|
+
* The latest version of SDL_sound can be found at:
|
|
13
|
+
*
|
|
14
|
+
* https://icculus.org/SDL_sound/
|
|
15
|
+
*
|
|
16
|
+
* Note that SDL_sound is _not_ an official part of the SDL project, despite
|
|
17
|
+
* its name.
|
|
18
|
+
*
|
|
19
|
+
* The basic gist of SDL_sound is that you use an SDL_IOStream to get sound
|
|
20
|
+
* data into this library, and SDL_sound will take that data, in one of
|
|
21
|
+
* several popular formats, and decode it into raw waveform data in the format
|
|
22
|
+
* of your choice. This gives you a nice abstraction for getting sound into
|
|
23
|
+
* your game or application; just feed it to SDL_sound, and it will handle
|
|
24
|
+
* decoding and converting, so you can just pass it to your SDL audio callback
|
|
25
|
+
* (or whatever). Since it gets data from an SDL_IOStream, you can get the
|
|
26
|
+
* initial sound data from any number of sources: file, memory buffer, network
|
|
27
|
+
* connection, etc.
|
|
28
|
+
*
|
|
29
|
+
* As the name implies, this library depends on SDL: Simple Directmedia Layer,
|
|
30
|
+
* which is a powerful, free, and cross-platform multimedia library. It can be
|
|
31
|
+
* found at https://www.libsdl.org/
|
|
32
|
+
*
|
|
33
|
+
* Support is in place for the following sound formats:
|
|
34
|
+
*
|
|
35
|
+
* - .WAV (Microsoft WAVfile RIFF data, internal.)
|
|
36
|
+
* - .VOC (Creative Labs' Voice format, internal.)
|
|
37
|
+
* - .MP3 (MPEG-1 Layer 3 support, via libmpg123.)
|
|
38
|
+
* - .MID (MIDI music converted to Waveform data, internal.)
|
|
39
|
+
* - .MOD (MOD files, via internal copy of libModPlug.)
|
|
40
|
+
* - .OGG (Ogg files, via internal copy of stb_vorbis.)
|
|
41
|
+
* - .SHN (Shorten files, internal.)
|
|
42
|
+
* - .RAW (Raw sound data in any format, internal.)
|
|
43
|
+
* - .AU (Sun's Audio format, internal.)
|
|
44
|
+
* - .AIFF (Audio Interchange format, internal.)
|
|
45
|
+
* - .FLAC (Lossless audio compression, via libFLAC.)
|
|
46
|
+
*/
|
|
47
|
+
|
|
48
|
+
#ifndef SDL_SOUND_H_
|
|
49
|
+
#define SDL_SOUND_H_
|
|
50
|
+
|
|
51
|
+
#include <SDL3/SDL.h>
|
|
52
|
+
|
|
53
|
+
#if SDL_MAJOR_VERSION < 3
|
|
54
|
+
#error SDL3_sound requires SDL 3.0.0 or later.
|
|
55
|
+
#endif
|
|
56
|
+
|
|
57
|
+
#ifdef __cplusplus
|
|
58
|
+
extern "C" {
|
|
59
|
+
#endif
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* The current major version of the SDL_sound headers.
|
|
63
|
+
*
|
|
64
|
+
* If this were SDL_sound version 3.2.1, this value would be 3.
|
|
65
|
+
*
|
|
66
|
+
* \since This macro is available since SDL_sound 3.0.0.
|
|
67
|
+
*/
|
|
68
|
+
#define SDL_SOUND_MAJOR_VERSION 3
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The current minor version of the SDL_sound headers.
|
|
72
|
+
*
|
|
73
|
+
* If this were SDL_sound version 3.2.1, this value would be 2.
|
|
74
|
+
*
|
|
75
|
+
* \since This macro is available since SDL_sound 3.0.0.
|
|
76
|
+
*/
|
|
77
|
+
#define SDL_SOUND_MINOR_VERSION 3
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The current micro (or patchlevel) version of the SDL_sound headers.
|
|
81
|
+
*
|
|
82
|
+
* If this were SDL_sound version 3.2.1, this value would be 1.
|
|
83
|
+
*
|
|
84
|
+
* \since This macro is available since SDL_sound 3.0.0.
|
|
85
|
+
*/
|
|
86
|
+
#define SDL_SOUND_MICRO_VERSION 0
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* This is the version number macro for the current SDL_sound version.
|
|
90
|
+
*
|
|
91
|
+
* \since This macro is available since SDL_sound 3.0.0.
|
|
92
|
+
*
|
|
93
|
+
* \sa Sound_Version
|
|
94
|
+
*/
|
|
95
|
+
#define SDL_SOUND_VERSION \
|
|
96
|
+
SDL_VERSIONNUM(SDL_SOUND_MAJOR_VERSION, SDL_SOUND_MINOR_VERSION, SDL_SOUND_MICRO_VERSION)
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* This macro will evaluate to true if compiled with SDL_sound at least X.Y.Z.
|
|
100
|
+
*
|
|
101
|
+
* \since This macro is available since SDL_sound 3.0.0.
|
|
102
|
+
*/
|
|
103
|
+
#define SDL_SOUND_VERSION_ATLEAST(X, Y, Z) \
|
|
104
|
+
((SDL_SOUND_MAJOR_VERSION >= X) && \
|
|
105
|
+
(SDL_SOUND_MAJOR_VERSION > X || SDL_SOUND_MINOR_VERSION >= Y) && \
|
|
106
|
+
(SDL_SOUND_MAJOR_VERSION > X || SDL_SOUND_MINOR_VERSION > Y || SDL_SOUND_MICRO_VERSION >= Z))
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* This function gets the version of the dynamically linked SDL_sound library.
|
|
111
|
+
*
|
|
112
|
+
* \returns SDL_sound version.
|
|
113
|
+
*
|
|
114
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
115
|
+
*
|
|
116
|
+
* \since This function is available since SDL_sound 3.0.0.
|
|
117
|
+
*/
|
|
118
|
+
extern SDL_DECLSPEC int SDLCALL Sound_Version(void);
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Flags that are used in a Sound_Sample to show various states.
|
|
123
|
+
*
|
|
124
|
+
* \since This enum is available since SDL_sound 1.0.0.
|
|
125
|
+
*
|
|
126
|
+
* \sa Sound_SampleNew
|
|
127
|
+
* \sa Sound_SampleNewFromFile
|
|
128
|
+
* \sa Sound_SampleDecode
|
|
129
|
+
* \sa Sound_SampleDecodeAll
|
|
130
|
+
* \sa Sound_SampleSeek
|
|
131
|
+
*/
|
|
132
|
+
typedef enum Sound_SampleFlags
|
|
133
|
+
{
|
|
134
|
+
SOUND_SAMPLEFLAG_NONE = 0, /**< No special attributes. */
|
|
135
|
+
|
|
136
|
+
/* these are set at sample creation time... */
|
|
137
|
+
SOUND_SAMPLEFLAG_CANSEEK = 1, /**< Sample can seek to arbitrary points. */
|
|
138
|
+
|
|
139
|
+
/* these are set during decoding... */
|
|
140
|
+
SOUND_SAMPLEFLAG_EOF = 1 << 29, /**< End of input stream. */
|
|
141
|
+
SOUND_SAMPLEFLAG_ERROR = 1 << 30, /**< Unrecoverable error. */
|
|
142
|
+
SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /**< Function would block, or temp error. */
|
|
143
|
+
} Sound_SampleFlags;
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Sound_DecoderInfo Information about available sound decoders.
|
|
148
|
+
*
|
|
149
|
+
* Each decoder sets up one of these structs, which can be retrieved via the
|
|
150
|
+
* Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
|
|
151
|
+
*
|
|
152
|
+
* The extensions field is a NULL-terminated list of ASCIZ strings. You should
|
|
153
|
+
* read it like this:
|
|
154
|
+
*
|
|
155
|
+
* ```c
|
|
156
|
+
* for (const char **ext = info->extensions; *ext != NULL; ext++) {
|
|
157
|
+
* printf(" File extension \"%s\"\n", *ext);
|
|
158
|
+
* }
|
|
159
|
+
* ```
|
|
160
|
+
*
|
|
161
|
+
* \since This struct is available since SDL_sound 1.0.0.
|
|
162
|
+
*
|
|
163
|
+
* \sa Sound_AvailableDecoders
|
|
164
|
+
*/
|
|
165
|
+
typedef struct Sound_DecoderInfo
|
|
166
|
+
{
|
|
167
|
+
const char **extensions; /**< File extensions, list ends with NULL. */
|
|
168
|
+
const char *description; /**< Human readable description of decoder. */
|
|
169
|
+
const char *author; /**< "Name Of Author <email@emailhost.dom>" */
|
|
170
|
+
const char *url; /**< URL specific to this decoder. */
|
|
171
|
+
} Sound_DecoderInfo;
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Represents sound data in the process of being decoded.
|
|
177
|
+
*
|
|
178
|
+
* The Sound_Sample structure is the heart of SDL_sound. This holds
|
|
179
|
+
* information about a source of sound data as it is being decoded. EVERY
|
|
180
|
+
* FIELD IN THIS IS READ-ONLY. Please use the API functions to change them.
|
|
181
|
+
*
|
|
182
|
+
* \since This struct is available since SDL_sound 1.0.0.
|
|
183
|
+
*/
|
|
184
|
+
typedef struct Sound_Sample
|
|
185
|
+
{
|
|
186
|
+
void *opaque; /**< Internal use only. Don't touch. */
|
|
187
|
+
const Sound_DecoderInfo *decoder; /**< Decoder used for this sample. */
|
|
188
|
+
SDL_AudioSpec desired; /**< Desired audio format for conversion. */
|
|
189
|
+
SDL_AudioSpec actual; /**< Actual audio format of sample. */
|
|
190
|
+
void *buffer; /**< Decoded sound data lands in here. */
|
|
191
|
+
Uint32 buffer_size; /**< Current size of (buffer), in bytes (Uint8). */
|
|
192
|
+
Sound_SampleFlags flags; /**< Flags relating to this sample. */
|
|
193
|
+
} Sound_Sample;
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
/* functions and macros... */
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Initialize SDL_sound.
|
|
201
|
+
*
|
|
202
|
+
* This must be called before any other SDL_sound function (except perhaps
|
|
203
|
+
* Sound_Version()). You should call SDL_Init() before calling this.
|
|
204
|
+
* Sound_Init() will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case.
|
|
205
|
+
* This is a safe behaviour, but it may not configure SDL to your liking by
|
|
206
|
+
* itself.
|
|
207
|
+
*
|
|
208
|
+
* \returns nonzero on success, zero on error. Specifics of the error can be
|
|
209
|
+
* gleaned from Sound_GetError().
|
|
210
|
+
*
|
|
211
|
+
* \threadsafety This call is not thread-safe.
|
|
212
|
+
*
|
|
213
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
214
|
+
*
|
|
215
|
+
* \sa Sound_Quit
|
|
216
|
+
*/
|
|
217
|
+
extern SDL_DECLSPEC int SDLCALL Sound_Init(void);
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* Shutdown SDL_sound.
|
|
222
|
+
*
|
|
223
|
+
* This closes any SDL_IOStreams that were being used as sound sources, and
|
|
224
|
+
* frees any resources in use by SDL_sound.
|
|
225
|
+
*
|
|
226
|
+
* All Sound_Sample pointers you had prior to this call are invalidated.
|
|
227
|
+
*
|
|
228
|
+
* Once successfully deinitialized, Sound_Init() can be called again to
|
|
229
|
+
* restart the subsystem. All default API states are restored at this point.
|
|
230
|
+
*
|
|
231
|
+
* You should call this _before_ SDL_Quit(). This will _not_ call SDL_Quit()
|
|
232
|
+
* for you!
|
|
233
|
+
*
|
|
234
|
+
* \returns nonzero on success, zero on error. Specifics of the error can be
|
|
235
|
+
* gleaned from Sound_GetError(). If failure, state of SDL_sound is
|
|
236
|
+
* undefined, and probably badly screwed up.
|
|
237
|
+
*
|
|
238
|
+
* \threadsafety This call is not thread-safe.
|
|
239
|
+
*
|
|
240
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
241
|
+
*
|
|
242
|
+
* \sa Sound_Init
|
|
243
|
+
*/
|
|
244
|
+
extern SDL_DECLSPEC int SDLCALL Sound_Quit(void);
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Get a list of sound formats supported by this version of SDL_sound.
|
|
249
|
+
*
|
|
250
|
+
* This is for informational purposes only. Note that the extension listed is
|
|
251
|
+
* merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
|
|
252
|
+
* file with an extension of "XYZ", if you like. The file extensions are
|
|
253
|
+
* informational, and only required as a hint to choosing the correct decoder,
|
|
254
|
+
* since the sound data may not be coming from a file at all, thanks to the
|
|
255
|
+
* abstraction that an SDL_IOStream provides.
|
|
256
|
+
*
|
|
257
|
+
* The returned value is an array of pointers to Sound_DecoderInfo structures,
|
|
258
|
+
* with a NULL entry to signify the end of the list:
|
|
259
|
+
*
|
|
260
|
+
* ```c
|
|
261
|
+
* for (Sound_DecoderInfo **i = Sound_AvailableDecoders(); *i != NULL; i++)
|
|
262
|
+
* {
|
|
263
|
+
* printf("Supported sound format: [%s], which is [%s].\n",
|
|
264
|
+
* i->extension, i->description);
|
|
265
|
+
* // ...and other fields...
|
|
266
|
+
* }
|
|
267
|
+
* ```
|
|
268
|
+
*
|
|
269
|
+
* The return values are pointers to static internal memory, and should be
|
|
270
|
+
* considered READ ONLY, and never freed.
|
|
271
|
+
*
|
|
272
|
+
* \returns READ ONLY null-terminated array of READ ONLY structures.
|
|
273
|
+
*
|
|
274
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
275
|
+
*
|
|
276
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
277
|
+
*
|
|
278
|
+
* \sa Sound_DecoderInfo
|
|
279
|
+
*/
|
|
280
|
+
extern SDL_DECLSPEC const Sound_DecoderInfo ** SDLCALL Sound_AvailableDecoders(void);
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Get the last SDL_sound error message as a null-terminated string.
|
|
285
|
+
*
|
|
286
|
+
* This will be NULL if there's been no error since the last call to this
|
|
287
|
+
* function. The pointer returned by this call points to an internal buffer,
|
|
288
|
+
* and should not be deallocated. Each thread has a unique error state
|
|
289
|
+
* associated with it, but each time a new error message is set, it will
|
|
290
|
+
* overwrite the previous one associated with that thread. It is safe to call
|
|
291
|
+
* this function at anytime, even before Sound_Init().
|
|
292
|
+
*
|
|
293
|
+
* \returns READ ONLY string of last error message.
|
|
294
|
+
*
|
|
295
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
296
|
+
*
|
|
297
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
298
|
+
*
|
|
299
|
+
* \sa Sound_ClearError
|
|
300
|
+
*/
|
|
301
|
+
extern SDL_DECLSPEC const char * SDLCALL Sound_GetError(void);
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Clear the current error message.
|
|
306
|
+
*
|
|
307
|
+
* The next call to Sound_GetError() after Sound_ClearError() will return
|
|
308
|
+
* NULL.
|
|
309
|
+
*
|
|
310
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
311
|
+
*
|
|
312
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
313
|
+
*
|
|
314
|
+
* \sa Sound_GetError
|
|
315
|
+
*/
|
|
316
|
+
extern SDL_DECLSPEC void SDLCALL Sound_ClearError(void);
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* Start decoding a new sound sample.
|
|
321
|
+
*
|
|
322
|
+
* The data is read via an SDL_IOStream structure (see SDL_iostream.h in
|
|
323
|
+
* SDL3's include directory), so it may be coming from memory, disk, network
|
|
324
|
+
* stream, etc. The (ext) parameter is merely a hint to determining the
|
|
325
|
+
* correct decoder; if you specify, for example, "mp3" for an extension, and
|
|
326
|
+
* one of the decoders lists that as a handled extension, then that decoder is
|
|
327
|
+
* given first shot at trying to claim the data for decoding. If none of the
|
|
328
|
+
* extensions match (or the extension is NULL), then every decoder examines
|
|
329
|
+
* the data to determine if it can handle it, until one accepts it. In such a
|
|
330
|
+
* case your SDL_IOStream will need to be capable of rewinding to the start of
|
|
331
|
+
* the stream.
|
|
332
|
+
*
|
|
333
|
+
* If no decoders can handle the data, a NULL value is returned, and a human
|
|
334
|
+
* readable error message can be fetched from Sound_GetError().
|
|
335
|
+
*
|
|
336
|
+
* Optionally, a desired audio format can be specified. If the incoming data
|
|
337
|
+
* is in a different format, SDL_sound will convert it to the desired format
|
|
338
|
+
* on the fly. Note that this can be an expensive operation, so it may be wise
|
|
339
|
+
* to convert data before you need to play it back, if possible, or make sure
|
|
340
|
+
* your data is initially in the format that you need it in. If you don't want
|
|
341
|
+
* to convert the data, you can specify NULL for a desired format. The
|
|
342
|
+
* incoming format of the data, preconversion, can be found in the
|
|
343
|
+
* Sound_Sample structure.
|
|
344
|
+
*
|
|
345
|
+
* Note that the raw sound data "decoder" needs you to specify both the
|
|
346
|
+
* extension "RAW" and a "desired" format, or it will refuse to handle the
|
|
347
|
+
* data. This is to prevent it from catching all formats unsupported by the
|
|
348
|
+
* other decoders.
|
|
349
|
+
*
|
|
350
|
+
* Finally, specify an initial buffer size; this is the number of bytes that
|
|
351
|
+
* will be allocated to store each read from the sound buffer. The more you
|
|
352
|
+
* can safely allocate, the more decoding can be done in one block, but the
|
|
353
|
+
* more resources you have to use up, and the longer each decoding call will
|
|
354
|
+
* take. Note that different data formats require more or less space to store.
|
|
355
|
+
* This buffer can be resized later via Sound_SetBufferSize().
|
|
356
|
+
*
|
|
357
|
+
* The buffer size specified must be a multiple of the size of a single sample
|
|
358
|
+
* frame. So, if you want 16-bit, stereo samples, then your sample frame size
|
|
359
|
+
* is (2 channels * 16 bits), or 32 bits per frame, which is four bytes. In
|
|
360
|
+
* such a case, you could specify 128 or 132 bytes for a buffer, but not 129,
|
|
361
|
+
* 130, or 131 (although in reality, you'll want to specify a MUCH larger
|
|
362
|
+
* buffer).
|
|
363
|
+
*
|
|
364
|
+
* When you are done with this Sound_Sample pointer, you can dispose of it via
|
|
365
|
+
* Sound_FreeSample().
|
|
366
|
+
*
|
|
367
|
+
* You do not have to keep a reference to `io` around. If this function
|
|
368
|
+
* suceeds, it stores `io` internally (and disposes of it during the call to
|
|
369
|
+
* Sound_FreeSample()). If this function fails, it will dispose of the
|
|
370
|
+
* SDL_IOStream for you.
|
|
371
|
+
*
|
|
372
|
+
* \param io an SDL_IOStream with sound data.
|
|
373
|
+
* \param ext file extension normally associated with a data format. Can
|
|
374
|
+
* usually be NULL.
|
|
375
|
+
* \param desired format to convert sound data into. Can usually be NULL, if
|
|
376
|
+
* you don't need conversion.
|
|
377
|
+
* \param bufferSize size, in bytes, to allocate for the decoding buffer.
|
|
378
|
+
* \returns Sound_Sample pointer, which is used as a handle to several other
|
|
379
|
+
* SDL_sound APIs. NULL on error. If error, use Sound_GetError() to
|
|
380
|
+
* see what went wrong.
|
|
381
|
+
*
|
|
382
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
383
|
+
*
|
|
384
|
+
* \since This function is available since SDL_sound 1.0.0 (using SDL_RWops
|
|
385
|
+
* and Sound_AudioInfo; as of SDL_sound 3.0.0, this expects the SDL3
|
|
386
|
+
* equivalents, SDL_IOStream and SDL_AudioSpec, but is otherwise
|
|
387
|
+
* identical).
|
|
388
|
+
*
|
|
389
|
+
* \sa Sound_NewSampleFromFile
|
|
390
|
+
* \sa Sound_SetBufferSize
|
|
391
|
+
* \sa Sound_Decode
|
|
392
|
+
* \sa Sound_DecodeAll
|
|
393
|
+
* \sa Sound_Seek
|
|
394
|
+
* \sa Sound_Rewind
|
|
395
|
+
* \sa Sound_FreeSample
|
|
396
|
+
*/
|
|
397
|
+
extern SDL_DECLSPEC Sound_Sample * SDLCALL Sound_NewSample(SDL_IOStream *io,
|
|
398
|
+
const char *ext,
|
|
399
|
+
const SDL_AudioSpec *desired,
|
|
400
|
+
Uint32 bufferSize);
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* Start decoding a new sound sample from a file on disk.
|
|
404
|
+
*
|
|
405
|
+
* This is identical to Sound_NewSample(), but it creates an SDL_IOStream for
|
|
406
|
+
* you from the `size` bytes of memory referenced by `data`.
|
|
407
|
+
*
|
|
408
|
+
* \param data Buffer of data holding contents of an audio file to decode.
|
|
409
|
+
* \param size Size, in bytes, of buffer pointed to by (data).
|
|
410
|
+
* \param ext File extension normally associated with a data format. Can
|
|
411
|
+
* usually be NULL.
|
|
412
|
+
* \param desired Format to convert sound data into. Can usually be NULL, if
|
|
413
|
+
* you don't need conversion.
|
|
414
|
+
* \param bufferSize size, in bytes, of initial read buffer.
|
|
415
|
+
* \returns Sound_Sample pointer, which is used as a handle to several other
|
|
416
|
+
* SDL_sound APIs. NULL on error. If error, use Sound_GetError() to
|
|
417
|
+
* see what went wrong.
|
|
418
|
+
*
|
|
419
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
420
|
+
*
|
|
421
|
+
* \since This function is available since SDL_sound 1.0.0 (using
|
|
422
|
+
* Sound_AudioInfo; as of SDL_sound 3.0.0, this expects the SDL3
|
|
423
|
+
* equivalent, SDL_AudioSpec, but is otherwise identical).
|
|
424
|
+
*
|
|
425
|
+
* \sa Sound_NewSample
|
|
426
|
+
* \sa Sound_SetBufferSize
|
|
427
|
+
* \sa Sound_Decode
|
|
428
|
+
* \sa Sound_DecodeAll
|
|
429
|
+
* \sa Sound_Seek
|
|
430
|
+
* \sa Sound_Rewind
|
|
431
|
+
* \sa Sound_FreeSample
|
|
432
|
+
*/
|
|
433
|
+
extern SDL_DECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromMem(const Uint8 *data,
|
|
434
|
+
Uint32 size,
|
|
435
|
+
const char *ext,
|
|
436
|
+
const SDL_AudioSpec *desired,
|
|
437
|
+
Uint32 bufferSize);
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Start decoding a new sound sample from a file on disk.
|
|
442
|
+
*
|
|
443
|
+
* This is identical to Sound_NewSample(), but it creates an SDL_IOStream for
|
|
444
|
+
* you from the file located in `filename`. Note that `filename` is specified
|
|
445
|
+
* in platform-dependent notation. ("C:\\music\\mysong.mp3" on Windows, and
|
|
446
|
+
* "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
|
|
447
|
+
*
|
|
448
|
+
* Sound_NewSample()'s "ext" parameter is gleaned from the contents of
|
|
449
|
+
* `filename`.
|
|
450
|
+
*
|
|
451
|
+
* \param filename file containing sound data.
|
|
452
|
+
* \param desired Format to convert sound data into. Can usually be NULL, if
|
|
453
|
+
* you don't need conversion.
|
|
454
|
+
* \param bufferSize size, in bytes, of initial read buffer.
|
|
455
|
+
* \returns Sound_Sample pointer, which is used as a handle to several other
|
|
456
|
+
* SDL_sound APIs. NULL on error. If error, use Sound_GetError() to
|
|
457
|
+
* see what went wrong.
|
|
458
|
+
*
|
|
459
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
460
|
+
*
|
|
461
|
+
* \since This function is available since SDL_sound 1.0.0 (using
|
|
462
|
+
* Sound_AudioInfo; as of SDL_sound 3.0.0, this expects the SDL3
|
|
463
|
+
* equivalent, SDL_AudioSpec, but is otherwise identical).
|
|
464
|
+
*
|
|
465
|
+
* \sa Sound_NewSample
|
|
466
|
+
* \sa Sound_SetBufferSize
|
|
467
|
+
* \sa Sound_Decode
|
|
468
|
+
* \sa Sound_DecodeAll
|
|
469
|
+
* \sa Sound_Seek
|
|
470
|
+
* \sa Sound_Rewind
|
|
471
|
+
* \sa Sound_FreeSample
|
|
472
|
+
*/
|
|
473
|
+
extern SDL_DECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromFile(const char *filename,
|
|
474
|
+
const SDL_AudioSpec *desired,
|
|
475
|
+
Uint32 bufferSize);
|
|
476
|
+
|
|
477
|
+
/**
|
|
478
|
+
* Dispose of a Sound_Sample.
|
|
479
|
+
*
|
|
480
|
+
* This will also close/dispose of the SDL_IOStream that was used at creation
|
|
481
|
+
* time, so there's no need to keep a reference to that around. The
|
|
482
|
+
* Sound_Sample pointer is invalid after this call, and will almos certainly
|
|
483
|
+
* result in a crash if you attempt to keep using it.
|
|
484
|
+
*
|
|
485
|
+
* \param sample The Sound_Sample to delete.
|
|
486
|
+
*
|
|
487
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
488
|
+
*
|
|
489
|
+
* \since This function is available since SDL_sound 1.0.0 (using
|
|
490
|
+
* Sound_AudioInfo; as of SDL_sound 3.0.0, this expects the SDL3
|
|
491
|
+
* equivalent, SDL_AudioSpec, but is otherwise identical).
|
|
492
|
+
*
|
|
493
|
+
* \sa Sound_NewSample
|
|
494
|
+
* \sa Sound_NewSampleFromFile
|
|
495
|
+
*/
|
|
496
|
+
extern SDL_DECLSPEC void SDLCALL Sound_FreeSample(Sound_Sample *sample);
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* Retrieve total play time of sample, in milliseconds.
|
|
501
|
+
*
|
|
502
|
+
* Report total time length of sample, in milliseconds. This is a fast call.
|
|
503
|
+
* Duration is calculated during Sound_NewSample*, so this is just an accessor
|
|
504
|
+
* into otherwise opaque data.
|
|
505
|
+
*
|
|
506
|
+
* Please note that not all formats can determine a total time, some can't be
|
|
507
|
+
* exact without fully decoding the data, and thus will estimate the duration.
|
|
508
|
+
* Many decoders will require the ability to seek in the data stream to
|
|
509
|
+
* calculate this, so even if we can tell you how long an .ogg file will be,
|
|
510
|
+
* the same data set may fail if it's, say, streamed over an HTTP connection.
|
|
511
|
+
* Plan accordingly.
|
|
512
|
+
*
|
|
513
|
+
* Most people won't need this function to just decode and playback, but it
|
|
514
|
+
* can be useful for informational purposes in, say, a music player's UI.
|
|
515
|
+
*
|
|
516
|
+
* \param sample Sound_Sample from which to retrieve duration information.
|
|
517
|
+
* \returns Sample length in milliseconds, or -1 if duration can't be
|
|
518
|
+
* determined for any reason.
|
|
519
|
+
*
|
|
520
|
+
* \threadsafety It is safe to call this function from any thread.
|
|
521
|
+
*
|
|
522
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
523
|
+
*/
|
|
524
|
+
extern SDL_DECLSPEC Sint32 SDLCALL Sound_GetDuration(Sound_Sample *sample);
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
/**
|
|
528
|
+
* Change the current buffer size for a sample.
|
|
529
|
+
*
|
|
530
|
+
* If the buffer size could be changed, then the `sample->buffer` and
|
|
531
|
+
* `sample->buffer_size` fields will reflect that. If they could not be
|
|
532
|
+
* changed, then your original sample state is preserved. If the buffer is
|
|
533
|
+
* shrinking, the data at the end of buffer is truncated. If the buffer is
|
|
534
|
+
* growing, the contents of the new space at the end is undefined until you
|
|
535
|
+
* decode more into it or initialize it yourself.
|
|
536
|
+
*
|
|
537
|
+
* The buffer size specified must be a multiple of the size of a single sample
|
|
538
|
+
* frame. So, if you want 16-bit, stereo samples, then your sample frame size
|
|
539
|
+
* is (2 channels * 16 bits), or 32 bits per sample, which is four bytes. In
|
|
540
|
+
* such a case, you could specify 128 or 132 bytes for a buffer, but not 129,
|
|
541
|
+
* 130, or 131 (although in reality, you'll want to specify a MUCH larger
|
|
542
|
+
* buffer).
|
|
543
|
+
*
|
|
544
|
+
* \param sample The Sound_Sample whose buffer to modify.
|
|
545
|
+
* \param new_size The desired size, in bytes, of the new buffer.
|
|
546
|
+
* \returns non-zero if buffer size changed, zero on failure.
|
|
547
|
+
*
|
|
548
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
549
|
+
* single Sound_Sample should not be accessed from two threads
|
|
550
|
+
* at the same time.
|
|
551
|
+
*
|
|
552
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
553
|
+
*
|
|
554
|
+
* \sa Sound_Decode
|
|
555
|
+
* \sa Sound_DecodeAll
|
|
556
|
+
*/
|
|
557
|
+
extern SDL_DECLSPEC int SDLCALL Sound_SetBufferSize(Sound_Sample *sample,
|
|
558
|
+
Uint32 new_size);
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* Change the desired output format for a sample.
|
|
562
|
+
*
|
|
563
|
+
* Future calls to Sound_Decode() or Sound_DecodeAll() will produce audio in
|
|
564
|
+
* the newly-requested format; SDL_sound will convert on-the-fly while
|
|
565
|
+
* decoding, if necessary.
|
|
566
|
+
*
|
|
567
|
+
* The sample's buffer size, must be a multiple of the size of a single sample
|
|
568
|
+
* frame. If this is no longer the case after the format change, the buffer
|
|
569
|
+
* size will be reduced by a few bytes to accommodate this, but no actual
|
|
570
|
+
* reallocation of the buffer is made. Sound_SetBufferSize() can take more
|
|
571
|
+
* explicit control over the buffer after a format change.
|
|
572
|
+
*
|
|
573
|
+
* If `desired` is NULL, the sample's actual format is used, disabling audio
|
|
574
|
+
* conversion.
|
|
575
|
+
*
|
|
576
|
+
* If this function fails (out of memory setting up a new internal audio
|
|
577
|
+
* stream, etc), the sample remains usable with its current, unchanged format.
|
|
578
|
+
*
|
|
579
|
+
* \param sample The Sound_Sample whose format should be modified.
|
|
580
|
+
* \param desired The new desired format.
|
|
581
|
+
* \returns non-zero if format changed, zero on failure.
|
|
582
|
+
*
|
|
583
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
584
|
+
* single Sound_Sample should not be accessed from two threads
|
|
585
|
+
* at the same time.
|
|
586
|
+
*
|
|
587
|
+
* \since This function is available since SDL_sound 3.0.0.
|
|
588
|
+
*
|
|
589
|
+
* \sa Sound_Decode
|
|
590
|
+
* \sa Sound_DecodeAll
|
|
591
|
+
*/
|
|
592
|
+
extern SDL_DECLSPEC int SDLCALL Sound_SetDesiredFormat(Sound_Sample *sample, const SDL_AudioSpec *desired);
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
/**
|
|
596
|
+
* Decode more of the sound data in a Sound_Sample.
|
|
597
|
+
*
|
|
598
|
+
* It will decode at most `sample->buffer_size` bytes into `sample->buffer` in
|
|
599
|
+
* the desired format, and return the number of decoded bytes.
|
|
600
|
+
*
|
|
601
|
+
* If `sample->buffer_size` bytes could not be decoded, then please refer to
|
|
602
|
+
* `sample->flags` to determine if this was an end-of-stream or error
|
|
603
|
+
* condition.
|
|
604
|
+
*
|
|
605
|
+
* \param sample Do more decoding to this Sound_Sample.
|
|
606
|
+
* \returns number of bytes decoded into sample->buffer.
|
|
607
|
+
*
|
|
608
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
609
|
+
* single Sound_Sample should not be accessed from two threads
|
|
610
|
+
* at the same time.
|
|
611
|
+
*
|
|
612
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
613
|
+
*
|
|
614
|
+
* \sa Sound_DecodeAll
|
|
615
|
+
* \sa Sound_SetBufferSize
|
|
616
|
+
* \sa Sound_Seek
|
|
617
|
+
* \sa Sound_Rewind
|
|
618
|
+
*/
|
|
619
|
+
extern SDL_DECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample);
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
/**
|
|
623
|
+
* Decode the remainder of the sound data in a Sound_Sample.
|
|
624
|
+
*
|
|
625
|
+
* This will dynamically allocate memory for the ENTIRE remaining sample.
|
|
626
|
+
* `sample->buffer_size` and `sample->buffer` will be updated to reflect the
|
|
627
|
+
* new buffer. Please refer to sample->flags to determine if the decoding
|
|
628
|
+
* finished due to an end-of-stream or error condition.
|
|
629
|
+
*
|
|
630
|
+
* Be aware that sound data can take a large amount of memory, and that this
|
|
631
|
+
* function may block for quite awhile while processing. Also note that a
|
|
632
|
+
* streaming source (for example, from a SDL_IOStream that is getting fed from
|
|
633
|
+
* an Internet radio feed that doesn't end) may fill all available memory
|
|
634
|
+
* before giving up...be sure to use this on finite sound sources only!
|
|
635
|
+
*
|
|
636
|
+
* When decoding the sample in its entirety, the work is done one buffer at a
|
|
637
|
+
* time. That is, sound is decoded in `sample->buffer_size` blocks, and
|
|
638
|
+
* appended to a continually-growing buffer until the decoding completes. That
|
|
639
|
+
* means that this function will need enough RAM to hold approximately
|
|
640
|
+
* `sample->buffer_size` bytes plus the complete decoded sample at most. The
|
|
641
|
+
* larger your buffer size, the less overhead this function needs, but beware
|
|
642
|
+
* the possibility of paging to disk. Best to make this user-configurable if
|
|
643
|
+
* the sample isn't specific and small.
|
|
644
|
+
*
|
|
645
|
+
* \param sample do all decoding for this Sound_Sample.
|
|
646
|
+
* \returns number of bytes decoded into sample->buffer. You should check
|
|
647
|
+
* sample->flags to see what the current state of the sample is (EOF,
|
|
648
|
+
* error, read again).
|
|
649
|
+
*
|
|
650
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
651
|
+
* single Sound_Sample should not be accessed from two threads
|
|
652
|
+
* at the same time.
|
|
653
|
+
*
|
|
654
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
655
|
+
*
|
|
656
|
+
* \sa Sound_Decode
|
|
657
|
+
* \sa Sound_SetBufferSize
|
|
658
|
+
*/
|
|
659
|
+
extern SDL_DECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample);
|
|
660
|
+
|
|
661
|
+
|
|
662
|
+
/**
|
|
663
|
+
* Rewind a sample to the start.
|
|
664
|
+
*
|
|
665
|
+
* Restart a sample at the start of its waveform data, as if newly created
|
|
666
|
+
* with Sound_NewSample(). If successful, the next call to Sound_Decode() or
|
|
667
|
+
* Sound_DecodeAll() will give audio data from the earliest point in the
|
|
668
|
+
* stream.
|
|
669
|
+
*
|
|
670
|
+
* Beware that this function will fail if the SDL_IOStream that feeds the
|
|
671
|
+
* decoder can not be rewound via SDL_SeekIO(), but this can theoretically be
|
|
672
|
+
* avoided by wrapping it in some sort of buffering SDL_IOStream.
|
|
673
|
+
*
|
|
674
|
+
* This function should ONLY fail if the SDL_IOStream is not seekable, or
|
|
675
|
+
* SDL_sound is not initialized. Both can be controlled by the application,
|
|
676
|
+
* and thus, it is up to the developer's paranoia to dictate whether this
|
|
677
|
+
* function's return value need be checked at all.
|
|
678
|
+
*
|
|
679
|
+
* If this function fails, the state of the sample is undefined, but it is
|
|
680
|
+
* still safe to call Sound_FreeSample() to dispose of it.
|
|
681
|
+
*
|
|
682
|
+
* On success, SOUND_SAMPLEFLAG_ERROR, SOUND_SAMPLEFLAG_EOF, and
|
|
683
|
+
* SOUND_SAMPLEFLAG_EAGAIN are cleared from `sample->flags`. The
|
|
684
|
+
* SOUND_SAMPLEFLAG_ERROR flag will be set on error.
|
|
685
|
+
*
|
|
686
|
+
* \param sample the Sound_Sample to rewind.
|
|
687
|
+
* \returns nonzero on success, zero on error. Specifics of the error can be
|
|
688
|
+
* gleaned from Sound_GetError().
|
|
689
|
+
*
|
|
690
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
691
|
+
* single Sound_Sample should not be accessed from two threads
|
|
692
|
+
* at the same time.
|
|
693
|
+
*
|
|
694
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
695
|
+
*
|
|
696
|
+
* \sa Sound_Seek
|
|
697
|
+
*/
|
|
698
|
+
extern SDL_DECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample);
|
|
699
|
+
|
|
700
|
+
|
|
701
|
+
/**
|
|
702
|
+
* Seek to a different point in a sample.
|
|
703
|
+
*
|
|
704
|
+
* Reposition a sample's stream. If successful, the next call to
|
|
705
|
+
* Sound_Decode() or Sound_DecodeAll() will give audio data from the offset
|
|
706
|
+
* you specified.
|
|
707
|
+
*
|
|
708
|
+
* The offset is specified in milliseconds from the start of the sample.
|
|
709
|
+
*
|
|
710
|
+
* Beware that this function can fail for several reasons. If the SDL_IOStream
|
|
711
|
+
* that feeds the decoder can not seek, this call will almost certainly fail,
|
|
712
|
+
* but this can theoretically be avoided by wrapping it in some sort of
|
|
713
|
+
* buffering SDL_IOStream. Some decoders can never seek, others can only seek
|
|
714
|
+
* with certain files. The decoders will set a flag in the sample at creation
|
|
715
|
+
* time to help you determine this.
|
|
716
|
+
*
|
|
717
|
+
* You should check `sample->flags & SOUND_SAMPLEFLAG_CANSEEK` before
|
|
718
|
+
* attempting. Sound_Seek() reports failure immediately if this flag isn't
|
|
719
|
+
* set. This function can still fail for other reasons if the flag is set.
|
|
720
|
+
*
|
|
721
|
+
* This function can be emulated in the application with Sound_Rewind() and
|
|
722
|
+
* predecoding a specific amount of the sample, but this can be extremely
|
|
723
|
+
* inefficient. Sound_Seek() accelerates the seek with decoder-specific code.
|
|
724
|
+
*
|
|
725
|
+
* If this function fails, the sample should continue to function as if this
|
|
726
|
+
* call was never made. If there was an unrecoverable error, `sample->flags &
|
|
727
|
+
* SOUND_SAMPLEFLAG_ERROR` will be set, which your regular decoding loop can
|
|
728
|
+
* pick up.
|
|
729
|
+
*
|
|
730
|
+
* On success, SOUND_SAMPLEFLAG_ERROR, SOUND_SAMPLEFLAG_EOF, and
|
|
731
|
+
* SOUND_SAMPLEFLAG_EAGAIN are cleared from `sample->flags`.
|
|
732
|
+
*
|
|
733
|
+
* \param sample the Sound_Sample to seek.
|
|
734
|
+
* \param ms the new position, in milliseconds from start of sample.
|
|
735
|
+
* \returns nonzero on success, zero on error. Specifics of the error can be
|
|
736
|
+
* gleaned from Sound_GetError().
|
|
737
|
+
*
|
|
738
|
+
* \threadsafety It is safe to call this function from any thread, but a
|
|
739
|
+
* single Sound_Sample should not be accessed from two threads
|
|
740
|
+
* at the same time.
|
|
741
|
+
*
|
|
742
|
+
* \since This function is available since SDL_sound 1.0.0.
|
|
743
|
+
*
|
|
744
|
+
* \sa Sound_Rewind
|
|
745
|
+
*/
|
|
746
|
+
extern SDL_DECLSPEC int SDLCALL Sound_Seek(Sound_Sample *sample, Uint32 ms);
|
|
747
|
+
|
|
748
|
+
#ifdef __cplusplus
|
|
749
|
+
}
|
|
750
|
+
#endif
|
|
751
|
+
|
|
752
|
+
#endif /* !defined SDL_SOUND_H_ */
|
|
753
|
+
|
|
754
|
+
/* end of SDL_sound.h ... */
|
|
755
|
+
|