Mercurial > SDL_sound_CoreAudio
annotate SDL_sound.h @ 474:c66080364dff
Most decoders now report total sample play time, now. Technically, this
breaks binary compatibility with the 1.0 branch, since it extends the
Sound_Sample struct, but most (all?) programs are just passing pointers
allocated by SDL_sound around, and might be okay.
Source-level compatibility is not broken...yet! :)
--ryan.
-------- Original Message --------
Subject: SDL_sound patch: Finding total length of time of sound file.
Date: Sun, 26 Jan 2003 09:31:17 -0800 (PST)
Hi Ryan,
I am working with Eric Wing and helping him modify
SDL_sound. AS part of our efforts in improving and
enhancing SDL_sound, we like to submit this patch. We
modified the codecs to find the total time of a sound
file. Below is the explanation of the patch. The
patch is appended as an attachment to this email.
* MOTIVATION:
We needed the ability to get the total play time of a
sample (And we noticed that we're not the only ones).
Since SDL_sound blocks direct access to the specific
decoders, there is no way for a user to know this
information short of decoding the whole thing.
Because of this, we believe this will be a useful
addition, even though the accuracy may not be perfect
(subject to each decoder) or the information may not
always be available.
* CONTRIBUTORS:
Wesley Leong (modified the majority of the codecs and
verified the results)
Eric Wing (showed everyone how to do modify codec,
modified mikmod)
Wang Lam (modified a handful of codecs, researched
into specs and int overflow)
Ahilan Anantha (modified a few codecs and helped with
integer math)
* GENERAL ISSUES:
We chose the value to be milliseconds as an Sint32.
Milliseconds because that's what Sound_Seek takes as a
parameter and -1 to allow for instances/codecs where
the value could not be determined. We are
not sure if this is the final convention you want, so
we are willing to work with you on this.
We also expect the total_time field to be set on open
and never again modified by SDL_sound. Users may
access it directly much like the sample buffer and
buffer_size. We thought about recomputing the time
on DecodeAll, but since users may seek or decode small
chunks first, not all the data may be there. So this
is better done by the user. This may be good
information to document.
Currently, all the main codecs are implemented except
for QuickTime.
author | Ryan C. Gordon <icculus@icculus.org> |
---|---|
date | Sat, 08 May 2004 08:19:50 +0000 |
parents | 6e50a61059b8 |
children | 3e705c9180e5 |
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.) |
305
c345a40a8a99
VERY preliminary work on Sound_Seek() API.
Ryan C. Gordon <icculus@icculus.org>
parents:
252
diff
changeset
|
45 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.) |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
46 * - .MID (MIDI music converted to Waveform data, internal.) |
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
47 * - .MOD (MOD files, via MikMod and ModPlug.) |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
48 * - .OGG (Ogg files, via Ogg Vorbis libraries.) |
453
b9856ba6fb4e
Updated comments on supported files to include Speex.
Ryan C. Gordon <icculus@icculus.org>
parents:
427
diff
changeset
|
49 * - .SPX (Speex files, via libspeex.) |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
50 * - .SHN (Shorten files, internal.) |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
51 * - .RAW (Raw sound data in any format, internal.) |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
52 * - .AU (Sun's Audio format, internal.) |
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
53 * - .AIFF (Audio Interchange format, internal.) |
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
54 * - .FLAC (Lossless audio compression, via libFLAC.) |
0 | 55 * |
56 * (...and more to come...) | |
57 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
58 * Please see the file COPYING in the source's root directory. |
0 | 59 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
60 * \author Ryan C. Gordon (icculus@clutteredmind.org) |
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) |
386
8c8ecd1008c9
Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents:
357
diff
changeset
|
82 #else |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
83 # define SNDDECLSPEC |
130
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
84 #endif |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
85 |
427
ba94ffe34a47
Upped version to 1.0.0.
Ryan C. Gordon <icculus@icculus.org>
parents:
417
diff
changeset
|
86 #define SOUND_VER_MAJOR 1 |
ba94ffe34a47
Upped version to 1.0.0.
Ryan C. Gordon <icculus@icculus.org>
parents:
417
diff
changeset
|
87 #define SOUND_VER_MINOR 0 |
463
6e50a61059b8
Upped version to 1.0.1.
Ryan C. Gordon <icculus@icculus.org>
parents:
453
diff
changeset
|
88 #define SOUND_VER_PATCH 1 |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
89 #endif |
29 | 90 |
91 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
92 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
93 * \enum Sound_SampleFlags |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
94 * \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
|
95 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
96 * To use: |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
97 * \code |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
98 * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); } |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
99 * \endcode |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
100 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
101 * \sa Sound_SampleNew |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
102 * \sa Sound_SampleNewFromFile |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
103 * \sa Sound_SampleDecode |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
104 * \sa Sound_SampleDecodeAll |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
105 * \sa Sound_SampleSeek |
0 | 106 */ |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
107 typedef enum |
0 | 108 { |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
109 SOUND_SAMPLEFLAG_NONE = 0, /**< No special attributes. */ |
0 | 110 |
111 /* these are set at sample creation time... */ | |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
112 SOUND_SAMPLEFLAG_CANSEEK = 1, /**< Sample can seek to arbitrary points. */ |
0 | 113 |
114 /* these are set during decoding... */ | |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
115 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
|
116 SOUND_SAMPLEFLAG_ERROR = 1 << 30, /**< Unrecoverable error. */ |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
117 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /**< Function would block, or temp error. */ |
0 | 118 } Sound_SampleFlags; |
119 | |
120 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
121 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
122 * \struct Sound_AudioInfo |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
123 * \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
|
124 * |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
125 * 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
|
126 * (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
|
127 * 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
|
128 * sound code right now. |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
129 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
130 * \sa Sound_SampleNew |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
131 * \sa Sound_SampleNewFromFile |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
132 */ |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
133 typedef struct |
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 Uint16 format; /**< Equivalent of SDL_AudioSpec.format. */ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
136 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
|
137 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
|
138 } Sound_AudioInfo; |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
139 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
140 |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
141 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
142 * \struct Sound_DecoderInfo |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
143 * \brief Information about available soudn decoders. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
144 * |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
145 * 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
|
146 * 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
|
147 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
148 * 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
|
149 * should read it like this: |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
150 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
151 * \code |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
152 * const char **ext; |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
153 * for (ext = info->extensions; *ext != NULL; ext++) { |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
154 * printf(" File extension \"%s\"\n", *ext); |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
155 * } |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
156 * \endcode |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
157 * |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
158 * \sa Sound_AvailableDecoders |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
159 */ |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
160 typedef struct |
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 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
|
163 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
|
164 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
|
165 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
|
166 } Sound_DecoderInfo; |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
167 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
168 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
169 |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
170 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
171 * \struct Sound_Sample |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
172 * \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
|
173 * |
0 | 174 * The Sound_Sample structure is the heart of SDL_sound. This holds |
175 * information about a source of sound data as it is being decoded. | |
176 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to | |
177 * change them. | |
178 */ | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
179 typedef struct |
0 | 180 { |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
181 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
|
182 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
|
183 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
|
184 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
|
185 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
|
186 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
|
187 Sound_SampleFlags flags; /**< Flags relating to this sample. */ |
474
c66080364dff
Most decoders now report total sample play time, now. Technically, this
Ryan C. Gordon <icculus@icculus.org>
parents:
463
diff
changeset
|
188 Sint32 total_time; /**< Total length of song or track */ |
0 | 189 } Sound_Sample; |
190 | |
191 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
192 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
193 * \struct Sound_Version |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
194 * \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
|
195 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
196 * 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
|
197 * (increments with massive changes, additions, and enhancements), |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
198 * 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
|
199 * 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
|
200 * revision). |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
201 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
202 * \sa SOUND_VERSION |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
203 * \sa Sound_GetLinkedVersion |
0 | 204 */ |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
205 typedef struct |
0 | 206 { |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
207 int major; /**< major revision */ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
208 int minor; /**< minor revision */ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
209 int patch; /**< patchlevel */ |
0 | 210 } Sound_Version; |
211 | |
212 | |
213 /* functions and macros... */ | |
214 | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
215 /** |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
216 * \def SOUND_VERSION(x) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
217 * \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
|
218 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
219 * 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
|
220 * 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
|
221 * 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
|
222 * 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
|
223 * 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
|
224 * is not a macro. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
225 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
226 * \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
|
227 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
228 * \sa Sound_Version |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
229 * \sa Sound_GetLinkedVersion |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
230 */ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
231 #define SOUND_VERSION(x) \ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
232 { \ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
233 (x)->major = SOUND_VER_MAJOR; \ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
234 (x)->minor = SOUND_VER_MINOR; \ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
235 (x)->patch = SOUND_VER_PATCH; \ |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
236 } |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
237 |
0 | 238 |
239 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
240 * \fn void Sound_GetLinkedVersion(Sound_Version *ver) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
241 * \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
|
242 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
243 * 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
|
244 * possible that it will be different than the version you compiled against. |
0 | 245 * |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
246 * This is a real function; the macro SOUND_VERSION tells you what version |
0 | 247 * of SDL_sound you compiled against: |
248 * | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
249 * \code |
0 | 250 * Sound_Version compiled; |
251 * Sound_Version linked; | |
252 * | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
253 * SOUND_VERSION(&compiled); |
0 | 254 * Sound_GetLinkedVersion(&linked); |
255 * printf("We compiled against SDL_sound version %d.%d.%d ...\n", | |
256 * compiled.major, compiled.minor, compiled.patch); | |
257 * printf("But we linked against SDL_sound version %d.%d.%d.\n", | |
258 * linked.major, linked.minor, linked.patch); | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
259 * \endcode |
0 | 260 * |
261 * 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
|
262 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
263 * \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
|
264 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
265 * \sa Sound_Version |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
266 * \sa SOUND_VERSION |
0 | 267 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
268 SNDDECLSPEC void SDLCALL Sound_GetLinkedVersion(Sound_Version *ver); |
0 | 269 |
270 | |
271 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
272 * \fn Sound_Init(void) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
273 * \brief Initialize SDL_sound. |
0 | 274 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
275 * 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
|
276 * 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
|
277 * 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
|
278 * 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
|
279 * itself. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
280 * |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
281 * \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
|
282 * error can be gleaned from Sound_GetError(). |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
283 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
284 * \sa Sound_Quit |
0 | 285 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
286 SNDDECLSPEC int SDLCALL Sound_Init(void); |
0 | 287 |
288 | |
289 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
290 * \fn Sound_Quit(void) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
291 * \brief Shutdown SDL_sound. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
292 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
293 * 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
|
294 * any resources in use by SDL_sound. |
0 | 295 * |
296 * All Sound_Sample pointers you had prior to this call are INVALIDATED. | |
297 * | |
298 * 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
|
299 * restart the subsystem. All default API states are restored at this |
0 | 300 * point. |
301 * | |
302 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit() | |
303 * for you! | |
304 * | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
305 * \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
|
306 * 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
|
307 * 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
|
308 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
309 * \sa Sound_Init |
0 | 310 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
311 SNDDECLSPEC int SDLCALL Sound_Quit(void); |
0 | 312 |
313 | |
314 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
315 * \fn const Sound_DecoderInfo **Sound_AvailableDecoders(void) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
316 * \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
|
317 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
318 * This is for informational purposes only. Note that the extension listed is |
11 | 319 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio |
0 | 320 * file with an extension of "XYZ", if you like. The file extensions are |
321 * informational, and only required as a hint to choosing the correct | |
322 * decoder, since the sound data may not be coming from a file at all, thanks | |
323 * to the abstraction that an SDL_RWops provides. | |
324 * | |
325 * The returned value is an array of pointers to Sound_DecoderInfo structures, | |
326 * with a NULL entry to signify the end of the list: | |
327 * | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
328 * \code |
0 | 329 * Sound_DecoderInfo **i; |
330 * | |
331 * for (i = Sound_AvailableDecoders(); *i != NULL; i++) | |
332 * { | |
333 * printf("Supported sound format: [%s], which is [%s].\n", | |
334 * i->extension, i->description); | |
335 * // ...and other fields... | |
336 * } | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
337 * \endcode |
0 | 338 * |
339 * The return values are pointers to static internal memory, and should | |
340 * be considered READ ONLY, and never freed. | |
341 * | |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
342 * \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
|
343 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
344 * \sa Sound_DecoderInfo |
0 | 345 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
346 SNDDECLSPEC const Sound_DecoderInfo ** SDLCALL Sound_AvailableDecoders(void); |
0 | 347 |
348 | |
349 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
350 * \fn const char *Sound_GetError(void) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
351 * \brief Get the last SDL_sound error message as a null-terminated string. |
0 | 352 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
353 * 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
|
354 * 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
|
355 * 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
|
356 * 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
|
357 * 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
|
358 * 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
|
359 * |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
360 * \return READ ONLY string of last error message. |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
361 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
362 * \sa Sound_ClearError |
0 | 363 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
364 SNDDECLSPEC const char * SDLCALL Sound_GetError(void); |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
365 |
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 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
368 * \fn void Sound_ClearError(void) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
369 * \brief Clear the current error message. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
370 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
371 * 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
|
372 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
373 * \sa Sound_GetError |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
374 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
375 SNDDECLSPEC void SDLCALL Sound_ClearError(void); |
0 | 376 |
377 | |
378 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
379 * \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
|
380 * \brief Start decoding a new sound sample. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
381 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
382 * 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
|
383 * 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
|
384 * 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
|
385 * 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
|
386 * 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
|
387 * 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
|
388 * 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
|
389 * 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
|
390 * 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
|
391 * the stream. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
392 * |
0 | 393 * 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
|
394 * 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
|
395 * |
0 | 396 * Optionally, a desired audio format can be specified. If the incoming data |
397 * is in a different format, SDL_sound will convert it to the desired format | |
398 * on the fly. Note that this can be an expensive operation, so it may be | |
399 * wise to convert data before you need to play it back, if possible, or | |
400 * make sure your data is initially in the format that you need it in. | |
401 * If you don't want to convert the data, you can specify NULL for a desired | |
402 * format. The incoming format of the data, preconversion, can be found | |
403 * in the Sound_Sample structure. | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
404 * |
0 | 405 * 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
|
406 * 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
|
407 * 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
|
408 * by the other decoders. |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
409 * |
0 | 410 * Finally, specify an initial buffer size; this is the number of bytes that |
411 * will be allocated to store each read from the sound buffer. The more you | |
412 * can safely allocate, the more decoding can be done in one block, but the | |
413 * more resources you have to use up, and the longer each decoding call will | |
414 * take. Note that different data formats require more or less space to | |
415 * 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
|
416 * |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
417 * 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
|
418 * 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
|
419 * 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
|
420 * 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
|
421 * 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
|
422 * MUCH larger buffer). |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
423 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
424 * 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
|
425 * via Sound_FreeSample(). |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
426 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
427 * 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
|
428 * 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
|
429 * 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
|
430 * SDL_RWops for you. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
431 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
432 * \param rw SDL_RWops with sound data. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
433 * \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
|
434 * Can usually be NULL. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
435 * \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
|
436 * if you don't need conversion. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
437 * \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
|
438 * \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
|
439 * 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
|
440 * Sound_GetError() to see what went wrong. |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
441 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
442 * \sa Sound_NewSampleFromFile |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
443 * \sa Sound_SetBufferSize |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
444 * \sa Sound_Decode |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
445 * \sa Sound_DecodeAll |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
446 * \sa Sound_Seek |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
447 * \sa Sound_Rewind |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
448 * \sa Sound_FreeSample |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
449 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
450 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
|
451 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
|
452 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
|
453 Uint32 bufferSize); |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
454 |
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 * \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
|
457 * \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
|
458 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
459 * 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
|
460 * 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
|
461 * 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
|
462 * "/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
|
463 * 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
|
464 * (filename). |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
465 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
466 * \param filename file containing sound data. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
467 * \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
|
468 * if you don't need conversion. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
469 * \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
|
470 * \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
|
471 * 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
|
472 * Sound_GetError() to see what went wrong. |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
473 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
474 * \sa Sound_NewSample |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
475 * \sa Sound_SetBufferSize |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
476 * \sa Sound_Decode |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
477 * \sa Sound_DecodeAll |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
478 * \sa Sound_Seek |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
479 * \sa Sound_Rewind |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
480 * \sa Sound_FreeSample |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
481 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
482 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
|
483 Sound_AudioInfo *desired, |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
484 Uint32 bufferSize); |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
485 |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
486 /** |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
487 * \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
|
488 * \brief Dispose of a Sound_Sample. |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
489 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
490 * 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
|
491 * 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
|
492 * 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
|
493 * 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
|
494 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
495 * \param sample The Sound_Sample to delete. |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
496 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
497 * \sa Sound_NewSample |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
498 * \sa Sound_NewSampleFromFile |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
499 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
500 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
|
501 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
502 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
503 /** |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
504 * \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
|
505 * \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
|
506 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
507 * 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
|
508 * 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
|
509 * 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
|
510 * 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
|
511 * 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
|
512 * 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
|
513 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
514 * 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
|
515 * 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
|
516 * 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
|
517 * 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
|
518 * 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
|
519 * MUCH larger buffer). |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
520 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
521 * \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
|
522 * \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
|
523 * \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
|
524 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
525 * \sa Sound_Decode |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
526 * \sa Sound_DecodeAll |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
527 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
528 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
|
529 Uint32 new_size); |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
530 |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
531 |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
532 /** |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
533 * \fn Uint32 Sound_Decode(Sound_Sample *sample) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
534 * \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
|
535 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
536 * 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
|
537 * desired format, and return the number of decoded bytes. |
0 | 538 * 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
|
539 * sample->flags to determine if this was an end-of-stream or error condition. |
0 | 540 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
541 * \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
|
542 * \return number of bytes decoded into sample->buffer. If it is less than |
0 | 543 * sample->buffer_size, then you should check sample->flags to see |
544 * 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
|
545 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
546 * \sa Sound_DecodeAll |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
547 * \sa Sound_SetBufferSize |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
548 * \sa Sound_Seek |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
549 * \sa Sound_Rewind |
0 | 550 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
551 SNDDECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample); |
0 | 552 |
553 | |
554 /** | |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
555 * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
556 * \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
|
557 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
558 * This will dynamically allocate memory for the ENTIRE remaining sample. |
0 | 559 * sample->buffer_size and sample->buffer will be updated to reflect the |
560 * new buffer. Please refer to sample->flags to determine if the decoding | |
561 * finished due to an End-of-stream or error condition. | |
562 * | |
563 * Be aware that sound data can take a large amount of memory, and that | |
564 * this function may block for quite awhile while processing. Also note | |
565 * that a streaming source (for example, from a SDL_RWops that is getting | |
566 * fed from an Internet radio feed that doesn't end) may fill all available | |
567 * memory before giving up...be sure to use this on finite sound sources | |
568 * only! | |
569 * | |
170
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
570 * 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
|
571 * 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
|
572 * 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
|
573 * 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
|
574 * 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
|
575 * 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
|
576 * 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
|
577 * the sample isn't specific and small. |
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
578 * |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
579 * \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
|
580 * \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
|
581 * 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
|
582 * (EOF, error, read again). |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
583 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
584 * \sa Sound_Decode |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
585 * \sa Sound_SetBufferSize |
0 | 586 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
587 SNDDECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample); |
0 | 588 |
223
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
589 |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
590 /** |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
591 * \fn int Sound_Rewind(Sound_Sample *sample) |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
592 * \brief Rewind a sample to the start. |
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 * 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
|
595 * 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
|
596 * 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
|
597 * in the stream. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
598 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
599 * 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
|
600 * 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
|
601 * 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
|
602 * SDL_RWops. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
603 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
604 * 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
|
605 * 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
|
606 * 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
|
607 * 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
|
608 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
609 * 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
|
610 * 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
|
611 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
612 * 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
|
613 * ERROR flag is set on error. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
614 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
615 * \param sample The Sound_Sample to rewind. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
616 * \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
|
617 * error can be gleaned from Sound_GetError(). |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
618 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
619 * \sa Sound_Seek |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
620 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
621 SNDDECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample); |
223
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
622 |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
623 |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
624 /** |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
625 * \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
|
626 * \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
|
627 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
628 * 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
|
629 * 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
|
630 * specified. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
631 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
632 * 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
|
633 * sample. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
634 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
635 * 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
|
636 * 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
|
637 * 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
|
638 * 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
|
639 * 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
|
640 * 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
|
641 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
642 * 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
|
643 * 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
|
644 * 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
|
645 * flag is set. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
646 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
647 * 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
|
648 * 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
|
649 * 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
|
650 * with decoder-specific code. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
651 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
652 * 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
|
653 * 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
|
654 * 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
|
655 * decoding loop can pick up. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
656 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
657 * 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
|
658 * |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
659 * \param sample The Sound_Sample to seek. |
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
660 * \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
|
661 * \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
|
662 * error can be gleaned from Sound_GetError(). |
357
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
663 * |
b3ac77d08e79
More documentation cleanups and enhancements.
Ryan C. Gordon <icculus@icculus.org>
parents:
353
diff
changeset
|
664 * \sa Sound_Rewind |
353
2740fad98dfe
Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents:
305
diff
changeset
|
665 */ |
417
55c6695b6038
Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents:
389
diff
changeset
|
666 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
|
667 |
0 | 668 #ifdef __cplusplus |
669 } | |
670 #endif | |
671 | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
672 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */ |
0 | 673 |
674 /* end of SDL_sound.h ... */ | |
675 |