annotate SDL_sound.h @ 0:1078b3528e6f

Initial revision
author Ryan C. Gordon <icculus@icculus.org>
date Fri, 14 Sep 2001 23:41:11 +0000
parents
children 508aac690b19
rev   line source
0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
1 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
2 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
3 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
4 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
5 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
6 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
7 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
8 * 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
9 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
10 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
13 * Lesser General Public License for more details.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
14 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
15 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
18 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
19
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 * 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
22 * 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
23 * 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
24 * 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
25 * 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
26 * decoding and converting, so you can just pass it to your SDL audio
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
27 * callback (or whatever). Since it gets data from a SDL_RWops, you can get
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
28 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
29 * network connection, etc.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
30 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
31 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
32 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
33 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
34 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
35 * Support is in place or planned for the following sound formats:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
36 * - .WAV (Microsoft WAVfile RIFF data, internal.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
37 * - .VOC (Creative Labs' Voice format, internal.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
38 * - .MP3 (MPEG-1 layer 3 support, via the SMPEG library.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
39 * - .MID (MIDI music converted to Waveform data, via Timidity.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
40 * - .MOD (MOD files, via MikMod.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
41 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
42 * - .RAWDATA (Raw sound data in any format, internal.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
43 * - .CDA (CD audio read into a sound buffer, internal.)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
44 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
45 * (...and more to come...)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
46 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
47 * Please see the file LICENSE in the source's root directory.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
48 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
49 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
50 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
51
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
52 #ifndef _INCLUDE_SDL_VOICE_H_
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
53 #define _INCLUDE_SDL_VOICE_H_
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
54
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
55 #include "SDL.h"
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
56
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
57 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
58 extern "C" {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
59 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
60
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
61 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
62 * These are flags that are used in a Sound_Sample (below) to show various
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
63 * states.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
64 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
65 * To use: "if (sample->flags & VOICE_SAMPLEFLAGS_ERROR) { dosomething(); }"
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 typedef enum __VOICE_SAMPLEFLAGS__
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
68 {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
69 VOICE_SAMPLEFLAG_NONE = 0, /* Null flag. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
70
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
71 /* these are set at sample creation time... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
72 VOICE_SAMPLEFLAG_NEEDSEEK = 1, /* SDL_RWops must be able to seek. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
73 VOICE_SAMPLEFLAG_STREAMING = 1 << 1, /* source is streaming (no EOF). */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
74
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
75 /* these are set during decoding... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
76 VOICE_SAMPLEFLAG_EOF = 1 << 29, /* end of input stream. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
77 VOICE_SAMPLEFLAG_ERROR = 1 << 30, /* unrecoverable error. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
78 VOICE_SAMPLEFLAG_AGAIN = 1 << 31 /* couldn't read without blocking. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
79 } Sound_SampleFlags;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
80
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
81
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
82 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
83 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
84 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
85 * 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
86 * change them.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
87 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
88 typedef struct __VOICE_SAMPLE__
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
89 {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
90 void *opaque; /* Internal use only. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
91 Sound_DecoderInfo *decoder; /* Decoder used for this sample. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
92 SDL_AudioSpec desired; /* Desired audio format for conversion. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
93 SDL_AudioSpec actual; /* Actual audio format of sample. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
94 void *buffer; /* Decoded sound data lands in here. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
95 Uint32 buffer_size; /* Current size of (buffer), in bytes. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
96 Sound_SampleFlags flags; /* Flags relating to this sample. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
97 } Sound_Sample;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
98
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
99
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
100 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
101 * Each decoder sets up one of these structs, which can be retrieved via
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
102 * the Sound_AvailableDecoders() function.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
103 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
104 typedef struct __PHYSFS_ARCHIVEINFO__
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
105 {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
106 const char *extension; /* Case sensitive standard file extension. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
107 const char *description; /* Human readable description of decoder. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
108 const char *author; /* "Name Of Author (email@emailhost.dom)" */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
109 const char *url; /* URL specific to this decoder. */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
110 } PHYSFS_ArchiveInfo;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
111
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
112
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
113 /*
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
114 * Just what it says: a x.y.z style version number...
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
115 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
116 typedef struct __VOICE_VERSION__
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
117 {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
118 int major;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
119 int minor;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
120 int patch;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
121 } Sound_Version;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
122
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
123
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
124
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
125 /* functions and macros... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
126
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
127 #define VOICE_VER_MAJOR 0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
128 #define VOICE_VER_MINOR 0
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
129 #define VOICE_VER_PATCH 1
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
130
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
131 #define VOICE_VERSION(x) { \
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
132 (x)->major = VOICE_VER_MAJOR; \
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
133 (x)->minor = VOICE_VER_MINOR; \
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
134 (x)->patch = VOICE_VER_PATCH; \
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
135 }
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
136
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
137 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
138 * Get the version of SDL_sound that is linked against your program. If you
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
139 * are using a shared library (DLL) version of SDL_sound, then it is possible
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
140 * that it will be different than the version you compiled against.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
141 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
142 * This is a real function; the macro VOICE_VERSION tells you what version
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
143 * of SDL_sound you compiled against:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
144 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
145 * Sound_Version compiled;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
146 * Sound_Version linked;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
147 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
148 * VOICE_VERSION(&compiled);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
149 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
150 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
151 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
152 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
153 * linked.major, linked.minor, linked.patch);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
154 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
155 * This function may be called safely at any time, even before Sound_Init().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
156 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
157 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
158
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
159
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
160 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
161 * Initialize SDL_sound. This must be called before any other SDL_sound
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
162 * function (except perhaps Sound_GetLinkedVersion()). You should call
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
163 * SDL_Init() before calling this. Sound_Init() will attempt to call
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
164 * SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
165 * may not configure SDL to your liking by itself.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
166 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
167 * @return nonzero on success, zero on error. Specifics of the error can be
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
168 * gleaned from Sound_GetLastError().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
169 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
170 extern DECLSPEC int Sound_Init(void);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
171
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
172
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
173 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
174 * Shutdown SDL_sound. This closes any SDL_RWops that were being used as
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
175 * sound sources, and frees any resources in use by SDL_sound.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
176 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
177 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
178 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
179 * Once successfully deinitialized, Sound_Init() can be called again to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
180 * restart the subsystem. All defaults API states are restored at this
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
181 * point.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
182 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
183 * 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
184 * for you!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
185 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
186 * @return nonzero on success, zero on error. Specifics of the error can be
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
187 * gleaned from Sound_GetLastError(). If failure, state of SDL_sound
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
188 * is undefined, and probably badly screwed up.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
189 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
190 extern DECLSPEC int Sound_Quit(void);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
191
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
192
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
193 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
194 * Get a list of sound formats supported by this implementation of SDL_sound.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
195 * This is for informational purposes only. Note that the extension listed is
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
196 * merely convention: if we list "MP3", you can open an MPEG Audio layer 3
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
197 * 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
198 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
199 * 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
200 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
201 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
202 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
203 * with a NULL entry to signify the end of the list:
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
204 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
205 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
206 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
207 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
208 * {
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
209 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
210 * i->extension, i->description);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
211 * // ...and other fields...
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
212 * }
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
213 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
214 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
215 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
216 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
217 * @return READ ONLY Null-terminated array of READ ONLY structures.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
218 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
219 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
220
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
221
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
222 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
223 * Get the last SDL_sound error message as a null-terminated string.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
224 * This will be NULL if there's been no error since the last call to this
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
225 * function. The pointer returned by this call points to an internal buffer.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
226 * Each thread has a unique error state associated with it, but each time
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
227 * a new error message is set, it will overwrite the previous one associated
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
228 * with that thread. It is safe to call this function at anytime, even
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
229 * before Sound_Init().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
230 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
231 * @return READ ONLY string of last error message.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
232 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
233 extern DECLSPEC const char *Sound_GetLastError(void);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
234
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
235
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
236 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
237 * Start decoding a new sound sample. The data is read via an SDL_RWops
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
238 * structure (see SDL_rwops.h in the SDL include directory), so it may be
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
239 * coming from memory, disk, network stream, etc. The (ext) parameter is
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
240 * merely a hint to determining the correct decoder; if you specify, for
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
241 * example, "mp3" for an extension, and one of the decoders lists that
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
242 * (case sensitive) as a handled extension, then that decoder is given
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
243 * first shot at trying to claim the data for decoding. If none of the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
244 * extensions match (or the extension is NULL), then every decoder examines
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
245 * the data to determine if it can handle it, until one accepts it.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
246 * If no decoders can handle the data, a NULL value is returned, and a human
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
247 * readable error message can be fetched from Sound_GetLastError().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
248 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
249 * 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
250 * 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
251 * 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
252 * 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
253 * 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
254 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
255 * in the Sound_Sample structure.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
256 * Note that the raw sound data "decoder" needs you to specify both the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
257 * extension "RAWDATA" and a "desired" format, or it will refuse to handle
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
258 * the data.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
259 * 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
260 * 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
261 * 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
262 * 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
263 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
264 * store. This buffer can be resized via Sound_SetBufferSize() ...
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
265 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
266 * When you are done with this Sound_Sample pointer, you can dispose of it
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
267 * via Sound_FreeSample().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
268 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
269 * @param rw SDL_RWops with sound data.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
270 * @param ext File extension normally associated with a data format.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
271 * Can usually be NULL.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
272 * @param desired Format to convert sound data into. Can usually be NULL,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
273 * if you don't need conversion.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
274 * @return Sound_Sample pointer, which is used as a handle to several other
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
275 * SDL_sound APIs. NULL on error. If error, use
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
276 * Sound_GetLastError() to see what went wrong.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
277 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
278 extern DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
279 SDL_AudioInfo *desired,
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
280 Uint32 bufferSize);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
281
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
282 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
283 * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample().
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
284 * This will also close/dispose of the SDL_RWops that was used at creation
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
285 * time, so there's no need to keep a reference to that around.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
286 * The Sound_Sample pointer is invalid after this call, and will almost
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
287 * certainly result in a crash if you attempt to keep using it.
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 * @param sample The Sound_Sample to delete.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
290 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
291 extern DECLSPEC void Sound_FreeSample(Sound_Sample *sample);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
292
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
293
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
294 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
295 * Decode more of the sound data in a Sound_Sample. It will decode at most
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
296 * sample->buffer_size bytes into sample->buffer in the desired format, and
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
297 * return the number of decoded bytes.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
298 * If sample->buffer_size bytes could not be decoded, then please refer to
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
299 * sample->flags to determine if this was an End-of-stream or error condition.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
300 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
301 * @param sample Do more decoding to this Sound_Sample.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
302 * @return number of bytes decoded into sample->buffer. If it is less than
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
303 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
304 * what the current state of the sample is (EOF, error, read again).
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
305 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
306 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
307
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
308
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
309 /**
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
310 * Decode the remainder of the sound data in a Sound_Sample. This will
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
311 * dynamically allocate memory for the ENTIRE remaining sample.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
312 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
313 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
314 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
315 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
316 * 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
317 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
318 * 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
319 * 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
320 * 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
321 * only!
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
322 *
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
323 * @param sample Do all decoding for this Sound_Sample.
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
324 * @return number of bytes decoded into sample->buffer. If it is less than
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
325 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
326 * what the current state of the sample is (EOF, error, read again).
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
327 */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
328 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
329
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
330 #ifdef __cplusplus
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
331 }
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
332 #endif
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
333
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
334 #endif /* !defined _INCLUDE_SDL_VOICE_H_ */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
335
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
336 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
337