| Automatic Playback | |
| Functions | |
| alurePlaySourceStream | Starts playing a stream, using the specified source ID. |
| alurePlaySource | Plays the specified source ID and watches for it to stop. |
| alureStopSource | Stops the specified source ID, and any associated stream. |
| alurePauseSource | Pauses the specified source ID, and any associated stream. |
| alureResumeSource | Resumes the specified source ID after being paused. |
| alureUpdate | Updates the running list of streams, and checks for stopped sources. |
| alureUpdateInterval | Sets up a timer or thread to automatically call alureUpdate at the given interval, in seconds. |
ALURE_API ALboolean ALURE_APIENTRY alurePlaySourceStream( ALuint source, alureStream * stream, ALsizei numBufs, ALsizei loopcount, void (*eos_callback)(void *userdata, ALuint source), void * userdata )
Starts playing a stream, using the specified source ID. A stream can only be played if it is not already playing. You must call alureUpdate at regular intervals to keep the stream playing, or else the stream will underrun and cause a break in the playback until an update call can restart it. It is also important that the current context is kept for alureUpdate calls if ALC_EXT_thread_local_context is not supported, otherwise the method may start calling OpenAL with invalid IDs. Note that checking the state of the specified source is not a good method to determine if a stream is playing. If an underrun occurs, the source will enter a stopped state until it is automatically restarted. Instead, set a flag using the callback to indicate the stream being stopped.
| source | The source ID to play the stream with. Any buffers on the source will be unqueued. It is valid to set source properties not related to the buffer queue or playback state (ie. you may change the source’s position, pitch, gain, etc, but you must not stop the source or queue/unqueue buffers on it). To pause the source, call alurePauseSource. |
| stream | The stream to play. Any valid stream will work, although looping will only work if the stream can be rewound (eg. streams made with alureCreateStreamFromCallback cannot loop, but will play for as long as the callback provides data). |
| numBufs | The number of buffers used to queue with the OpenAL source. Each buffer will be filled with the chunk length specified when the stream was created. This value must be at least 2. More buffers at a larger size will increase the time needed between updates, but at the cost of more memory usage. |
| loopcount | The number of times to loop the stream. When the stream reaches the end of processing, it will be rewound to continue buffering data. A value of -1 will cause the stream to loop indefinitely (or until alureStopSource is called). |
| eos_callback | This callback will be called when the stream reaches the end, no more loops are pending, and the source reaches a stopped state. It will also be called if an error occured and playback terminated. |
| userdata | An opaque user pointer passed to the callback. |
AL_FALSE on error.
Version Added: 1.1
ALURE_API ALboolean ALURE_APIENTRY alurePlaySource( ALuint source, void (*callback)(void *userdata, ALuint source), void * userdata )
Plays the specified source ID and watches for it to stop. When the source enters an AL_STOPPED or AL_INITIAL state, the specified callback will be called by alureUpdate to alert the application. If ALC_EXT_thread_local_context is not supported, the current context must not be changed while the source is being watched (before the callback is called or alureStopSource is called). It also must not be deleted while being watched.
| source | The source ID to play. As with alurePlaySourceStream, it is valid to set source properties not related to the playback state (ie. you may change a source’s position, pitch, gain, etc). Pausing a source and restarting a paused source is allowed, and the callback will still be called when the source reaches an AL_STOPPED or AL_INITIAL state. |
| callback | The callback to be called when the source stops. |
| userdata | An opaque user pointer passed to the callback. |
AL_FALSE on error.
Version Added: 1.1
ALURE_API ALboolean ALURE_APIENTRY alureStopSource( ALuint source, ALboolean run_callback )
Stops the specified source ID, and any associated stream. The previously specified callback will be invoked if ‘run_callback’ is not AL_FALSE. Sources that were not started with alurePlaySourceStream or alurePlaySource will still be stopped, but will not have any callback called for them.
AL_FALSE on error.
Version Added: 1.1
ALURE_API ALboolean ALURE_APIENTRY alurePauseSource( ALuint source )
Pauses the specified source ID, and any associated stream. This is needed to avoid potential race conditions with sources that are playing a stream.
Note that it is possible for the specified source to become stopped, and any associated stream to finish, before this function is called, causing the callback to be delayed until after the function returns and alureUpdate detects the stopped source.
AL_FALSE on error.
Version Added: 1.1
ALURE_API void ALURE_APIENTRY alureUpdate( void )
Updates the running list of streams, and checks for stopped sources. This makes sure that sources played with alurePlaySourceStream are kept fed from their associated stream, and sources played with alurePlaySource are still playing. It will call their callbacks as needed.
Version Added: 1.1
ALURE_API ALboolean ALURE_APIENTRY alureUpdateInterval( ALfloat interval )
Sets up a timer or thread to automatically call alureUpdate at the given interval, in seconds. If the timer or thread is already running, the update interval will be modified. A 0 or negative interval will stop alureUpdate from being called.
AL_FALSE on error.
Version Added: 1.1
Starts playing a stream, using the specified source ID.
ALURE_API ALboolean ALURE_APIENTRY alurePlaySourceStream( ALuint source, alureStream * stream, ALsizei numBufs, ALsizei loopcount, void (*eos_callback)(void *userdata, ALuint source), void * userdata )
Plays the specified source ID and watches for it to stop.
ALURE_API ALboolean ALURE_APIENTRY alurePlaySource( ALuint source, void (*callback)(void *userdata, ALuint source), void * userdata )
Stops the specified source ID, and any associated stream.
ALURE_API ALboolean ALURE_APIENTRY alureStopSource( ALuint source, ALboolean run_callback )
Pauses the specified source ID, and any associated stream.
ALURE_API ALboolean ALURE_APIENTRY alurePauseSource( ALuint source )
Resumes the specified source ID after being paused.
ALURE_API ALboolean ALURE_APIENTRY alureResumeSource( ALuint source )
Updates the running list of streams, and checks for stopped sources.
ALURE_API void ALURE_APIENTRY alureUpdate( void )
Sets up a timer or thread to automatically call alureUpdate at the given interval, in seconds.
ALURE_API ALboolean ALURE_APIENTRY alureUpdateInterval( ALfloat interval )
Creates a stream using the specified callback to retrieve data.
ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback( ALuint (*callback)(void *userdata, ALubyte *data, ALuint bytes), void * userdata, ALenum format, ALuint samplerate, ALsizei chunkLength, ALsizei numBufs, ALuint * bufs )