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
;