|
4
|
1 /*
|
|
|
2 * SDL_sound -- An abstract sound format decoding API.
|
|
|
3 * Copyright (C) 2001 Ryan C. Gordon.
|
|
|
4 *
|
|
|
5 * This library is free software; you can redistribute it and/or
|
|
|
6 * modify it under the terms of the GNU Lesser General Public
|
|
|
7 * License as published by the Free Software Foundation; either
|
|
|
8 * version 2.1 of the License, or (at your option) any later version.
|
|
|
9 *
|
|
|
10 * This library is distributed in the hope that it will be useful,
|
|
|
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
13 * Lesser General Public License for more details.
|
|
|
14 *
|
|
|
15 * You should have received a copy of the GNU Lesser General Public
|
|
|
16 * License along with this library; if not, write to the Free Software
|
|
|
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
18 */
|
|
|
19
|
|
|
20 /*
|
|
|
21 * Internal function/structure declaration. Do NOT include in your
|
|
|
22 * application.
|
|
|
23 *
|
|
|
24 * Please see the file LICENSE in the source's root directory.
|
|
|
25 *
|
|
|
26 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
|
|
|
27 */
|
|
|
28
|
|
|
29 #ifndef _INCLUDE_SDL_SOUND_INTERNAL_H_
|
|
|
30 #define _INCLUDE_SDL_SOUND_INTERNAL_H_
|
|
|
31
|
|
|
32 #ifndef __SDL_SOUND_INTERNAL__
|
|
|
33 #error Do not include this header from your applications.
|
|
|
34 #endif
|
|
|
35
|
|
|
36 #include "SDL.h"
|
|
|
37
|
|
|
38 typedef struct __SOUND_DECODERFUNCTIONS__
|
|
|
39 {
|
|
|
40 /* This is a block of info about your decoder. See SDL_sound.h. */
|
|
|
41 const Sound_DecoderInfo info;
|
|
|
42
|
|
|
43 /*
|
|
|
44 * Returns non-zero if (sample) has a valid fileformat that this
|
|
|
45 * driver can handle. Zero if this driver can NOT handle the data.
|
|
|
46 *
|
|
|
47 * Extension, which may be NULL, is just a hint as to the form of
|
|
|
48 * data that is being passed in. Most decoders should determine if
|
|
|
49 * they can handle the data by the data itself, but others, like
|
|
|
50 * the raw data handler, need this hint to know if they should
|
|
|
51 * accept the data in the first place.
|
|
|
52 *
|
|
|
53 * (sample)'s (opaque) field should be cast to a Sound_SampleInternal
|
|
|
54 * pointer:
|
|
|
55 *
|
|
|
56 * Sound_SampleInternal *internal;
|
|
|
57 * internal = (Sound_SampleInternal *) sample->opaque;
|
|
|
58 *
|
|
|
59 * Certain fields of sample will be filled in for the decoder before
|
|
|
60 * this call, and others should be filled in by the decoder. Some
|
|
|
61 * fields are offlimits, and should NOT be modified. The list:
|
|
|
62 *
|
|
|
63 * in Sound_SampleInternal section:
|
|
|
64 * Sound_Sample *next; (offlimits)
|
|
|
65 * Sound_Sample *prev; (offlimits)
|
|
|
66 * SDL_RWops *rw; (can use, but do NOT close it)
|
|
|
67 * const Sound_DecoderFunctions *funcs; (that's this structure)
|
|
|
68 * SDL_AudioCVT sdlcvt; (offlimits)
|
|
|
69 * void *buffer; (offlimits until read() method)
|
|
|
70 * Uint32 buffer_size; (offlimits until read() method)
|
|
|
71 *
|
|
|
72 * in rest of Sound_Sample:
|
|
|
73 * void *opaque; (this was internal section, above)
|
|
|
74 * const Sound_DecoderInfo *decoder; (read only)
|
|
|
75 * Sound_AudioInfo desired; (read only, usually not needed here)
|
|
|
76 * Sound_AudioInfo actual; (please fill this in)
|
|
|
77 * void *buffer; (offlimits)
|
|
|
78 * Uint32 buffer_size; (offlimits)
|
|
|
79 * Sound_SampleFlags flags; (set appropriately)
|
|
|
80 */
|
|
|
81 int (*open)(Sound_Sample *sample, const char *ext);
|
|
|
82
|
|
|
83 /*
|
|
|
84 * Clean up. SDL_sound is done with this sample, so the decoder should
|
|
|
85 * clean up any resources it allocated. Anything that wasn't
|
|
|
86 * explicitly allocated by the decoder should be LEFT ALONE, since
|
|
|
87 * the higher-level SDL_sound layer will clean up its own mess.
|
|
|
88 */
|
|
|
89 void (*close)(Sound_Sample *sample);
|
|
|
90
|
|
|
91 /*
|
|
|
92 * Get more data from (sample). The decoder should get a pointer to
|
|
|
93 * the internal structure...
|
|
|
94 *
|
|
|
95 * Sound_SampleInternal *internal;
|
|
|
96 * internal = (Sound_SampleInternal *) sample->opaque;
|
|
|
97 *
|
|
|
98 * ...and then start decoding. Fill in up to internal->buffer_size
|
|
|
99 * bytes of decoded sound in the space pointed to by
|
|
|
100 * internal->buffer. The encoded data is read in from internal->rw.
|
|
|
101 * Data should be decoded in the format specified during the
|
|
|
102 * decoder's open() method in the sample->actual field. The
|
|
|
103 * conversion to the desired format is done at a higher level.
|
|
|
104 *
|
|
|
105 * The return value is the number of bytes decoded into
|
|
|
106 * internal->buffer, which can be no more than internal->buffer_size,
|
|
|
107 * but can be less. If it is less, you should set a state flag:
|
|
|
108 *
|
|
|
109 * If there's just no more data (end of file, etc), then do:
|
|
|
110 * sample->flags |= SOUND_SAMPLEFLAG_EOF;
|
|
|
111 *
|
|
|
112 * If there's an unrecoverable error, then do:
|
|
|
113 * Sound_SetError(ERR_EXPLAIN_WHAT_WENT_WRONG);
|
|
|
114 * sample->flags |= SOUND_SAMPLEFLAG_ERROR;
|
|
|
115 *
|
|
|
116 * If there's more data, but you'd have to block for considerable
|
|
|
117 * amounts of time to get at it, or there's a recoverable error,
|
|
|
118 * then do:
|
|
|
119 * Sound_SetError(ERR_EXPLAIN_WHAT_WENT_WRONG);
|
|
|
120 * sample->flags |= SOUND_SAMPLEFLAG_EAGAIN;
|
|
|
121 *
|
|
|
122 * SDL_sound will not call your read() method for any samples with
|
|
|
123 * SOUND_SAMPLEFLAG_EOF or SOUND_SAMPLEFLAG_ERROR set. The
|
|
|
124 * SOUND_SAMPLEFLAG_EAGAIN flag is reset before each call to this
|
|
|
125 * method.
|
|
|
126 */
|
|
|
127 int (*read)(Sound_Sample *sample);
|
|
|
128 } Sound_DecoderFunctions;
|
|
|
129
|
|
|
130
|
|
|
131 typedef struct __SOUND_SAMPLEINTERNAL__
|
|
|
132 {
|
|
|
133 Sound_Sample *next;
|
|
|
134 Sound_Sample *prev;
|
|
|
135 SDL_RWops *rw;
|
|
|
136 const Sound_DecoderFunctions *funcs;
|
|
|
137 SDL_AudioCVT sdlcvt;
|
|
|
138 void *buffer;
|
|
|
139 Uint32 buffer_size;
|
|
|
140 } Sound_SampleInternal;
|
|
|
141
|
|
|
142
|
|
|
143
|
|
|
144 /* error messages... */
|
|
|
145 #define ERR_IS_INITIALIZED "Already initialized"
|
|
|
146 #define ERR_NOT_INITIALIZED "Not initialized"
|
|
|
147 #define ERR_INVALID_ARGUMENT "Invalid argument"
|
|
|
148 #define ERR_OUT_OF_MEMORY "Out of memory"
|
|
|
149 #define ERR_NOT_SUPPORTED "Operation not supported"
|
|
|
150 #define ERR_UNSUPPORTED_FORMAT "Sound format unsupported"
|
|
|
151 #define ERR_NOT_A_HANDLE "Not a file handle"
|
|
|
152 #define ERR_NO_SUCH_FILE "No such file"
|
|
|
153 #define ERR_PAST_EOF "Past end of file"
|
|
|
154 #define ERR_IO_ERROR "I/O error"
|
|
|
155 #define ERR_COMPRESSION "(De)compression error"
|
|
|
156 #define ERR_PREV_ERROR "Previous decoding already caused an error"
|
|
|
157 #define ERR_PREV_EOF "Previous decoding already triggered EOF"
|
|
|
158
|
|
|
159 /*
|
|
|
160 * Call this to set the message returned by Sound_GetError().
|
|
|
161 * Please only use the ERR_* constants above, or add new constants to the
|
|
|
162 * above group, but I want these all in one place.
|
|
|
163 *
|
|
|
164 * Calling this with a NULL argument is a safe no-op.
|
|
|
165 */
|
|
|
166 void Sound_SetError(const char *err);
|
|
|
167
|
|
|
168
|
|
|
169 /*
|
|
|
170 * Use this if you need a cross-platform stricmp().
|
|
|
171 */
|
|
|
172 int __Sound_strcasecmp(const char *x, const char *y);
|
|
|
173
|
|
|
174
|
|
|
175 /* These get used all over for lessening code clutter. */
|
|
|
176 #define BAIL_MACRO(e, r) { Sound_SetError(e); return r; }
|
|
|
177 #define BAIL_IF_MACRO(c, e, r) if (c) { Sound_SetError(e); return r; }
|
|
|
178
|
|
|
179
|
|
|
180
|
|
|
181
|
|
|
182 /*--------------------------------------------------------------------------*/
|
|
|
183 /*--------------------------------------------------------------------------*/
|
|
|
184 /*------------ ----------------*/
|
|
|
185 /*------------ You MUST implement the following functions ----------------*/
|
|
|
186 /*------------ if porting to a new platform. ----------------*/
|
|
|
187 /*------------ (see platform/unix.c for an example) ----------------*/
|
|
|
188 /*------------ ----------------*/
|
|
|
189 /*--------------------------------------------------------------------------*/
|
|
|
190 /*--------------------------------------------------------------------------*/
|
|
|
191
|
|
|
192
|
|
|
193 /* (None, right now.) */
|
|
|
194
|
|
|
195
|
|
|
196 #ifdef __cplusplus
|
|
|
197 extern "C" {
|
|
|
198 #endif
|
|
|
199
|
|
|
200 #endif /* defined _INCLUDE_SDL_SOUND_INTERNAL_H_ */
|
|
|
201
|
|
|
202 /* end of SDL_sound_internal.h ... */
|
|
|
203
|
