annotate SDL_sound.h @ 569:d02c00ce16d9 stable-1.0

Clean up symbol visibility in the stable-1.0 branch.
author Ryan C. Gordon <icculus@icculus.org>
date Tue, 05 Jan 2010 15:03:43 -0500
parents 394e3ec86164
children
rev   line source
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
1 /** \file SDL_sound.h */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
2
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
3 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
4 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
5 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
6 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
7 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
8 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
9 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
10 * version 2.1 of the License, or (at your option) any later version.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
11 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
12 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
15 * Lesser General Public License for more details.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
17 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
18 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
20 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
21
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
22 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
23 * \mainpage SDL_sound
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
24 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
25 * The latest version of SDL_sound can be found at:
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
26 * http://icculus.org/SDL_sound/
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
27 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
28 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
29 * into this library, and SDL_sound will take that data, in one of several
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
30 * popular formats, and decode it into raw waveform data in the format of
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
31 * your choice. This gives you a nice abstraction for getting sound into your
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
32 * game or application; just feed it to SDL_sound, and it will handle
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
33 * decoding and converting, so you can just pass it to your SDL audio
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
34 * callback (or whatever). Since it gets data from an SDL_RWops, you can get
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
35 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
36 * network connection, etc.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
37 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
38 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
39 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
40 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
41 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
42 * Support is in place or planned for the following sound formats:
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
43 * - .WAV (Microsoft WAVfile RIFF data, internal.)
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
44 * - .VOC (Creative Labs' Voice format, internal.)
305
c345a40a8a99 VERY preliminary work on Sound_Seek() API.
Ryan C. Gordon <icculus@icculus.org>
parents: 252
diff changeset
45 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
46 * - .MID (MIDI music converted to Waveform data, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
47 * - .MOD (MOD files, via MikMod and ModPlug.)
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
48 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
453
b9856ba6fb4e Updated comments on supported files to include Speex.
Ryan C. Gordon <icculus@icculus.org>
parents: 427
diff changeset
49 * - .SPX (Speex files, via libspeex.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
50 * - .SHN (Shorten files, internal.)
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
51 * - .RAW (Raw sound data in any format, internal.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
52 * - .AU (Sun's Audio format, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
53 * - .AIFF (Audio Interchange format, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
54 * - .FLAC (Lossless audio compression, via libFLAC.)
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
55 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
56 * (...and more to come...)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
57 *
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
58 * Please see the file COPYING in the source's root directory.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
59 *
525
50bb9a6cebfe Updated my email address.
Ryan C. Gordon <icculus@icculus.org>
parents: 463
diff changeset
60 * \author Ryan C. Gordon (icculus@icculus.org)
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
61 * \author many others, please see CREDITS in the source's root directory.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
62 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
63
1
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
64 #ifndef _INCLUDE_SDL_SOUND_H_
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
65 #define _INCLUDE_SDL_SOUND_H_
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
66
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
67 #include "SDL.h"
19
734e5d75acec Now includes SDL_endian.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
68 #include "SDL_endian.h"
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
69
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
70 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
71 extern "C" {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
72 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
73
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
74 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
386
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
75
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
76 #ifndef SDLCALL /* may not be defined with older SDL releases. */
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
77 #define SDLCALL
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
78 #endif
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
79
130
ac49f81e42d6 Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents: 44
diff changeset
80 #ifdef SDL_SOUND_DLL_EXPORTS
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
81 # define SNDDECLSPEC __declspec(dllexport)
569
d02c00ce16d9 Clean up symbol visibility in the stable-1.0 branch.
Ryan C. Gordon <icculus@icculus.org>
parents: 549
diff changeset
82 #elif (__GNUC__ >= 3)
d02c00ce16d9 Clean up symbol visibility in the stable-1.0 branch.
Ryan C. Gordon <icculus@icculus.org>
parents: 549
diff changeset
83 # define SNDDECLSPEC __attribute__((visibility("default")))
386
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
84 #else
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
85 # define SNDDECLSPEC
130
ac49f81e42d6 Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents: 44
diff changeset
86 #endif
ac49f81e42d6 Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents: 44
diff changeset
87
427
ba94ffe34a47 Upped version to 1.0.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 417
diff changeset
88 #define SOUND_VER_MAJOR 1
ba94ffe34a47 Upped version to 1.0.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 417
diff changeset
89 #define SOUND_VER_MINOR 0
549
394e3ec86164 Upped version to 1.0.3.
Ryan C. Gordon <icculus@icculus.org>
parents: 543
diff changeset
90 #define SOUND_VER_PATCH 3
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
91 #endif
29
0e27c909c952 Upped version to 0.1.1
Ryan C. Gordon <icculus@icculus.org>
parents: 19
diff changeset
92
0e27c909c952 Upped version to 0.1.1
Ryan C. Gordon <icculus@icculus.org>
parents: 19
diff changeset
93
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
94 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
95 * \enum Sound_SampleFlags
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
96 * \brief Flags that are used in a Sound_Sample to show various states.
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
97 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
98 * To use:
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
99 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
100 * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
101 * \endcode
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
102 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
103 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
104 * \sa Sound_SampleNewFromFile
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
105 * \sa Sound_SampleDecode
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
106 * \sa Sound_SampleDecodeAll
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
107 * \sa Sound_SampleSeek
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
108 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
109 typedef enum
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
110 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
111 SOUND_SAMPLEFLAG_NONE = 0, /**< No special attributes. */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
112
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
113 /* these are set at sample creation time... */
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
114 SOUND_SAMPLEFLAG_CANSEEK = 1, /**< Sample can seek to arbitrary points. */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
115
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
116 /* these are set during decoding... */
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
117 SOUND_SAMPLEFLAG_EOF = 1 << 29, /**< End of input stream. */
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
118 SOUND_SAMPLEFLAG_ERROR = 1 << 30, /**< Unrecoverable error. */
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
119 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /**< Function would block, or temp error. */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
120 } Sound_SampleFlags;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
121
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
122
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
123 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
124 * \struct Sound_AudioInfo
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
125 * \brief Information about an existing sample's format.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
126 *
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
127 * These are the basics of a decoded sample's data structure: data format
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
128 * (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
129 * rate. If you need more explanation than that, you should stop developing
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
130 * sound code right now.
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
131 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
132 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
133 * \sa Sound_SampleNewFromFile
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
134 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
135 typedef struct
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
136 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
137 Uint16 format; /**< Equivalent of SDL_AudioSpec.format. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
138 Uint8 channels; /**< Number of sound channels. 1 == mono, 2 == stereo. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
139 Uint32 rate; /**< Sample rate; frequency of sample points per second. */
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
140 } Sound_AudioInfo;
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
141
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
142
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
143 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
144 * \struct Sound_DecoderInfo
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
145 * \brief Information about available soudn decoders.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
146 *
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
147 * Each decoder sets up one of these structs, which can be retrieved via
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
148 * the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
149 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
150 * The extensions field is a NULL-terminated list of ASCIZ strings. You
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
151 * should read it like this:
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
152 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
153 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
154 * const char **ext;
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
155 * for (ext = info->extensions; *ext != NULL; ext++) {
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
156 * printf(" File extension \"%s\"\n", *ext);
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
157 * }
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
158 * \endcode
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
159 *
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
160 * \sa Sound_AvailableDecoders
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
161 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
162 typedef struct
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
163 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
164 const char **extensions; /**< File extensions, list ends with NULL. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
165 const char *description; /**< Human readable description of decoder. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
166 const char *author; /**< "Name Of Author \<email@emailhost.dom\>" */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
167 const char *url; /**< URL specific to this decoder. */
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
168 } Sound_DecoderInfo;
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
169
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
170
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
171
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
172 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
173 * \struct Sound_Sample
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
174 * \brief Represents sound data in the process of being decoded.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
175 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
176 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
177 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
178 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
179 * change them.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
180 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
181 typedef struct
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
182 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
183 void *opaque; /**< Internal use only. Don't touch. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
184 const Sound_DecoderInfo *decoder; /**< Decoder used for this sample. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
185 Sound_AudioInfo desired; /**< Desired audio format for conversion. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
186 Sound_AudioInfo actual; /**< Actual audio format of sample. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
187 void *buffer; /**< Decoded sound data lands in here. */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
188 Uint32 buffer_size; /**< Current size of (buffer), in bytes (Uint8). */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
189 Sound_SampleFlags flags; /**< Flags relating to this sample. */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
190 } Sound_Sample;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
191
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
192
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
193 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
194 * \struct Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
195 * \brief Information the version of SDL_sound in use.
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
196 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
197 * Represents the library's version as three levels: major revision
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
198 * (increments with massive changes, additions, and enhancements),
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
199 * minor revision (increments with backwards-compatible changes to the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
200 * major revision), and patchlevel (increments with fixes to the minor
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
201 * revision).
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
202 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
203 * \sa SOUND_VERSION
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
204 * \sa Sound_GetLinkedVersion
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
205 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
206 typedef struct
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
207 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
208 int major; /**< major revision */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
209 int minor; /**< minor revision */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
210 int patch; /**< patchlevel */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
211 } Sound_Version;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
212
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
213
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
214 /* functions and macros... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
215
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
216 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
217 * \def SOUND_VERSION(x)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
218 * \brief Macro to determine SDL_sound version program was compiled against.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
219 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
220 * This macro fills in a Sound_Version structure with the version of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
221 * library you compiled against. This is determined by what header the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
222 * compiler uses. Note that if you dynamically linked the library, you might
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
223 * have a slightly newer or older version at runtime. That version can be
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
224 * determined with Sound_GetLinkedVersion(), which, unlike SOUND_VERSION,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
225 * is not a macro.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
226 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
227 * \param x A pointer to a Sound_Version struct to initialize.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
228 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
229 * \sa Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
230 * \sa Sound_GetLinkedVersion
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
231 */
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
232 #define SOUND_VERSION(x) \
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
233 { \
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
234 (x)->major = SOUND_VER_MAJOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
235 (x)->minor = SOUND_VER_MINOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
236 (x)->patch = SOUND_VER_PATCH; \
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
237 }
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
238
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
239
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
240 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
241 * \fn void Sound_GetLinkedVersion(Sound_Version *ver)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
242 * \brief Get the version of SDL_sound that is linked against your program.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
243 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
244 * If you are using a shared library (DLL) version of SDL_sound, then it is
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
245 * possible that it will be different than the version you compiled against.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
246 *
1
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
247 * This is a real function; the macro SOUND_VERSION tells you what version
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
248 * of SDL_sound you compiled against:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
249 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
250 * \code
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
251 * Sound_Version compiled;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
252 * Sound_Version linked;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
253 *
1
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
254 * SOUND_VERSION(&compiled);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
255 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
256 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
257 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
258 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
259 * linked.major, linked.minor, linked.patch);
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
260 * \endcode
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
261 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
262 * This function may be called safely at any time, even before Sound_Init().
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
263 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
264 * \param ver Sound_Version structure to fill with shared library's version.
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
265 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
266 * \sa Sound_Version
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
267 * \sa SOUND_VERSION
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
268 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
269 SNDDECLSPEC void SDLCALL Sound_GetLinkedVersion(Sound_Version *ver);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
270
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
271
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
272 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
273 * \fn Sound_Init(void)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
274 * \brief Initialize SDL_sound.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
275 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
276 * This must be called before any other SDL_sound function (except perhaps
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
277 * Sound_GetLinkedVersion()). You should call SDL_Init() before calling this.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
278 * Sound_Init() will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
279 * This is a safe behaviour, but it may not configure SDL to your liking by
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
280 * itself.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
281 *
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
282 * \return nonzero on success, zero on error. Specifics of the
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
283 * error can be gleaned from Sound_GetError().
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
284 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
285 * \sa Sound_Quit
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
286 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
287 SNDDECLSPEC int SDLCALL Sound_Init(void);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
288
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
289
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
290 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
291 * \fn Sound_Quit(void)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
292 * \brief Shutdown SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
293 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
294 * This closes any SDL_RWops that were being used as sound sources, and frees
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
295 * any resources in use by SDL_sound.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
296 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
297 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
298 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
299 * Once successfully deinitialized, Sound_Init() can be called again to
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
300 * restart the subsystem. All default API states are restored at this
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
301 * point.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
302 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
303 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
304 * for you!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
305 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
306 * \return nonzero on success, zero on error. Specifics of the error
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
307 * can be gleaned from Sound_GetError(). If failure, state of
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
308 * SDL_sound is undefined, and probably badly screwed up.
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
309 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
310 * \sa Sound_Init
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
311 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
312 SNDDECLSPEC int SDLCALL Sound_Quit(void);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
313
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
314
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
315 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
316 * \fn const Sound_DecoderInfo **Sound_AvailableDecoders(void)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
317 * \brief Get a list of sound formats supported by this version of SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
318 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
319 * This is for informational purposes only. Note that the extension listed is
11
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
320 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
321 * file with an extension of "XYZ", if you like. The file extensions are
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
322 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
323 * decoder, since the sound data may not be coming from a file at all, thanks
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
324 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
325 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
326 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
327 * with a NULL entry to signify the end of the list:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
328 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
329 * \code
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
330 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
331 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
332 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
333 * {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
334 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
335 * i->extension, i->description);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
336 * // ...and other fields...
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
337 * }
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
338 * \endcode
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
339 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
340 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
341 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
342 *
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
343 * \return READ ONLY Null-terminated array of READ ONLY structures.
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
344 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
345 * \sa Sound_DecoderInfo
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
346 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
347 SNDDECLSPEC const Sound_DecoderInfo ** SDLCALL Sound_AvailableDecoders(void);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
348
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
349
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
350 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
351 * \fn const char *Sound_GetError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
352 * \brief Get the last SDL_sound error message as a null-terminated string.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
353 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
354 * This will be NULL if there's been no error since the last call to this
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
355 * function. The pointer returned by this call points to an internal buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
356 * and should not be deallocated. Each thread has a unique error state
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
357 * associated with it, but each time a new error message is set, it will
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
358 * overwrite the previous one associated with that thread. It is safe to call
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
359 * this function at anytime, even before Sound_Init().
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
360 *
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
361 * \return READ ONLY string of last error message.
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
362 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
363 * \sa Sound_ClearError
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
364 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
365 SNDDECLSPEC const char * SDLCALL Sound_GetError(void);
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
366
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
367
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
368 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
369 * \fn void Sound_ClearError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
370 * \brief Clear the current error message.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
371 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
372 * The next call to Sound_GetError() after Sound_ClearError() will return NULL.
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
373 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
374 * \sa Sound_GetError
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
375 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
376 SNDDECLSPEC void SDLCALL Sound_ClearError(void);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
377
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
378
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
379 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
380 * \fn Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext, Sound_AudioInfo *desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
381 * \brief Start decoding a new sound sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
382 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
383 * The data is read via an SDL_RWops structure (see SDL_rwops.h in the SDL
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
384 * include directory), so it may be coming from memory, disk, network stream,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
385 * etc. The (ext) parameter is merely a hint to determining the correct
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
386 * decoder; if you specify, for example, "mp3" for an extension, and one of
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
387 * the decoders lists that as a handled extension, then that decoder is given
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
388 * first shot at trying to claim the data for decoding. If none of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
389 * extensions match (or the extension is NULL), then every decoder examines
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
390 * the data to determine if it can handle it, until one accepts it. In such a
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
391 * case your SDL_RWops will need to be capable of rewinding to the start of
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
392 * the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
393 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
394 * If no decoders can handle the data, a NULL value is returned, and a human
186
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
395 * readable error message can be fetched from Sound_GetError().
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
396 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
397 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
398 * is in a different format, SDL_sound will convert it to the desired format
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
399 * on the fly. Note that this can be an expensive operation, so it may be
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
400 * wise to convert data before you need to play it back, if possible, or
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
401 * make sure your data is initially in the format that you need it in.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
402 * If you don't want to convert the data, you can specify NULL for a desired
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
403 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
404 * in the Sound_Sample structure.
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
405 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
406 * Note that the raw sound data "decoder" needs you to specify both the
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
407 * extension "RAW" and a "desired" format, or it will refuse to handle
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
408 * the data. This is to prevent it from catching all formats unsupported
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
409 * by the other decoders.
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
410 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
411 * Finally, specify an initial buffer size; this is the number of bytes that
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
412 * will be allocated to store each read from the sound buffer. The more you
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
413 * can safely allocate, the more decoding can be done in one block, but the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
414 * more resources you have to use up, and the longer each decoding call will
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
415 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
416 * store. This buffer can be resized via Sound_SetBufferSize() ...
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
417 *
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
418 * The buffer size specified must be a multiple of the size of a single
186
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
419 * sample point. So, if you want 16-bit, stereo samples, then your sample
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
420 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
421 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
422 * but not 129, 130, or 131 (although in reality, you'll want to specify a
70561bf8d5fd Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
423 * MUCH larger buffer).
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
424 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
425 * When you are done with this Sound_Sample pointer, you can dispose of it
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
426 * via Sound_FreeSample().
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
427 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
428 * You do not have to keep a reference to (rw) around. If this function
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
429 * suceeds, it stores (rw) internally (and disposes of it during the call
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
430 * to Sound_FreeSample()). If this function fails, it will dispose of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
431 * SDL_RWops for you.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
432 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
433 * \param rw SDL_RWops with sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
434 * \param ext File extension normally associated with a data format.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
435 * Can usually be NULL.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
436 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
437 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
438 * \param bufferSize Size, in bytes, to allocate for the decoding buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
439 * \return Sound_Sample pointer, which is used as a handle to several other
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
440 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
441 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
442 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
443 * \sa Sound_NewSampleFromFile
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
444 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
445 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
446 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
447 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
448 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
449 * \sa Sound_FreeSample
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
450 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
451 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSample(SDL_RWops *rw,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
452 const char *ext,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
453 Sound_AudioInfo *desired,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
454 Uint32 bufferSize);
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
455
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
456 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
457 * \fn Sound_Sample *Sound_NewSampleFromFile(const char *filename, Sound_AudioInfo *desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
458 * \brief Start decoding a new sound sample from a file on disk.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
459 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
460 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
461 * from the file located in (filename). Note that (filename) is specified in
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
462 * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
463 * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
464 * Sound_NewSample()'s "ext" parameter is gleaned from the contents of
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
465 * (filename).
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
466 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
467 * \param filename file containing sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
468 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
469 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
470 * \param bufferSize size, in bytes, of initial read buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
471 * \return Sound_Sample pointer, which is used as a handle to several other
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
472 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
473 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
474 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
475 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
476 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
477 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
478 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
479 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
480 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
481 * \sa Sound_FreeSample
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
482 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
483 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromFile(const char *fname,
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
484 Sound_AudioInfo *desired,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
485 Uint32 bufferSize);
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
486
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
487 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
488 * \fn void Sound_FreeSample(Sound_Sample *sample)
389
fced17b9890c Fixed a typo in the comments (and as such, also in the Doxygen output).
Ryan C. Gordon <icculus@icculus.org>
parents: 386
diff changeset
489 * \brief Dispose of a Sound_Sample.
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
490 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
491 * This will also close/dispose of the SDL_RWops that was used at creation
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
492 * time, so there's no need to keep a reference to that around.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
493 * The Sound_Sample pointer is invalid after this call, and will almost
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
494 * certainly result in a crash if you attempt to keep using it.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
495 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
496 * \param sample The Sound_Sample to delete.
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
497 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
498 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
499 * \sa Sound_NewSampleFromFile
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
500 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
501 SNDDECLSPEC void SDLCALL Sound_FreeSample(Sound_Sample *sample);
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
502
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
503
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
504 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
505 * \fn int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
506 * \brief Change the current buffer size for a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
507 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
508 * If the buffer size could be changed, then the sample->buffer and
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
509 * sample->buffer_size fields will reflect that. If they could not be
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
510 * changed, then your original sample state is preserved. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
511 * shrinking, the data at the end of buffer is truncated. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
512 * growing, the contents of the new space at the end is undefined until you
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
513 * decode more into it or initialize it yourself.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
514 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
515 * The buffer size specified must be a multiple of the size of a single
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
516 * sample point. So, if you want 16-bit, stereo samples, then your sample
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
517 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
518 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
519 * but not 129, 130, or 131 (although in reality, you'll want to specify a
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
520 * MUCH larger buffer).
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
521 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
522 * \param sample The Sound_Sample whose buffer to modify.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
523 * \param new_size The desired size, in bytes, of the new buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
524 * \return non-zero if buffer size changed, zero on failure.
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
525 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
526 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
527 * \sa Sound_DecodeAll
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
528 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
529 SNDDECLSPEC int SDLCALL Sound_SetBufferSize(Sound_Sample *sample,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
530 Uint32 new_size);
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
531
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
532
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
533 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
534 * \fn Uint32 Sound_Decode(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
535 * \brief Decode more of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
536 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
537 * It will decode at most sample->buffer_size bytes into sample->buffer in the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
538 * desired format, and return the number of decoded bytes.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
539 * If sample->buffer_size bytes could not be decoded, then please refer to
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
540 * sample->flags to determine if this was an end-of-stream or error condition.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
541 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
542 * \param sample Do more decoding to this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
543 * \return number of bytes decoded into sample->buffer. If it is less than
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
544 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
545 * what the current state of the sample is (EOF, error, read again).
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
546 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
547 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
548 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
549 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
550 * \sa Sound_Rewind
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
551 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
552 SNDDECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
553
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
554
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
555 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
556 * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
557 * \brief Decode the remainder of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
558 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
559 * This will dynamically allocate memory for the ENTIRE remaining sample.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
560 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
561 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
562 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
563 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
564 * Be aware that sound data can take a large amount of memory, and that
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
565 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
566 * that a streaming source (for example, from a SDL_RWops that is getting
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
567 * fed from an Internet radio feed that doesn't end) may fill all available
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
568 * memory before giving up...be sure to use this on finite sound sources
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
569 * only!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
570 *
170
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
571 * When decoding the sample in its entirety, the work is done one buffer at a
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
572 * time. That is, sound is decoded in sample->buffer_size blocks, and
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
573 * appended to a continually-growing buffer until the decoding completes.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
574 * That means that this function will need enough RAM to hold approximately
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
575 * sample->buffer_size bytes plus the complete decoded sample at most. The
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
576 * larger your buffer size, the less overhead this function needs, but beware
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
577 * the possibility of paging to disk. Best to make this user-configurable if
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
578 * the sample isn't specific and small.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
579 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
580 * \param sample Do all decoding for this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
581 * \return number of bytes decoded into sample->buffer. You should check
170
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
582 * sample->flags to see what the current state of the sample is
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 149
diff changeset
583 * (EOF, error, read again).
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
584 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
585 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
586 * \sa Sound_SetBufferSize
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
587 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
588 SNDDECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample);
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
589
223
249186e31431 Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents: 194
diff changeset
590
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
591 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
592 * \fn int Sound_Rewind(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
593 * \brief Rewind a sample to the start.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
594 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
595 * Restart a sample at the start of its waveform data, as if newly
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
596 * created with Sound_NewSample(). If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
597 * Sound_Decode[All]() will give audio data from the earliest point
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
598 * in the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
599 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
600 * Beware that this function will fail if the SDL_RWops that feeds the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
601 * decoder can not be rewound via it's seek method, but this can
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
602 * theoretically be avoided by wrapping it in some sort of buffering
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
603 * SDL_RWops.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
604 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
605 * This function should ONLY fail if the RWops is not seekable, or
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
606 * SDL_sound is not initialized. Both can be controlled by the application,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
607 * and thus, it is up to the developer's paranoia to dictate whether this
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
608 * function's return value need be checked at all.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
609 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
610 * If this function fails, the state of the sample is undefined, but it
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
611 * is still safe to call Sound_FreeSample() to dispose of it.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
612 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
613 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
614 * ERROR flag is set on error.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
615 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
616 * \param sample The Sound_Sample to rewind.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
617 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
618 * error can be gleaned from Sound_GetError().
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
619 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
620 * \sa Sound_Seek
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
621 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
622 SNDDECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample);
223
249186e31431 Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents: 194
diff changeset
623
249186e31431 Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents: 194
diff changeset
624
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
625 /**
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
626 * \fn int Sound_Seek(Sound_Sample *sample, Uint32 ms)
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
627 * \brief Seek to a different point in a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
628 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
629 * Reposition a sample's stream. If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
630 * Sound_Decode[All]() will give audio data from the offset you
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
631 * specified.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
632 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
633 * The offset is specified in milliseconds from the start of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
634 * sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
635 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
636 * Beware that this function can fail for several reasons. If the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
637 * SDL_RWops that feeds the decoder can not seek, this call will almost
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
638 * certainly fail, but this can theoretically be avoided by wrapping it
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
639 * in some sort of buffering SDL_RWops. Some decoders can never seek,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
640 * others can only seek with certain files. The decoders will set a flag
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
641 * in the sample at creation time to help you determine this.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
642 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
643 * You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
644 * before attempting. Sound_Seek() reports failure immediately if this
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
645 * flag isn't set. This function can still fail for other reasons if the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
646 * flag is set.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
647 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
648 * This function can be emulated in the application with Sound_Rewind()
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
649 * and predecoding a specific amount of the sample, but this can be
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
650 * extremely inefficient. Sound_Seek() accelerates the seek on a
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
651 * with decoder-specific code.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
652 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
653 * If this function fails, the sample should continue to function as if
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
654 * this call was never made. If there was an unrecoverable error,
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
655 * sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
656 * decoding loop can pick up.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
657 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
658 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
659 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
660 * \param sample The Sound_Sample to seek.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
661 * \param ms The new position, in milliseconds from start of sample.
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
662 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
663 * error can be gleaned from Sound_GetError().
357
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
664 *
b3ac77d08e79 More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents: 353
diff changeset
665 * \sa Sound_Rewind
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
666 */
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
667 SNDDECLSPEC int SDLCALL Sound_Seek(Sound_Sample *sample, Uint32 ms);
305
c345a40a8a99 VERY preliminary work on Sound_Seek() API.
Ryan C. Gordon <icculus@icculus.org>
parents: 252
diff changeset
668
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
669 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
670 }
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
671 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
672
1
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
673 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
674
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
675 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
676