BlitzMax/Modules/Audio/OpenAL 1.1

=Constants=

=Functions=

OpenALInstalled
Function OpenALInstalled

Description: Check if OpenAL is installed.

Returns: True if OpenAL is installed.

Information: This function allows you to determine whether OpenAL is installed on the current machine.

=Globals=

alcOpenDevice
Global alcOpenDevice( devicename$z )

Description: This function opens a device by name.

Information: The return value will be NULL if there is an error.

Returns a pointer to the opened device. Will return NULL if a device can not be opened.

alcCloseDevice
Global alcCloseDevice( device )

Description: This function closes a device by name.

Information: Any contexts and buffers within the device will be destroyed when the device is closed, and ALC_TRUE will be returned on success or ALC_FALSE on failure.

alcGetError
Global alcGetError( device )

Description: This function retrieves the current context error state.

Information:

alcGetString
Global alcGetString:Byte Ptr( device,param )

Description: This function returns pointers to strings related to the context.

Information: ALC_DEFAULT_DEVICE_SPECIFIER will return the name of the default output device.

ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER will return the name of the default capture device.

ALC_DEVICE_SPECIFIER will return the name of the specified output device if a pointer is supplied, or will return a list of all available devices if a NULL device pointer is supplied. A list is a pointer to a series of strings separated by NULL characters, with the list terminated by two NULL characters.

ALC_CAPTURE_DEVICE_SPECIFIER will return the name of the specified capture device if a pointer is supplied, or will return a list of all available devices if a NULL device pointer is supplied.

ALC_EXTENSIONS returns a list of available context extensions, with each extension separated by a space and the list terminated by a NULL character.

alcGetIntegerv
Global alcGetIntegerv( device,param,size,data:Int Ptr )

Description: This function returns integers related to the context.

Information: The versions returned refer to the specification version that the implementation meets.

alcCreateContext
Global alcCreateContext( device,attrlist:Int Ptr )

Description: This function creates a context using a specified device.

Information:

Returns: A pointer to the new context (NULL on failure).

alcMakeContextCurrent
Global alcMakeContextCurrent( context )

Description: This function makes a specified context the current context.

Information: Returns ALC_TRUE on success, or ALC_FALSE on failure.

alcProcessContext
Global alcProcessContext( context )

Description: This function tells a context to begin processing.

Information: When a context is suspended, changes in OpenAL state will be accepted but will not be processed. alcSuspendContext can be used to suspend a context, and then all the OpenAL state changes can be applied at once, followed by a call to alcProcessContext to apply all the state changes immediately. In some cases, this procedure may be more efficient than application of properties in a non-suspended state. In some implementations, process and suspend calls are each a NOP.

alcSuspendContext
Global alcSuspendContext( context )

Description: This function suspends processing on a specified context.

Information: When a context is suspended, changes in OpenAL state will be accepted but will not be processed. A typical use of alcSuspendContext would be to suspend a context, apply all the OpenAL state changes at once, and then call alcProcessContext to apply all the state changes at once. In some cases, this procedure may be more efficient than application of properties in a non-suspended state. In some implementations, process and suspend calls are each a NOP.

alcDestroyContext
Global alcDestroyContext( context )

Description: This function destroys a context.

Information: A context which is not current can be destroyed at any time (all sources within that context will also be deleted - buffers are not affected). alcMakeContextCurrent should be used to make sure the context to be destroyed is not current (NULL is valid for alcMakeContextCurrent).

alcGetCurrentContext
Global alcGetCurrentContext

Description: This function retrieves the current context.

Returns: a pointer to the current context.

alcGetContextsDevice
Global alcGetContextsDevice( context )

Description: This function retrieves a context's device pointer.

Information:

Returns: a pointer to the specified context's device.

alcIsExtensionPresent
Global alcIsExtensionPresent( device,extName$z )

Description: This function queries if a specified context extension is available.

Information: Returns ALC_TRUE if the extension is available, ALC_FALSE if the extension is not available.

alcGetProcAddress
Global alcGetProcAddress:Byte Ptr( device,funcName$z )

Description: This function retrieves the address of a specified context extension function.

Information: Returns the address of the function, or NULL if it is not found.

alcGetEnumValue
Global alcGetEnumValue( device,enumName$z )

Description: This function retrieves the enum value for a specified enumeration name.

Information: Returns the enum value described by the enumName string. This is most often used for querying an enum value for an ALC extension.

alcCaptureOpenDevice
Global alcCaptureOpenDevice( devicename$z,frequency,format,buffersize )

Description: This function opens a capture device by name.

Information: Returns the capture device pointer, or NULL on failure.

alcCaptureCloseDevice
Global alcCaptureCloseDevice( device )

Description: This function closes the specified capture device.

Information: Returns ALC_TRUE if the close operation was successful, ALC_FALSE on failure.

alcCaptureStart
Global alcCaptureStart( device )

Description: This function begins a capture operation.

Information: alcCaptureStart will begin recording to an internal ring buffer of the size specified when opening the capture device. The application can then retrieve the number of samples currently available using the ALC_CAPTURE_SAPMPLES token with alcGetIntegerv. When the application determines that enough samples are available for processing, then it can obtain them with a call to alcCaptureSamples.

alcCaptureStop
Global alcCaptureStop( device )

Description: This function stops a capture operation.

Information:

alcCaptureSamples
Global alcCaptureSamples( device,buffer:Byte Ptr,samples )

Description: This function completes a capture operation.

Information:

alEnable
Global alEnable( capability )

Description: This function enables a feature of the OpenAL driver.

Information: There are no capabilities defined in OpenAL 1.1 to be used with this function, but it may be used by an extension.

alDisable
Global alDisable( capability )

Description: This function disables a feature of the OpenAL driver.

Information: There are no capabilities defined in OpenAL 1.1 to be used with this function, but it may be used by an extension.

alIsEnabled
Global alIsEnabled( capability )

Description: This function returns a boolean indicating if a specific feature is enabled in the OpenAL

Information: Returns AL_TRUE if the capability is enabled, AL_FALSE if the capability is disabled. There are no capabilities defined in OpenAL 1.1 to be used with this function, but it may be used by an extension.

alGetString
Global alGetString:Byte Ptr( param )

Description: This function retrieves an OpenAL string property.

Information: Returns a pointer to a null-terminated string.

alGetBooleanv
Global alGetBooleanv( param,data:Byte Ptr )

Description: This function retrieves a boolean OpenAL state.

Information:

alGetIntegerv
Global alGetIntegerv( param,data:Int Ptr )

Description: This function retrieves an integer OpenAL state.

Information:

alGetFloatv
Global alGetFloatv( param,data:Float Ptr )

Description: This function retrieves a floating point OpenAL state.

Information:

alGetDoublev
Global alGetDoublev( param,data:Double Ptr )

Description: This function retrieves a double precision floating point OpenAL state.

Information:

alGetBoolean
Global alGetBoolean( param )

Description: This function returns a boolean OpenAL state.

Information: The boolean state described by param will be returned.

alGetInteger
Global alGetInteger( param )

Description: This function returns an integer OpenAL state.

Information: The integer state described by param will be returned.

alGetFloat
Global alGetFloat#( param )

Description: This function returns a floating point OpenAL state.

Information: The floating point state described by param will be returned.

alGetDouble
Global alGetDouble!( param )

Description: This function returns a double precision floating point OpenAL state.

Information: The double value described by param will be returned.

alGetError
Global alGetError

Description: This function returns the current error state and then clears the error state.

Information: Returns an Alenum representing the error state. When an OpenAL error occurs, the error state is set and will not be changed until the error state is retrieved using alGetError. Whenever alGetError is called, the error state is cleared and the last state (the current state when the call was made) is returned. To isolate error detection to a specific portion of code, alGetError should be called before the isolated section to clear the current error state.

alIsExtensionPresent
Global alIsExtensionPresent( extname$z )

Description: This function tests if a specific extension is available for the OpenAL driver.

Information: Returns AL_TRUE if the extension is available, AL_FALSE if the extension is not available.

alGetProcAddress
Global alGetProcAddress:Byte Ptr( fname$z )

Description: This function returns the address of an OpenAL extension function.

Information: The return value is a pointer to the specified function. The return value will be NULL if the function is not found.

alGetEnumValue
Global alGetEnumValue( ename$z )

Description: This function returns the enumeration value of an OpenAL enum described by a string.

Information: Returns the actual ALenum described by a string. Returns NULL if the string doesnt describe a valid OpenAL enum.

alListenerf
Global alListenerf( param,value# )

Description: This function sets a floating point property for the listener. The relevant properties are listed in the table Listener Properties.

Information:

alListener3f
Global alListener3f( param,value1#,value2#,value3# )

Description: This function sets a floating point property for the listener. The relevant properties are listed in the table Listener Properties.

Information:

alListenerfv
Global alListenerfv( param,values:Float Ptr )

Description: This function sets a floating point-vector property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alListeneri
Global alListeneri( param,value )

Description: This function sets an integer property of the listener.

Information: There are no integer listener attributes defined for OpenAL 1.1, but this function may be used by an extension.

alListener3i
Global alListener3i( param,value1,value2,value3 )

Description: This function sets an integer property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alListeneriv
Global alListeneriv( param,values:Int Ptr )

Description: This function sets an integer property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGetListenerf
Global alGetListenerf( param,value:Float Ptr )

Description: This function retrieves a floating point property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGetListener3f
Global alGetListener3f( param,value1:Float Ptr,value2:Float Ptr,value3:Float Ptr )

Description: This function retrieves a set of three floating point values from a property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGetListenerfv
Global alGetListenerfv( param,values:Float Ptr )

Description: This function retrieves a floating point-vector property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGetListeneri
Global alGetListeneri( param,value:Int Ptr )

Description: This function retrieves an integer property of the listener.

Information: There are no integer listener attributes defined for OpenAL 1.1, but this function may be used by an extension.

alGetListener3i
Global alGetListener3i( param,value1:Int Ptr,value2:Int Ptr,value3:Int Ptr )

Description: This function retrieves an integer property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGetListeneriv
Global alGetListeneriv( param,values:Int Ptr )

Description: This function retrieves an integer property of the listener. The relevant properties are listed in the table Listener Properties.

Information:

alGenBuffers
Global alGenBuffers( n,buffers:Int Ptr )

Description: This Function generates one or more buffers, which contain audio data (see alBufferData). References To buffers are ALuint values, which are used wherever a buffer reference is needed (in calls such as alDeleteBuffers, alSourcei, alSourceQueueBuffers, and alSourceUnqueueBuffers).

Information: If the requested number of buffers cannot be created, an error will be generated which can be detected with alGetError. If an error occurs, no buffers will be generated. If n equals zero, alGenBuffers does nothing and does not Return an error.

alDeleteBuffers
Global alDeleteBuffers( n,buffers:Int Ptr )

Description: This function deletes one or more buffers, freeing the resources used by the buffer. Buffers which are attached to a source can not be deleted. See alSourcei and alSourceUnqueueBuffers for information on how to detach a buffer from a source.

Information: If the requested number of buffers cannot be deleted, an error will be generated which can be detected with alGetError. If an error occurs, no buffers will be deleted. If n equals zero, alDeleteBuffers does nothing and will not return an error.

alIsBuffer
Global alIsBuffer( bid )

Description: This function tests if a buffer name is valid, returning AL_TRUE if valid, AL_FALSE if not.

Information: The NULL buffer is always valid (see alSourcei for information on how the NULL buffer is used).

alBufferData
Global alBufferData( bid,format,data:Byte Ptr,size,freq )

Description: This function fills a buffer with audio data. All the pre-defined formats are PCM data, but this function may be used by extensions to load other data types as well.

Information: 8-bit PCM data is expressed as an unsigned value over the range 0 to 255, 128 being an audio output level of zero. 16-bit PCM data is expressed as a signed value over the range -32768 to 32767, 0 being an audio output level of zero. Stereo data is expressed in interleaved format, left channel first. Buffers containing more than one channel of data will be played without 3D spatialization.

alBufferf
Global alBufferf( bid,param,value# )

Description: This Function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this Function may be used by OpenAL extensions.

alBuffer3f
Global alBuffer3f( bid,param,value1#,value2#,value3# )

Description: This function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.

alBufferfv
Global alBufferfv( bid,param,values:Float Ptr )

Description: This function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.

alBufferi
Global alBufferi( bid,param,value )

Description: This Function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this Function may be used by OpenAL extensions.

alBuffer3i
Global alBuffer3i( bid,param,value1,value2,value3 )

Description: This Function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this Function may be used by OpenAL extensions.

alBufferiv
Global alBufferiv( bid,param,values:Int Ptr )

Description: This Function sets a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this Function may be used by OpenAL extensions.

alGetBufferf
Global alGetBufferf( bid,param,value:Float Ptr )

Description: This Function retrieves a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this Function may be used by OpenAL extensions.

alGetBuffer3f
Global alGetBuffer3f( bid,param,value1:Float Ptr,value2:Float Ptr,value3:Float Ptr )

Description: This Function retrieves a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this Function may be used by OpenAL extensions.

alGetBufferfv
Global alGetBufferfv( bid,param,values:Float Ptr )

Description: This Function retrieves a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this Function may be used by OpenAL extensions.

alGetBufferi
Global alGetBufferi( bid,param,value:Int Ptr )

Description: This Function retrieves a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this Function may be used by OpenAL extensions.

alGetBuffer3i
Global alGetBuffer3i( bid,param,value1:Int Ptr,value2:Int Ptr,value3:Int Ptr )

Description: This Function retrieves a floating point property of a buffer.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this Function may be used by OpenAL extensions.

alGetBufferiv
Global alGetBufferiv( bid,param,values:Int Ptr )

Description: This Function retrieves a floating point property of a buffer. The relevant properties are listed in the table Buffer Properties.

Information: There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this function may be used by OpenAL extensions.

alGenSources
Global alGenSources( n,sources:Int Ptr )

Description: This Function generates one or more sources. References To sources are ALuint values, which are used wherever a source reference is needed (in calls such as alDeleteSources and alSourcei).

Information: If the requested number of sources cannot be created, an error will be generated which can be detected with alGetError. If an error occurs, no sources will be generated. If n equals zero, alGenSources does nothing and does not Return an error.

alDeleteSources
Global alDeleteSources( n,sources:Int Ptr )

Description: This function deletes one or more sources.

Information: If the requested number of sources cannot be deleted, an error will be generated which can be detected with alGetError. If an error occurs, no sources will be deleted. If n equals zero, alDeleteSources does nothing and will not return an error. A playing source can be deleted - the source will be stopped and then deleted.

alIsSource
Global alIsSource( sid )

Description: This function tests if a source name is valid, returning AL_TRUE if valid and AL_FALSE if not.

Information:

alSourcef
Global alSourcef( sid,param,value# )

Description: This function sets a floating point property of a source. The relevant properties are listed in the table Source Properties.

Information:

alSource3f
Global alSource3f( sid,param,value1#,value2#,value3# )

Description: This function sets a source property requiring three floating point values. The relevant properties are listed in the table Source Properties.

Information: This function is an alternative to alSourcefv.

alSourcefv
Global alSourcefv( sid,param,values:Float Ptr )

Description: This function sets a source property requiring three floating point values. The relevant properties are listed in the table Source Properties.

Information: This function is an alternative to alSource3f.

alSourcei
Global alSourcei( sid,param,value )

Description: This function sets an integer property of a source. The relevant properties are listed in the table Source Properties.

Information: The buffer name zero is reserved as a "NULL Buffer" and is accepted by alSourcei(..., AL_BUFFER, ...) as a valid buffer of zero length. The NULL Buffer is extremely useful for detaching buffers from a source which were attached using this call or with alSourceQueueBuffers.

alSource3i
Global alSource3i( sid,param,value1,value2,value3 )

Description: This function sets an integer property of a source. The relevant properties are listed in the table Source Properties.

Information:

alSourceiv
Global alSourceiv( sid,param,values:Int Ptr )

Description: This function sets an integer property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSourcef
Global alGetSourcef( sid,param,value:Float Ptr )

Description: This function retrieves a floating point property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSource3f
Global alGetSource3f( sid,param,value1:Float Ptr,value2:Float Ptr,value3:Float Ptr )

Description: This function retrieves three floating point values representing a property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSourcefv
Global alGetSourcefv( sid,param,values:Float Ptr )

Description: This function retrieves a floating point-vector property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSourcei
Global alGetSourcei( sid,param,value:Int Ptr )

Description: This function retrieves an integer property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSource3i
Global alGetSource3i( sid,param,value1:Int Ptr,value2:Int Ptr,value3:Int Ptr )

Description: This function retrieves an integer property of a source. The relevant properties are listed in the table Source Properties.

Information:

alGetSourceiv
Global alGetSourceiv( sid,param,values:Int Ptr )

Description: This function retrieves an integer property of a source. The relevant properties are listed in the table Source Properties.

Information:

alSourcePlayv
Global alSourcePlayv( ns,sids:Int Ptr )

Description: This function plays a set of sources.

Information: The playing sources will have their state changed to AL_PLAYING. When called on a source which is already playing, the source will restart at the beginning. When the attached buffer(s) are done playing, the source will progress to the AL_STOPPED state.

alSourceStopv
Global alSourceStopv( ns,sids:Int Ptr )

Description: This function stops a set of sources.

Information: The stopped sources will have their state changed to AL_STOPPED.

alSourceRewindv
Global alSourceRewindv( ns,sids:Int Ptr )

Description: This function stops a set of sources and sets all their states to AL_INITIAL.

Information:

alSourcePausev
Global alSourcePausev( ns,sids:Int Ptr )

Description: This function pauses a set of sources.

Information: The paused sources will have their state changed to AL_PAUSED.

alSourcePlay
Global alSourcePlay( sid )

Description: This function plays a source.

Information: The playing source will have its state changed to AL_PLAYING. When called on a source which is already playing, the source will restart at the beginning. When the attached buffer(s) are done playing, the source will progress to the AL_STOPPED state.

alSourceStop
Global alSourceStop( sid )

Description: This function stops a source.

Information: The stopped source will have its state changed to AL_STOPPED.

alSourceRewind
Global alSourceRewind( sid )

Description: This function stops the source and sets its state to AL_INITIAL.

Information:

alSourcePause
Global alSourcePause( sid )

Description: This function pauses a source.

Information: The paused source will have its state changed to AL_PAUSED.

alSourceQueueBuffers
Global alSourceQueueBuffers( sid,numEntries,bids:Int Ptr )

Description: This function queues a set of buffers on a source. All buffers attached to a source will be played in sequence, and the number of processed buffers can be detected using an alSourcei call to retrieve AL_BUFFERS_PROCESSED.

Information: When first created, a source will be of type AL_UNDETERMINED. A successful alSourceQueueBuffers call will change the source type to AL_STREAMING.

alSourceUnqueueBuffers
Global alSourceUnqueueBuffers( sid,numEntries,bids:Int Ptr )

Description: This function unqueues a set of buffers attached to a source. The number of processed buffers can be detected using an alSourcei call to retrieve AL_BUFFERS_PROCESSED, which is the maximum number of buffers that can be unqueued using this call.

Information: The unqueue operation will only take place if all n buffers can be removed from the queue.

alDopplerFactor
Global alDopplerFactor( value# )

Description: This function selects the OpenAL Doppler factor value.

Information: The default Doppler factor value is 1.0.

alDopplerVelocity
Global alDopplerVelocity( value# )

Description: This function selects the speed of sound for use in Doppler calculations.

Information: The default speed of sound value is 343.3.

alSpeedOfSound
Global alSpeedOfSound( value# )

Description: This function selects the speed of sound for use in Doppler calculations.

Information: The default speed of sound value is 343.3.

alDistanceModel
Global alDistanceModel( distanceModel )

Description: This function selects the OpenAL distance model.

The AL_INVERSE_DISTANCE model works according to the following formula:

G_dB = AL_GAIN - 20log10(1 + AL_ROLLOFF_FACTOR*(distance - AL_REFERENCE_DISTANCE)/AL_REFERENCE_DISTANCE)); G_dB = min(G_dB, AL_MAX_GAIN); G_dB = max(G_dB, AL_MIN_GAIN);

The AL_INVERSE_DISTANCE_CLAMPED model works according to the following formula:

distance = max(distance, AL_REFERENCE_DISTANCE); distance = min(distance, AL_MAX_DISTANCE); G_dB = AL_GAIN - 20log10(1 + AL_ROLLOFF_FACTOR*(distance - AL_REFERENCE_DISTANCE)/AL_REFERENCE_DISTANCE)); G_dB = min(G_dB, AL_MAX_GAIN); G_dB = max(G_dB, AL_MIN_GAIN);

The AL_NONE model works according to the following formula:

G_db = AL_GAIN;

Information: The default distance model in OpenAL is AL_INVERSE_DISTANCE_CLAMPED.