Mercurial > SDL_sound_CoreAudio

comparison SDL_sound_internal.h @ 4:341cea3e13c6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial add.
author Ryan C. Gordon <icculus@icculus.org>
date Mon, 17 Sep 2001 18:12:03 +0000
parents
children 2888101dcf98
comparison
equal deleted inserted replaced
3:fd6cd0e04e6f 4:341cea3e13c6
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