Mercurial > SDL_sound_CoreAudio
annotate SDL_sound.h @ 591:8faf61a640f0 tip
Resynced fixes for unit conversion bugs in the Ogg Tremor decoder from SoundDecoder/ALmixer.
Ogg Vorbis uses seconds and we multiply by 1000 to convert to milliseconds. But Ogg Tremor already uses milliseconds but I was still multiplying by 1000.
| author | Eric Wing <ewing . public |-at-| gmail . com> |
|---|---|
| date | Thu, 25 Oct 2012 16:34:18 -0700 |
| parents | 7e08477b0fc1 |
| 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 | 3 /* |
| 4 * SDL_sound -- An abstract sound format decoding API. | |
| 5 * Copyright (C) 2001 Ryan C. Gordon. | |
| 6 * | |
| 7 * This library is free software; you can redistribute it and/or | |
| 8 * modify it under the terms of the GNU Lesser General Public | |
| 9 * License as published by the Free Software Foundation; either | |
| 10 * version 2.1 of the License, or (at your option) any later version. | |
| 11 * | |
| 12 * This library is distributed in the hope that it will be useful, | |
| 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 15 * Lesser General Public License for more details. | |
| 16 * | |
| 17 * You should have received a copy of the GNU Lesser General Public | |
| 18 * License along with this library; if not, write to the Free Software | |
| 19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
| 20 */ | |
| 21 | |
| 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 | 28 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data |
| 29 * into this library, and SDL_sound will take that data, in one of several | |
| 30 * popular formats, and decode it into raw waveform data in the format of | |
| 31 * your choice. This gives you a nice abstraction for getting sound into your | |
| 32 * game or application; just feed it to SDL_sound, and it will handle | |
| 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 | 35 * the initial sound data from any number of sources: file, memory buffer, |
| 36 * network connection, etc. | |
| 37 * | |
| 38 * As the name implies, this library depends on SDL: Simple Directmedia Layer, | |
| 39 * which is a powerful, free, and cross-platform multimedia library. It can | |
| 40 * be found at http://www.libsdl.org/ | |
| 41 * | |
| 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.) |
|
562
7e08477b0fc1
MP3 decoder upgrade work.
Ryan C. Gordon <icculus@icculus.org>
parents:
552
diff
changeset
|
45 * - .MP3 (MPEG-1 Layer 3 support, via libmpg123.) |
|
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 | 55 * |
| 56 * (...and more to come...) | |
| 57 * | |
|
552
2e8907ff98e9
Replaced references to COPYING with references to LICENSE.txt ...
Ryan C. Gordon <icculus@icculus.org>
parents:
526
diff
changeset
|
58 * Please see the file LICENSE.txt in the source's root directory. |
| 0 | 59 * |
|
526
2df1f5c62d38
Updated my email address.
Ryan C. Gordon <icculus@icculus.org>
parents:
524
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 | 62 */ |
| 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 | 66 |
| 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 | 69 |
| 70 #ifdef __cplusplus | |
| 71 extern "C" { | |
| 72 #endif | |
| 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) |
|
524
a0bb7a9c05b1
Added -fvisibility=hidden support.
Ryan C. Gordon <icculus@icculus.org>
parents:
485
diff
changeset
|
82 #elif (__GNUC__ >= 3) |
|
a0bb7a9c05b1
Added -fvisibility=hidden support.
Ryan C. Gordon <icculus@icculus.org>
parents:
485
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 |
|
463
6e50a61059b8
Upped version to 1.0.1.
Ryan C. Gordon <icculus@icculus.org>
parents:
453
diff
changeset
|
90 #define SOUND_VER_PATCH 1 |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
91 #endif |
| 29 | 92 |
| 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 | 108 */ |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
109 typedef enum |
| 0 | 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 | 112 |
| 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 | 115 |
| 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 | 120 } Sound_SampleFlags; |
| 121 | |
| 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 | 176 * The Sound_Sample structure is the heart of SDL_sound. This holds |
| 177 * information about a source of sound data as it is being decoded. | |
| 178 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to | |
| 179 * change them. | |
| 180 */ | |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
181 typedef struct |
| 0 | 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 | 190 } Sound_Sample; |
| 191 | |
| 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 | 205 */ |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
206 typedef struct |
| 0 | 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 | 211 } Sound_Version; |
| 212 | |
| 213 | |
| 214 /* functions and macros... */ | |
| 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 | 239 |
| 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 | 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 | 248 * of SDL_sound you compiled against: |
| 249 * | |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
250 * \code |
| 0 | 251 * Sound_Version compiled; |
| 252 * Sound_Version linked; | |
| 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 | 255 * Sound_GetLinkedVersion(&linked); |
| 256 * printf("We compiled against SDL_sound version %d.%d.%d ...\n", | |
| 257 * compiled.major, compiled.minor, compiled.patch); | |
| 258 * printf("But we linked against SDL_sound version %d.%d.%d.\n", | |
| 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 | 261 * |
| 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 | 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 | 270 |
| 271 | |
| 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 | 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 | 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 | 288 |
| 289 | |
| 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 | 296 * |
| 297 * All Sound_Sample pointers you had prior to this call are INVALIDATED. | |
| 298 * | |
| 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 | 301 * point. |
| 302 * | |
| 303 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit() | |
| 304 * for you! | |
| 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 | 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 | 313 |
| 314 | |
| 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 | 320 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio |
| 0 | 321 * file with an extension of "XYZ", if you like. The file extensions are |
| 322 * informational, and only required as a hint to choosing the correct | |
| 323 * decoder, since the sound data may not be coming from a file at all, thanks | |
| 324 * to the abstraction that an SDL_RWops provides. | |
| 325 * | |
| 326 * The returned value is an array of pointers to Sound_DecoderInfo structures, | |
| 327 * with a NULL entry to signify the end of the list: | |
| 328 * | |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
329 * \code |
| 0 | 330 * Sound_DecoderInfo **i; |
| 331 * | |
| 332 * for (i = Sound_AvailableDecoders(); *i != NULL; i++) | |
| 333 * { | |
| 334 * printf("Supported sound format: [%s], which is [%s].\n", | |
| 335 * i->extension, i->description); | |
| 336 * // ...and other fields... | |
| 337 * } | |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
338 * \endcode |
| 0 | 339 * |
| 340 * The return values are pointers to static internal memory, and should | |
| 341 * be considered READ ONLY, and never freed. | |
| 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 | 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 | 348 |
| 349 | |
| 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 | 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 | 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 | 377 |
| 378 | |
| 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 | 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 | 397 * Optionally, a desired audio format can be specified. If the incoming data |
| 398 * is in a different format, SDL_sound will convert it to the desired format | |
| 399 * on the fly. Note that this can be an expensive operation, so it may be | |
| 400 * wise to convert data before you need to play it back, if possible, or | |
| 401 * make sure your data is initially in the format that you need it in. | |
| 402 * If you don't want to convert the data, you can specify NULL for a desired | |
| 403 * format. The incoming format of the data, preconversion, can be found | |
| 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 | 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 | 411 * Finally, specify an initial buffer size; this is the number of bytes that |
| 412 * will be allocated to store each read from the sound buffer. The more you | |
| 413 * can safely allocate, the more decoding can be done in one block, but the | |
| 414 * more resources you have to use up, and the longer each decoding call will | |
| 415 * take. Note that different data formats require more or less space to | |
| 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 /** |
|
485
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
457 * \fn Sound_Sample *Sound_NewSampleFromMem(const Uint8 *data, Sound_AudioInfo *desired, Uint32 bufferSize) |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
458 * \brief Start decoding a new sound sample from a file on disk. |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
459 * |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
460 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
461 * from the (size) bytes of memory referenced by (data). |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
462 * |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
463 * This can pool RWops structures, so it may fragment the heap less over time |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
464 * than using SDL_RWFromMem(). |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
465 * |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
466 * \param filename file containing sound data. |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
467 * \param desired Format to convert sound data into. Can usually be NULL, |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
468 * if you don't need conversion. |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
469 * \param bufferSize size, in bytes, of initial read buffer. |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
470 * \return Sound_Sample pointer, which is used as a handle to several other |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
471 * SDL_sound APIs. NULL on error. If error, use |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
472 * Sound_GetError() to see what went wrong. |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
473 * |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
474 * \sa Sound_NewSample |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
475 * \sa Sound_SetBufferSize |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
476 * \sa Sound_Decode |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
477 * \sa Sound_DecodeAll |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
478 * \sa Sound_Seek |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
479 * \sa Sound_Rewind |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
480 * \sa Sound_FreeSample |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
481 */ |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
482 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromMem(const Uint8 *data, |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
483 Uint32 size, |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
484 const char *ext, |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
485 Sound_AudioInfo *desired, |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
486 Uint32 bufferSize); |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
487 |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
488 |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
489 /** |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
490 * \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
|
491 * \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
|
492 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
493 * 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
|
494 * 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
|
495 * 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
|
496 * "/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
|
497 * 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
|
498 * (filename). |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
499 * |
|
485
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
500 * This can pool RWops structures, so it may fragment the heap less over time |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
501 * than using SDL_RWFromFile(). |
|
137c0b00ea4c
Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents:
477
diff
changeset
|
502 * |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
503 * \param filename file containing sound data. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
504 * \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
|
505 * if you don't need conversion. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
506 * \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
|
507 * \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
|
508 * 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
|
509 * Sound_GetError() to see what went wrong. |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
510 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
511 * \sa Sound_NewSample |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
512 * \sa Sound_SetBufferSize |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
513 * \sa Sound_Decode |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
514 * \sa Sound_DecodeAll |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
515 * \sa Sound_Seek |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
516 * \sa Sound_Rewind |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
517 * \sa Sound_FreeSample |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
518 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
519 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
|
520 Sound_AudioInfo *desired, |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
521 Uint32 bufferSize); |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
522 |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
523 /** |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
524 * \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
|
525 * \brief Dispose of a Sound_Sample. |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
526 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
527 * 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
|
528 * 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
|
529 * 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
|
530 * 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
|
531 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
532 * \param sample The Sound_Sample to delete. |
|
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
533 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
534 * \sa Sound_NewSample |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
535 * \sa Sound_NewSampleFromFile |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
536 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
537 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
|
538 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
539 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
540 /** |
|
477
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
541 * \fn Sint32 Sound_GetDuration(Sound_Sample *sample) |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
542 * \brief Retrieve total play time of sample, in milliseconds. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
543 * |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
544 * Report total time length of sample, in milliseconds. This is a fast |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
545 * call. Duration is calculated during Sound_NewSample*, so this is just |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
546 * an accessor into otherwise opaque data. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
547 * |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
548 * Please note that not all formats can determine a total time, some can't |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
549 * be exact without fully decoding the data, and thus will estimate the |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
550 * duration. Many decoders will require the ability to seek in the data |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
551 * stream to calculate this, so even if we can tell you how long an .ogg |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
552 * file will be, the same data set may fail if it's, say, streamed over an |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
553 * HTTP connection. Plan accordingly. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
554 * |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
555 * Most people won't need this function to just decode and playback, but it |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
556 * can be useful for informational purposes in, say, a music player's UI. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
557 * |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
558 * \param sample Sound_Sample from which to retrieve duration information. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
559 * \return Sample length in milliseconds, or -1 if duration can't be |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
560 * determined for any reason. |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
561 */ |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
562 SNDDECLSPEC Sint32 SDLCALL Sound_GetDuration(Sound_Sample *sample); |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
563 |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
564 |
|
3e705c9180e5
Fixed binary compatibility, added Sound_GetDuration().
Ryan C. Gordon <icculus@icculus.org>
parents:
474
diff
changeset
|
565 /** |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
566 * \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
|
567 * \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
|
568 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
569 * 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
|
570 * 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
|
571 * 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
|
572 * 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
|
573 * 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
|
574 * 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
|
575 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
576 * 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
|
577 * 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
|
578 * 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
|
579 * 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
|
580 * 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
|
581 * MUCH larger buffer). |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
582 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
583 * \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
|
584 * \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
|
585 * \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
|
586 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
587 * \sa Sound_Decode |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
588 * \sa Sound_DecodeAll |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
589 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
590 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
|
591 Uint32 new_size); |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
592 |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
593 |
|
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 * \fn Uint32 Sound_Decode(Sound_Sample *sample) |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
596 * \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
|
597 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
598 * 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
|
599 * desired format, and return the number of decoded bytes. |
| 0 | 600 * 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
|
601 * sample->flags to determine if this was an end-of-stream or error condition. |
| 0 | 602 * |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
603 * \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
|
604 * \return number of bytes decoded into sample->buffer. If it is less than |
| 0 | 605 * sample->buffer_size, then you should check sample->flags to see |
| 606 * 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
|
607 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
608 * \sa Sound_DecodeAll |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
609 * \sa Sound_SetBufferSize |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
610 * \sa Sound_Seek |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
611 * \sa Sound_Rewind |
| 0 | 612 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
613 SNDDECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample); |
| 0 | 614 |
| 615 | |
| 616 /** | |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
617 * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample) |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
618 * \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
|
619 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
620 * This will dynamically allocate memory for the ENTIRE remaining sample. |
| 0 | 621 * sample->buffer_size and sample->buffer will be updated to reflect the |
| 622 * new buffer. Please refer to sample->flags to determine if the decoding | |
| 623 * finished due to an End-of-stream or error condition. | |
| 624 * | |
| 625 * Be aware that sound data can take a large amount of memory, and that | |
| 626 * this function may block for quite awhile while processing. Also note | |
| 627 * that a streaming source (for example, from a SDL_RWops that is getting | |
| 628 * fed from an Internet radio feed that doesn't end) may fill all available | |
| 629 * memory before giving up...be sure to use this on finite sound sources | |
| 630 * only! | |
| 631 * | |
|
170
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
632 * 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
|
633 * 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
|
634 * 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
|
635 * 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
|
636 * 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
|
637 * 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
|
638 * 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
|
639 * the sample isn't specific and small. |
|
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
640 * |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
641 * \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
|
642 * \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
|
643 * 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
|
644 * (EOF, error, read again). |
|
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
645 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
646 * \sa Sound_Decode |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
647 * \sa Sound_SetBufferSize |
| 0 | 648 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
649 SNDDECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample); |
| 0 | 650 |
|
223
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
651 |
|
353
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 * \fn int Sound_Rewind(Sound_Sample *sample) |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
654 * \brief Rewind a sample to the start. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
655 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
656 * 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
|
657 * 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
|
658 * 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
|
659 * in the stream. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
660 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
661 * 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
|
662 * 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
|
663 * 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
|
664 * SDL_RWops. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
665 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
666 * 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
|
667 * 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
|
668 * 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
|
669 * 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
|
670 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
671 * 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
|
672 * 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
|
673 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
674 * 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
|
675 * ERROR flag is set on error. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
676 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
677 * \param sample The Sound_Sample to rewind. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
678 * \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
|
679 * error can be gleaned from Sound_GetError(). |
|
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
680 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
681 * \sa Sound_Seek |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
682 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
683 SNDDECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample); |
|
223
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
684 |
|
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
685 |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
686 /** |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
687 * \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
|
688 * \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
|
689 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
690 * 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
|
691 * 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
|
692 * specified. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
693 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
694 * 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
|
695 * sample. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
696 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
697 * 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
|
698 * 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
|
699 * 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
|
700 * 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
|
701 * 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
|
702 * 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
|
703 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
704 * 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
|
705 * 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
|
706 * 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
|
707 * flag is set. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
708 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
709 * 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
|
710 * 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
|
711 * 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
|
712 * with decoder-specific code. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
713 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
714 * 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
|
715 * 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
|
716 * 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
|
717 * decoding loop can pick up. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
718 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
719 * 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
|
720 * |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
721 * \param sample The Sound_Sample to seek. |
|
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
722 * \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
|
723 * \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
|
724 * error can be gleaned from Sound_GetError(). |
|
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
725 * |
|
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
726 * \sa Sound_Rewind |
|
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
727 */ |
|
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
728 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
|
729 |
| 0 | 730 #ifdef __cplusplus |
| 731 } | |
| 732 #endif | |
| 733 | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
734 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */ |
| 0 | 735 |
| 736 /* end of SDL_sound.h ... */ | |
| 737 |