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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
3 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
4 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
5 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
6 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
7 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
8 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
9 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
10 * version 2.1 of the License, or (at your option) any later version.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
11 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
12 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
15 * Lesser General Public License for more details.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
17 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
18 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
20 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
21
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
22 /**
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
23 * \mainpage SDL_sound
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
24 *
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
25 * The latest version of SDL_sound can be found at:
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
26 * http://icculus.org/SDL_sound/
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
27 *
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
28 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
29 * into this library, and SDL_sound will take that data, in one of several
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
30 * popular formats, and decode it into raw waveform data in the format of
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
31 * your choice. This gives you a nice abstraction for getting sound into your
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
32 * game or application; just feed it to SDL_sound, and it will handle
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
33 * decoding and converting, so you can just pass it to your SDL audio
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
34 * callback (or whatever). Since it gets data from an SDL_RWops, you can get
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
35 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
36 * network connection, etc.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
37 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
38 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
39 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
40 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
41 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
42 * Support is in place or planned for the following sound formats:
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
43 * - .WAV (Microsoft WAVfile RIFF data, internal.)
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
44 * - .VOC (Creative Labs' Voice format, internal.)
305
c345a40a8a99 VERY preliminary work on Sound_Seek() API.
Ryan C. Gordon <icculus@icculus.org>
parents: 252
diff changeset
45 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
46 * - .MID (MIDI music converted to Waveform data, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
47 * - .MOD (MOD files, via MikMod and ModPlug.)
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
48 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
453
b9856ba6fb4e Updated comments on supported files to include Speex.
Ryan C. Gordon <icculus@icculus.org>
parents: 427
diff changeset
49 * - .SPX (Speex files, via libspeex.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
50 * - .SHN (Shorten files, internal.)
3
fd6cd0e04e6f First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
51 * - .RAW (Raw sound data in any format, internal.)
252
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
52 * - .AU (Sun's Audio format, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
53 * - .AIFF (Audio Interchange format, internal.)
c54eae85f5f1 Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents: 223
diff changeset
54 * - .FLAC (Lossless audio compression, via libFLAC.)
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
55 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
56 * (...and more to come...)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
57 *
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 170
diff changeset
58 * Please see the file COPYING in the source's root directory.
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
59 *
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
62 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
63
1
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
64 #ifndef _INCLUDE_SDL_SOUND_H_
508aac690b19 Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents: 0
diff changeset
65 #define _INCLUDE_SDL_SOUND_H_
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
66
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
67 #include "SDL.h"
19
734e5d75acec Now includes SDL_endian.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
68 #include "SDL_endian.h"
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
69
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
70 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
71 extern "C" {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
72 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
73
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
74 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
386
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
75
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
76 #ifndef SDLCALL /* may not be defined with older SDL releases. */
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
77 #define SDLCALL
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
78 #endif
8c8ecd1008c9 Changed DECLSPEC definition.
Ryan C. Gordon <icculus@icculus.org>
parents: 357
diff changeset
79
130
ac49f81e42d6 Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents: 44
diff changeset
80 #ifdef SDL_SOUND_DLL_EXPORTS
417
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think.
Ryan C. Gordon <icculus@icculus.org>
parents: 389
diff changeset
81 # define SNDDECLSPEC __declspec(dllexport)
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
0e27c909c952 Upped version to 0.1.1
Ryan C. Gordon <icculus@icculus.org>
parents: 19
diff changeset
90
0e27c909c952 Upped version to 0.1.1
Ryan C. Gordon <icculus@icculus.org>
parents: 19
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
106 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
107 typedef enum
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
108 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
109 SOUND_SAMPLEFLAG_NONE = 0, /**< No special attributes. */
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
110
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
113
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
118 } Sound_SampleFlags;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
119
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
174 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
175 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
176 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
177 * change them.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
178 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
179 typedef struct
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
180 {
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
181 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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
189 } Sound_Sample;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
190
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
204 */
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
205 typedef struct
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
210 } Sound_Version;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
211
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
212
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
213 /* functions and macros... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
238
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
247 * of SDL_sound you compiled against:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
248 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
249 * \code
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
250 * Sound_Version compiled;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
251 * Sound_Version linked;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
254 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
255 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
256 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
257 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
260 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
269
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
270
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
271 /**
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
287
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
288
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
289 /**
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
295 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
296 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
297 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
300 * point.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
301 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
302 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
303 * for you!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
312
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
313
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
314 /**
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
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
319 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
320 * file with an extension of "XYZ", if you like. The file extensions are
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
321 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
322 * decoder, since the sound data may not be coming from a file at all, thanks
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
323 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
324 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
325 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
326 * with a NULL entry to signify the end of the list:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
327 *
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
328 * \code
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
329 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
330 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
331 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
332 * {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
333 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
334 * i->extension, i->description);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
335 * // ...and other fields...
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
336 * }
353
2740fad98dfe Tweaked and enhanced for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 305
diff changeset
337 * \endcode
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
338 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
339 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
340 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
347
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
348
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
349 /**
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
376
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
377
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
378 /**
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
396 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
397 * is in a different format, SDL_sound will convert it to the desired format
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
398 * on the fly. Note that this can be an expensive operation, so it may be
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
399 * wise to convert data before you need to play it back, if possible, or
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
400 * make sure your data is initially in the format that you need it in.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
401 * If you don't want to convert the data, you can specify NULL for a desired
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
402 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
410 * Finally, specify an initial buffer size; this is the number of bytes that
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
411 * will be allocated to store each read from the sound buffer. The more you
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
412 * can safely allocate, the more decoding can be done in one block, but the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
413 * more resources you have to use up, and the longer each decoding call will
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
414 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
543 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
552
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
553
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
554 /**
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
559 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
560 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
561 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
562 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
563 * Be aware that sound data can take a large amount of memory, and that
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
564 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
565 * that a streaming source (for example, from a SDL_RWops that is getting
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
566 * fed from an Internet radio feed that doesn't end) may fill all available
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
567 * memory before giving up...be sure to use this on finite sound sources
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
568 * only!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
668 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
669 }
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
670 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
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
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
673
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
674 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
675