From 319bf76905e829f30c6abe705d9205bd28c4e929 Mon Sep 17 00:00:00 2001 From: Chris Robinson Date: Fri, 19 Feb 2010 23:39:26 -0800 Subject: [PATCH] Some documentation cleanups --- docs/html/files/buffer-cpp.html | 8 ++++---- docs/html/files/stream-cpp.html | 18 +++++++++--------- docs/html/files/streamplay-cpp.html | 2 +- src/buffer.cpp | 8 ++++---- src/stream.cpp | 34 ++++++---------------------------- src/streamplay.cpp | 4 ++-- 6 files changed, 26 insertions(+), 48 deletions(-) diff --git a/docs/html/files/buffer-cpp.html b/docs/html/files/buffer-cpp.html index 33ffea7..509a795 100644 --- a/docs/html/files/buffer-cpp.html +++ b/docs/html/files/buffer-cpp.html @@ -15,13 +15,13 @@ if (browserType) {document.write("
");if (browserV

Functions

-

alureCreateBufferFromFile

ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromFile(const ALchar *fname)

Loads the given file into a new OpenAL buffer object.  The formats supported depend on the options the library was compiled with, what libraries are available at runtime, and the installed decode callbacks.  Requires an active context.

Returns

A new buffer ID with the loaded sound, or AL_NONE on error.

See Also

alureCreateBufferFromMemory, alureBufferDataFromFile

+

alureCreateBufferFromFile

ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromFile(const ALchar *fname)

Loads the given file into a new OpenAL buffer object.  The formats supported depend on the options the library was compiled with, what libraries are available at runtime, and the installed decode callbacks.  Requires an active context.

Returns

A new buffer ID with the loaded sound, or AL_NONE on error.

See Also

alureBufferDataFromFile

-

alureCreateBufferFromMemory

ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromMemory(
   const ALubyte *fdata,
   ALsizei length
)

Loads a file image from memory into a new OpenAL buffer object, similar to alureCreateBufferFromFile.  Requires an active context.

Returns

A new buffer ID with the loaded sound, or AL_NONE on error.

See Also

alureCreateBufferFromFile, alureBufferDataFromMemory

+

alureCreateBufferFromMemory

ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromMemory(
   const ALubyte *fdata,
   ALsizei length
)

Loads a file image from memory into a new OpenAL buffer object, similar to alureCreateBufferFromFile.  Requires an active context.

Returns

A new buffer ID with the loaded sound, or AL_NONE on error.

See Also

alureBufferDataFromMemory

-

alureBufferDataFromFile

ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromFile(
   const ALchar *fname,
   ALuint buffer
)

Loads the given file into an existing OpenAL buffer object.  The previous contents of the buffer are replaced.  Requires an active context.

Returns

AL_FALSE on error.

See Also

alureCreateBufferFromFile, alureBufferDataFromMemory

+

alureBufferDataFromFile

ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromFile(
   const ALchar *fname,
   ALuint buffer
)

Loads the given file into an existing OpenAL buffer object.  The previous contents of the buffer are replaced.  Requires an active context.

Returns

AL_FALSE on error.

See Also

alureCreateBufferFromFile

-

alureBufferDataFromMemory

ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromMemory(
   const ALubyte *fdata,
   ALsizei length,
   ALuint buffer
)

Loads a file image from memory into an existing OpenAL buffer object, similar to alureBufferDataFromFile.  Requires an active context.

Returns

AL_FALSE on error.

See Also

alureCreateBufferFromMemory, alureBufferDataFromFile

+

alureBufferDataFromMemory

ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromMemory(
   const ALubyte *fdata,
   ALsizei length,
   ALuint buffer
)

Loads a file image from memory into an existing OpenAL buffer object, similar to alureBufferDataFromFile.  Requires an active context.

Returns

AL_FALSE on error.

See Also

alureCreateBufferFromMemory

diff --git a/docs/html/files/stream-cpp.html b/docs/html/files/stream-cpp.html index d907d40..6283b0a 100644 --- a/docs/html/files/stream-cpp.html +++ b/docs/html/files/stream-cpp.html @@ -15,23 +15,23 @@ if (browserType) {document.write("
");if (browserV

Functions

-

alureCreateStreamFromFile

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(
   const ALchar *fname,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Opens a file and sets it up for streaming.  The given chunkLength is the number of bytes each buffer will fill with.  ALURE will optionally generate the specified number of buffer objects, fill them with the beginning of the data, then place the new IDs into the provided storage, before returning.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureRewindStream, alureDestroyStream

+

alureCreateStreamFromFile

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(
   const ALchar *fname,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Opens a file and sets it up for streaming.  The given chunkLength is the number of bytes each buffer will fill with.  ALURE will optionally generate the specified number of buffer objects, fill them with the beginning of the data, then place the new IDs into the provided storage, before returning.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback

-

alureCreateStreamFromMemory

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(
   const ALubyte *fdata,
   ALuint length,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Opens a file image from memory and sets it up for streaming, similar to alureCreateStreamFromFile.  The given data buffer can be safely deleted after calling this function.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureRewindStream, alureDestroyStream

+

alureCreateStreamFromMemory

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(
   const ALubyte *fdata,
   ALuint length,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Opens a file image from memory and sets it up for streaming, similar to alureCreateStreamFromFile.  The given data buffer can be safely deleted after calling this function.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback

-

alureCreateStreamFromStaticMemory

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(
   const ALubyte *fdata,
   ALuint length,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Identical to alureCreateStreamFromMemory, except the given memory is used directly and not duplicated.  As a consequence, the data buffer must remain valid while the stream is alive.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureRewindStream, alureDestroyStream

+

alureCreateStreamFromStaticMemory

ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(
   const ALubyte *fdata,
   ALuint length,
   ALsizei chunkLength,
   ALsizei numBufs,
   ALuint *bufs
)

Identical to alureCreateStreamFromMemory, except the given memory is used directly and not duplicated.  As a consequence, the data buffer must remain valid while the stream is alive.  Requires an active context.

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromCallback

-

alureCreateStreamFromCallback

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
)

Creates a stream using the specified callback to retrieve data.  Requires an active context.

Parameters

callbackThis is called when more data is needed from the stream.  Up to the specified number of bytes should be written to the data pointer, and the number of bytes actually written should be returned.  The number of bytes written must be block aligned for the format (eg. a multiple of 4 for AL_FORMAT_STEREO16), or an OpenAL error may occur during buffering.
userdataA handle passed through to the callback.
formatThe format of the data the callback will be giving.  The format must be valid for the context.
samplerateThe sample rate (frequency) of the stream

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureBufferDataFromStream, alureRewindStream, alureDestroyStream

+

alureCreateStreamFromCallback

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
)

Creates a stream using the specified callback to retrieve data.  Requires an active context.

Parameters

callbackThis is called when more data is needed from the stream.  Up to the specified number of bytes should be written to the data pointer, and the number of bytes actually written should be returned.  The number of bytes written must be block aligned for the format (eg. a multiple of 4 for AL_FORMAT_STEREO16), or an OpenAL error may occur during buffering.
userdataA handle passed through to the callback.
formatThe format of the data the callback will be giving.  The format must be valid for the context.
samplerateThe sample rate (frequency) of the stream

Returns

An opaque handle used to control the opened stream, or NULL on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory

-

alureGetStreamFormat

ALURE_API ALboolean ALURE_APIENTRY alureGetStreamFormat(alureStream *stream,
ALenum *format,
ALuint *frequency,
ALuint *blockAlign)

Retrieves the format, frequency, and block-alignment used for the given stream.  If a parameter is NULL, that value will not be returned.

Returns

AL_FALSE on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback,

+

alureGetStreamFormat

ALURE_API ALboolean ALURE_APIENTRY alureGetStreamFormat(alureStream *stream,
ALenum *format,
ALuint *frequency,
ALuint *blockAlign)

Retrieves the format, frequency, and block-alignment used for the given stream.  If a parameter is NULL, that value will not be returned.

Returns

AL_FALSE on error.

-

alureBufferDataFromStream

ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream(alureStream *stream,
ALsizei numBufs,
ALuint *bufs)

Buffers the given buffer objects with the next chunks of data from the stream.  The given buffer objects do not need to be ones given by the alureCreateStreamFrom* functions.  Requires an active context.

Returns

The number of buffers filled with new data, or -1 on error.  If the value returned is less than the number requested, the end of the stream has been reached.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureRewindStream, alureDestroyStream

+

alureBufferDataFromStream

ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream(alureStream *stream,
ALsizei numBufs,
ALuint *bufs)

Buffers the given buffer objects with the next chunks of data from the stream.  The given buffer objects do not need to be ones given by the alureCreateStreamFrom* functions.  Requires an active context.

Returns

The number of buffers filled with new data, or -1 on error.  If the value returned is less than the number requested, the end of the stream has been reached.

-

alureRewindStream

ALURE_API ALboolean ALURE_APIENTRY alureRewindStream(alureStream *stream)

Rewinds the stream so that the next alureBufferDataFromStream call will restart from the beginning of the audio file.

Returns

AL_FALSE on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureSetStreamOrder, alureDestroyStream

+

alureRewindStream

ALURE_API ALboolean ALURE_APIENTRY alureRewindStream(alureStream *stream)

Rewinds the stream so that the next alureBufferDataFromStream call will restart from the beginning of the audio file.

Returns

AL_FALSE on error.

See Also

alureSetStreamOrder

-

alureSetStreamOrder

ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder(alureStream *stream,
ALuint order)

Skips the module decoder to the specified order, so following buffering calls will decode from the specified order.  For non-module formats, setting order 0 is identical to rewinding the stream (other orders will fail).

Returns

AL_FALSE on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureRewindStream, alureDestroyStream

+

alureSetStreamOrder

ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder(alureStream *stream,
ALuint order)

Skips the module decoder to the specified order, so following buffering calls will decode from the specified order.  For non-module formats, setting order 0 is identical to rewinding the stream (other orders will fail).

Returns

AL_FALSE on error.

See Also

alureRewindStream

-

alureDestroyStream

ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream(alureStream *stream,
ALsizei numBufs,
ALuint *bufs)

Closes an opened stream.  For convenience, it will also delete the given buffer objects.  The given buffer objects do not need to be ones given by the alureCreateStreamFrom* functions.  Requires an active context.

Returns

AL_FALSE on error.

See Also

alureCreateStreamFromFile, alureCreateStreamFromMemory, alureCreateStreamFromStaticMemory, alureCreateStreamFromCallback, alureBufferDataFromStream, alureRewindStream

+

alureDestroyStream

ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream(alureStream *stream,
ALsizei numBufs,
ALuint *bufs)

Closes an opened stream.  For convenience, it will also delete the given buffer objects.  The given buffer objects do not need to be ones given by the alureCreateStreamFrom* functions.  Requires an active context.

Returns

AL_FALSE on error.

diff --git a/docs/html/files/streamplay-cpp.html b/docs/html/files/streamplay-cpp.html index 4092e26..ae25b42 100644 --- a/docs/html/files/streamplay-cpp.html +++ b/docs/html/files/streamplay-cpp.html @@ -21,7 +21,7 @@ if (browserType) {document.write("
");if (browserV

alureStopSource

ALURE_API ALboolean ALURE_APIENTRY alureStopSource(ALuint source,
ALboolean run_callback)

Stops the specified source ID, and any associated asynchronous 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.

Returns

AL_FALSE on error.

See Also

alurePlaySourceStream, alurePlaySource

-

alurePauseSource

ALURE_API ALboolean ALURE_APIENTRY alurePauseSource(ALuint source,
ALboolean resume)

Pauses the specified source ID, and any associated asynchronous stream.  This is needed to avoid potential race conditions with sources that are playing an asynchronous stream.  Pass AL_TRUE to ‘resume’ to resume a paused stream.

Note that it is possible for the specified source to become stopped, and any associated stream to finish, before this function is called, and the callback to be delayed until after the function returns when the async thread detects the stopped source.

Returns

AL_FALSE on error.

See Also

alurePlaySourceStream, alurePlaySource

+

alurePauseSource

ALURE_API ALboolean ALURE_APIENTRY alurePauseSource(ALuint source,
ALboolean resume)

Pauses the specified source ID, and any associated asynchronous stream.  This is needed to avoid potential race conditions with sources that are playing an asynchronous stream.  Pass AL_TRUE to ‘resume’ to resume a paused 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 when the async thread detects the stopped source.

Returns

AL_FALSE on error.

See Also

alurePlaySourceStream, alurePlaySource

alureGetSourceOffset

ALURE_API alureUInt64 ALURE_APIENTRY alureGetSourceOffset(ALuint source)

Gets the sample offset of the specified source.  For sources started with alurePlaySourceStream, this will be the total samples played.  The offset will loop back to 0 when the stream rewinds for any specified loopcount.  For non-streamed sources, the function will behave as if retrieving the AL_SAMPLE_OFFSET source value.

Returns

(alureUInt64)-1 on error.

See Also

alurePlaySourceStream

diff --git a/src/buffer.cpp b/src/buffer.cpp index afa3520..2ce65fa 100644 --- a/src/buffer.cpp +++ b/src/buffer.cpp @@ -94,7 +94,7 @@ extern "C" { * A new buffer ID with the loaded sound, or AL_NONE on error. * * See Also: - * , + * */ ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromFile(const ALchar *fname) { @@ -131,7 +131,7 @@ ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromFile(const ALchar *fname) * A new buffer ID with the loaded sound, or AL_NONE on error. * * See Also: - * , + * */ ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromMemory(const ALubyte *fdata, ALsizei length) { @@ -168,7 +168,7 @@ ALURE_API ALuint ALURE_APIENTRY alureCreateBufferFromMemory(const ALubyte *fdata * AL_FALSE on error. * * See Also: - * , + * */ ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromFile(const ALchar *fname, ALuint buffer) { @@ -192,7 +192,7 @@ ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromFile(const ALchar *fname, * AL_FALSE on error. * * See Also: - * , + * */ ALURE_API ALboolean ALURE_APIENTRY alureBufferDataFromMemory(const ALubyte *fdata, ALsizei length, ALuint buffer) { diff --git a/src/stream.cpp b/src/stream.cpp index 817428f..2663858 100644 --- a/src/stream.cpp +++ b/src/stream.cpp @@ -113,8 +113,7 @@ extern "C" { * * See Also: * , , - * , , - * , + * */ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(const ALchar *fname, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs) { @@ -157,8 +156,7 @@ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromFile(const ALchar *fn * * See Also: * , , - * , , - * , + * */ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(const ALubyte *fdata, ALuint length, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs) { @@ -216,8 +214,7 @@ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromMemory(const ALubyte * * See Also: * , , - * , , - * , + * */ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(const ALubyte *fdata, ALuint length, ALsizei chunkLength, ALsizei numBufs, ALuint *bufs) { @@ -282,8 +279,7 @@ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromStaticMemory(const AL * * See Also: * , , - * , , - * , + * */ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback( ALuint (*callback)(void *userdata, ALubyte *data, ALuint bytes), @@ -333,10 +329,6 @@ ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback( * * Returns: * AL_FALSE on error. - * - * See Also: - * , , - * , , */ ALURE_API ALboolean ALURE_APIENTRY alureGetStreamFormat(alureStream *stream, ALenum *format, ALuint *frequency, ALuint *blockAlign) @@ -373,11 +365,6 @@ ALURE_API ALboolean ALURE_APIENTRY alureGetStreamFormat(alureStream *stream, * The number of buffers filled with new data, or -1 on error. If the value * returned is less than the number requested, the end of the stream has been * reached. - * - * See Also: - * , , - * , , - * , */ ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream(alureStream *stream, ALsizei numBufs, ALuint *bufs) { @@ -435,9 +422,7 @@ ALURE_API ALsizei ALURE_APIENTRY alureBufferDataFromStream(alureStream *stream, * AL_FALSE on error. * * See Also: - * , , - * , , - * , , + * */ ALURE_API ALboolean ALURE_APIENTRY alureRewindStream(alureStream *stream) { @@ -460,9 +445,7 @@ ALURE_API ALboolean ALURE_APIENTRY alureRewindStream(alureStream *stream) * AL_FALSE on error. * * See Also: - * , , - * , , - * , , + * */ ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder(alureStream *stream, ALuint order) { @@ -483,11 +466,6 @@ ALURE_API ALboolean ALURE_APIENTRY alureSetStreamOrder(alureStream *stream, ALui * * Returns: * AL_FALSE on error. - * - * See Also: - * , , - * , , - * , */ ALURE_API ALboolean ALURE_APIENTRY alureDestroyStream(alureStream *stream, ALsizei numBufs, ALuint *bufs) { diff --git a/src/streamplay.cpp b/src/streamplay.cpp index 776a642..bcf5b8a 100644 --- a/src/streamplay.cpp +++ b/src/streamplay.cpp @@ -610,8 +610,8 @@ ALURE_API ALboolean ALURE_APIENTRY alureStopSource(ALuint source, ALboolean run_ * is needed to avoid potential race conditions with sources that are playing * an asynchronous stream. Pass AL_TRUE to 'resume' to resume a paused stream. * - * Note that it is possible for the specified source to become stopped, and - * any associated stream to finish, before this function is called, and the + * 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 when the async * thread detects the stopped source. * -- 2.11.4.GIT