2 * ALURE OpenAL utility library
3 * Copyright (c) 2009 by Chris Robinson.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to
7 * deal in the Software without restriction, including without limitation the
8 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 * sell copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
24 /* Title: Streaming */
34 static bool SizeIsUS = false;
36 static alureStream *InitStream(alureStream *instream, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs)
38 std::auto_ptr<std::istream> fstream(instream->fstream);
39 std::auto_ptr<alureStream> stream(instream);
41 ALuint freq, blockAlign;
43 if(!stream->GetFormat(&format, &freq, &blockAlign))
45 SetError("Could not get stream format");
49 if(format == AL_NONE || format == -1)
51 SetError("No valid format");
56 SetError("Invalid block size");
61 SetError("Invalid sample rate");
67 ALuint framesPerBlock = DetectCompressionRate(format);
68 ALuint blockSize = DetectBlockAlignment(format);
69 if(framesPerBlock == 0 || blockSize == 0)
71 SetError("Unknown compression rate");
75 alureUInt64 len64 = chunkLength;
76 len64 = len64 * freq / 1000000 / framesPerBlock * blockSize;
77 if(len64 > 0x7FFFFFFF)
79 SetError("Chunk length too large");
85 chunkLength -= chunkLength%blockAlign;
88 SetError("Chunk length too small");
92 stream->dataChunk.resize(chunkLength);
96 alGenBuffers(numBufs, bufs);
97 if(alGetError() != AL_NO_ERROR)
99 SetError("Buffer creation failed");
105 for(filled = 0;filled < numBufs;filled++)
107 ALuint got = stream->GetData(&stream->dataChunk[0], stream->dataChunk.size());
108 got -= got%blockAlign;
111 alBufferData(bufs[filled], format, &stream->dataChunk[0], got, freq);
114 while(filled < numBufs)
116 alBufferData(bufs[filled], format, &stream->dataChunk[0], 0, freq);
119 if(alGetError() != AL_NO_ERROR)
121 alDeleteBuffers(numBufs, bufs);
124 SetError("Buffering error");
129 return stream.release();
135 /* Function: alureStreamSizeIsMicroSec
137 * Specifies if the chunk size value given to the alureCreateStream functions
138 * is in bytes (default) or microseconds. Specifying the size in microseconds
139 * can help manage the time needed in between needed updates (since the format
140 * and sample rate of the stream may not be known), while specifying the size
141 * in bytes can help control memory usage.
144 * Previously set value.
146 * *Version Added*: 1.1
149 * <alureCreateStreamFromFile>, <alureCreateStreamFromMemory>,
150 * <alureCreateStreamFromStaticMemory>, <alureCreateStreamFromCallback>
152 ALURE_API ALboolean ALURE_APIENTRY alureStreamSizeIsMicroSec(ALboolean useUS)
154 ALboolean old = (SizeIsUS ? AL_TRUE : AL_FALSE);
159 /* Function: alureCreateStreamFromFile
161 * Opens a file and sets it up for streaming. The given chunkLength is the
162 * number of bytes, or microseconds worth of bytes if
163 * <alureStreamSizeIsMicroSec> was last called with AL_TRUE, each buffer will
164 * fill with. ALURE will optionally generate the specified number of buffer
165 * objects, fill them with the beginning of the data, then place the new IDs
166 * into the provided storage, before returning. Requires an active context.
169 * An opaque handle used to control the opened stream, or NULL on error.
172 * <alureStreamSizeIsMicroSec>, <alureCreateStreamFromMemory>,
173 * <alureCreateStreamFromStaticMemory>, <alureCreateStreamFromCallback>
175 ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(const ALchar *fname, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs)
177 if(alGetError() != AL_NO_ERROR)
179 SetError("Existing OpenAL error");
185 SetError("Invalid chunk length");
191 SetError("Invalid buffer count");
195 alureStream *stream = create_stream(fname);
196 if(!stream) return NULL;
198 return InitStream(stream, chunkLength, numBufs, bufs);
201 /* Function: alureCreateStreamFromMemory
203 * Opens a file image from memory and sets it up for streaming, similar to
204 * <alureCreateStreamFromFile>. The given data buffer can be safely deleted
205 * after calling this function. Requires an active context.
208 * An opaque handle used to control the opened stream, or NULL on error.
211 * <alureStreamSizeIsMicroSec>, <alureCreateStreamFromFile>,
212 * <alureCreateStreamFromStaticMemory>, <alureCreateStreamFromCallback>
214 ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(const ALubyte *fdata, ALuint length, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs)
216 if(alGetError() != AL_NO_ERROR)
218 SetError("Existing OpenAL error");
224 SetError("Invalid chunk length");
230 SetError("Invalid buffer count");
236 SetError("Invalid data length");
240 ALubyte *streamData = new ALubyte[length];
241 memcpy(streamData, fdata, length);
244 memData.Data = streamData;
245 memData.Length = length;
248 alureStream *stream = create_stream(memData);
249 if(!stream) return NULL;
251 stream->data = streamData;
252 return InitStream(stream, chunkLength, numBufs, bufs);
255 /* Function: alureCreateStreamFromStaticMemory
257 * Identical to <alureCreateStreamFromMemory>, except the given memory is used
258 * directly and not duplicated. As a consequence, the data buffer must remain
259 * valid while the stream is alive. Requires an active context.
262 * An opaque handle used to control the opened stream, or NULL on error.
265 * <alureStreamSizeIsMicroSec>, <alureCreateStreamFromFile>,
266 * <alureCreateStreamFromMemory>, <alureCreateStreamFromCallback>
268 ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(const ALubyte *fdata, ALuint length, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs)
270 if(alGetError() != AL_NO_ERROR)
272 SetError("Existing OpenAL error");
278 SetError("Invalid chunk length");
284 SetError("Invalid buffer count");
290 SetError("Invalid data length");
295 memData.Data = fdata;
296 memData.Length = length;
299 alureStream *stream = create_stream(memData);
300 if(!stream) return NULL;
302 return InitStream(stream, chunkLength, numBufs, bufs);
305 /* Function: alureCreateStreamFromCallback
307 * Creates a stream using the specified callback to retrieve data. Requires an
311 * callback - This is called when more data is needed from the stream. Up to
312 * the specified number of bytes should be written to the data
313 * pointer, and the number of bytes actually written should be
314 * returned. The number of bytes written must be block aligned for
315 * the format (eg. a multiple of 4 for AL_FORMAT_STEREO16), or an
316 * OpenAL error may occur during buffering.
317 * userdata - A handle passed through to the callback.
318 * format - The format of the data the callback will be giving. The format must
319 * be valid for the context.
320 * samplerate - The sample rate (frequency) of the stream
323 * An opaque handle used to control the opened stream, or NULL on error.
326 * <alureStreamSizeIsMicroSec>, <alureCreateStreamFromFile>,
327 * <alureCreateStreamFromMemory>, <alureCreateStreamFromStaticMemory>
329 ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback(
330 ALuint (*callback)(void *userdata, ALubyte *data, ALuint bytes),
331 void *userdata, ALenum format, ALuint samplerate,
332 ALsizei chunkLength, ALsizei numBufs, ALuint *bufs)
334 if(alGetError() != AL_NO_ERROR)
336 SetError("Existing OpenAL error");
342 SetError("Invalid callback");
348 SetError("Invalid chunk length");
354 SetError("Invalid buffer count");
359 newcb.open_file = NULL;
360 newcb.open_mem = NULL;
361 newcb.get_fmt = NULL;
362 newcb.decode = callback;
366 alureStream *stream = create_stream(userdata, format, samplerate, newcb);
367 return InitStream(stream, chunkLength, numBufs, bufs);
370 /* Function: alureGetStreamFrequency
372 * Retrieves the frequency used by the given stream.
377 * *Version Added*: 1.1
379 ALURE_API ALsizei ALURE_APIENTRY alureGetStreamFrequency(alureStream *stream)
384 if(!alureStream::Verify(stream))
386 SetError("Invalid stream pointer");
390 if(!stream->GetFormat(&format, &rate, &balign))
392 SetError("Could not get stream format");
399 /* Function: alureBufferDataFromStream
401 * Buffers the given buffer objects with the next chunks of data from the
402 * stream. The given buffer objects do not need to be ones given by the
403 * alureCreateStream functions. Requires an active context.
406 * The number of buffers filled with new data, or -1 on error. If the value
407 * returned is less than the number requested, the end of the stream has been
410 ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream(alureStream *stream, ALsizei numBufs, ALuint *bufs)
412 if(alGetError() != AL_NO_ERROR)
414 SetError("Existing OpenAL error");
418 if(!alureStream::Verify(stream))
420 SetError("Invalid stream pointer");
426 SetError("Invalid buffer count");
430 for(ALsizei i = 0;i < numBufs;i++)
432 if(!bufs[i] || !alIsBuffer(bufs[i]))
434 SetError("Invalid buffer ID");
440 ALuint freq, blockAlign;
442 if(!stream->GetFormat(&format, &freq, &blockAlign))
444 SetError("Could not get stream format");
449 for(filled = 0;filled < numBufs;filled++)
451 ALuint got = stream->GetData(&stream->dataChunk[0], stream->dataChunk.size());
452 got -= got%blockAlign;
455 alBufferData(bufs[filled], format, &stream->dataChunk[0], got, freq);
456 if(alGetError() != AL_NO_ERROR)
458 SetError("Buffer load failed");
466 /* Function: alureRewindStream
468 * Rewinds the stream so that the next alureBufferDataFromStream call will
469 * restart from the beginning of the audio file.
475 * <alureSetStreamOrder>
477 ALURE_API ALboolean ALURE_APIENTRY alureRewindStream(alureStream *stream)
479 if(!alureStream::Verify(stream))
481 SetError("Invalid stream pointer");
485 return stream->Rewind();
488 /* Function: alureSetStreamOrder
490 * Skips the module decoder to the specified order, so following buffering
491 * calls will decode from the specified order. For non-module formats, setting
492 * order 0 is identical to rewinding the stream (other orders will fail).
497 * *Version Added*: 1.1
500 * <alureRewindStream>
502 ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder(alureStream *stream, ALuint order)
504 if(!alureStream::Verify(stream))
506 SetError("Invalid stream pointer");
510 return stream->SetOrder(order);
513 /* Function: alureSetStreamPatchset
515 * Specifies the patchset to use for MIDI streams. By default, the FluidSynth
516 * decoder will look for one in the FLUID_SOUNDFONT environment variable, but
517 * this can be used to change it to something different. On non-MIDI streams,
518 * this has no effect.
523 * *Version Added*: 1.1
525 ALURE_API ALboolean ALURE_APIENTRY alureSetStreamPatchset(alureStream *stream, const ALchar *patchset)
527 if(!alureStream::Verify(stream))
529 SetError("Invalid stream pointer");
533 return stream->SetPatchset(patchset);
536 /* Function: alureGetStreamLength
538 * Retrieves an approximate number of samples for the stream. Not all streams
539 * or decoders can return such info, and may return 0 if the stream length is
545 * *Version Added*: 1.2
547 ALURE_API alureInt64 ALURE_APIENTRY alureGetStreamLength(alureStream *stream)
549 if(!alureStream::Verify(stream))
551 SetError("Invalid stream pointer");
555 return stream->GetLength();
558 /* Function: alureDestroyStream
560 * Closes an opened stream. For convenience, it will also delete the given
561 * buffer objects. The given buffer objects do not need to be ones given by the
562 * alureCreateStream functions. Requires an active context.
567 ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream(alureStream *stream, ALsizei numBufs, ALuint *bufs)
569 if(alGetError() != AL_NO_ERROR)
571 SetError("Existing OpenAL error");
577 SetError("Invalid buffer count");
581 if(stream && !alureStream::Verify(stream))
583 SetError("Invalid stream pointer");
589 alDeleteBuffers(numBufs, bufs);
590 if(alGetError() != AL_NO_ERROR)
592 SetError("Buffer deletion failed");
600 std::istream *f = stream->fstream;