Class AL10

java.lang.Object
org.lwjgl.openal.AL10

public final class AL10 extends Object

This is the core OpenAL class. This class implements AL.h version 1.0

Version:
$Revision$ $Id$
Author:
Brian Matzon <brian@matzon.dk>
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Sound buffers: The number of bits per sample for the data contained in the buffer.
    static final int
    Indicate the buffer to provide sound samples.
    static final int
    Buffer Queue params
    static final int
    Buffer Queue params
    static final int
    Specify the channel mask.
    static final int
    Sound buffers: The number of channels for the data contained in the buffer.
    static final int
    Directional source, inner cone angle, in degrees Range: [0-360] Default: 360
    static final int
    Directional source, outer cone angle, in degrees.
    static final int
    Indicate the gain (volume amplification) applied.
    static final int
    Deprecated.
    This token is a relict of the early OpenAL days and is no longer supported.
    static final int
    Specify the current direction as forward vector.
    static final int
    Distance model.
    static final int
    Doppler scale.
    static final int
    Doppler velocity.
    static final int
    Context strings: Extensions
    static final int
    Boolean False
    static final int
    Sound buffers: format specifier.
    static final int
    Sound buffers: format specifier.
    static final int
    Sound buffers: format specifier.
    static final int
    Sound buffers: format specifier.
    static final int
    Ogg Vorbis format specifier.
    static final int
    Sound buffers: frequency, in units of Hertz [Hz].
    static final int
    Indicate the gain (volume amplification) applied.
    static final int
    Source state information
    static final int
    Bad value
    static final int
    Illegal enum passed as an argument to an AL call.
    static final int
    Illegal name passed as an argument to an AL call.
    static final int
    A function was called at inappropriate time, or in an inappropriate way, causing an illegal state.
    static final int
    Illegal value passed as an argument to an AL call.
    static final int
    Distance model
    static final int
    Distance model
    static final int
    Indicate whether source has to loop infinite.
    static final int
    Specify the maximum distance.
    static final int
    Indicate maximum source attenuation.
    static final int
    Indicate minimum source attenuation.
    static final int
    Errors: No Error.
    static final int
    Disable value
    static final int
    Specify the current orientation.
    static final int
    A function could not be completed, because there is not enough memory available.
    static final int
    Source state information
    static final int
    Buffer state.
    static final int
    Specify the pitch to be applied, either at source, or on mixer results, at listener.
    static final int
    Source state information
    static final int
    Specify the current location in three dimensional space.
    static final int
    Buffer state.
    static final int
    Specify the current orientation.
    static final int
    Context strings: Renderer
    static final int
    Indicate the rolloff factor for the source.
    static final int
    Sound buffers: Size in bytes of the buffer data.
    static final int
    Indicate source has absolute coordinates
    static final int
    Indicate Source has listener relative coordinates
    static final int
    Source state information
    static final int
    Indicate the type of SOURCE.
    static final int
    Source state information
    static final int
    Boolean True
    static final int
    Buffer state.
    static final int
    Specify the current velocity in three dimensional space.
    static final int
    Context strings: Vendor
    static final int
    Context strings: Version
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    alBufferData(int buffer, int format, ByteBuffer data, int freq)
    A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer.
    static void
    alBufferData(int buffer, int format, IntBuffer data, int freq)
    A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer.
    static void
    alBufferData(int buffer, int format, ShortBuffer data, int freq)
    A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer.
    static void
    alDeleteBuffers(int buffer)
    Overloads alDeleteBuffers.
    static void
    The application requests deletion of a number of Buffers by calling DeleteBuffers.
    static void
    alDeleteSources(int source)
    Overloads alDeleteSources.
    static void
    The application requests deletion of a number of Sources by DeleteSources.
    static void
    alDisable(int capability)
    The application can temporarily disable certain AL capabilities on a per Context basis.
    static void
    alDistanceModel(int value)
    Samples usually use the entire dynamic range of the chosen format/encoding, independent of their real world intensity.
    static void
    alDopplerFactor(float value)
    The Doppler Effect depends on the velocities of Source and Listener relative to the medium, and the propagation speed of sound in that medium.
    static void
    alDopplerVelocity(float value)
    The Doppler Effect depends on the velocities of Source and Listener relative to the medium, and the propagation speed of sound in that medium.
    static void
    alEnable(int capability)
    The application can temporarily disable certain AL capabilities on a per Context basis.
    static int
    Overloads alGenBuffers.
    static void
    The application requests a number of Buffers using GenBuffers.
    static int
    Overloads alGenSources.
    static void
    The application requests a number of Sources using GenSources.
    static boolean
    alGetBoolean(int pname)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static float
    alGetBufferf(int buffer, int pname)
    Buffer state is maintained inside the AL implementation and can be queried in full.
    ALC_FREQUENCY - specified in samples per second, i.e.
    static int
    alGetBufferi(int buffer, int pname)
    Buffer state is maintained inside the AL implementation and can be queried in full.
    ALC_FREQUENCY - specified in samples per second, i.e.
    static double
    alGetDouble(int pname)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static void
    alGetDouble(int pname, DoubleBuffer data)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static int
    To obtain enumeration values for extensions, the application has to use GetEnumValue of an extension token.
    static int
    The AL detects only a subset of those conditions that could be considered errors.
    static float
    alGetFloat(int pname)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static void
    alGetFloat(int pname, FloatBuffer data)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static int
    alGetInteger(int pname)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static void
    alGetInteger(int pname, IntBuffer data)
    Like OpenGL, AL uses a simplified interface for querying global state.
    static void
    alGetListener(int pname, FloatBuffer floatdata)
    Listener state is maintained inside the AL implementation and can be queried in full.
    static float
    alGetListenerf(int pname)
    Listener state is maintained inside the AL implementation and can be queried in full.
    static int
    alGetListeneri(int pname)
    Listener state is maintained inside the AL implementation and can be queried in full.
    static void
    alGetSource(int source, int pname, FloatBuffer floatdata)
    Source state is maintained inside the AL implementation, and the current attributes can be queried.
    static float
    alGetSourcef(int source, int pname)
    Source state is maintained inside the AL implementation, and the current attributes can be queried.
    static int
    alGetSourcei(int source, int pname)
    Source state is maintained inside the AL implementation, and the current attributes can be queried.
    static String
    alGetString(int pname)
    The application can retrieve state information global to the current AL Context.
    static boolean
    alIsBuffer(int buffer)
    The application can verify whether a buffer Name is valid using the IsBuffer query.
    static boolean
    alIsEnabled(int capability)
    The application can also query whether a given capability is currently enabled or not.
    static boolean
    To verify that a given extension is available for the current context and the device it is associated with, use this method.
    static boolean
    alIsSource(int id)
    The application can verify whether a source name is valid using the IsSource query.
    static void
    alListener(int pname, FloatBuffer value)
    Listener attributes are changed using the Listener group of commands.
    static void
    alListener3f(int pname, float v1, float v2, float v3)
    Listener attributes are changed using the Listener group of commands.
    static void
    alListenerf(int pname, float value)
    Listener attributes are changed using the Listener group of commands.
    static void
    alListeneri(int pname, int value)
    Listener attributes are changed using the Listener group of commands.
    static void
    alSource(int source, int pname, FloatBuffer value)
    Specifies the position and other properties as taken into account during sound processing.
    static void
    alSource3f(int source, int pname, float v1, float v2, float v3)
    Specifies the position and other properties as taken into account during sound processing.
    static void
    alSourcef(int source, int pname, float value)
    Specifies the position and other properties as taken into account during sound processing.
    static void
    alSourcei(int source, int pname, int value)
    Specifies the position and other properties as taken into account during sound processing.
    static void
    alSourcePause(int source)
    Pause() applied to an AL_INITIAL Source is a legal NOP.
    static void
    Pause() applied to an AL_INITIAL Source is a legal NOP.
    static void
    alSourcePlay(int source)
    Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus the data found in the Buffer will be fed into the processing, starting at the beginning.
    static void
    Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus the data found in the Buffer will be fed into the processing, starting at the beginning.
    static void
    alSourceQueueBuffers(int source, int buffer)
    Overloads alSourceQueueBuffers.
    static void
    alSourceQueueBuffers(int source, IntBuffer buffers)
    The application can queue up one or multiple buffer names using SourceQueueBuffers.
    static void
    alSourceRewind(int source)
    Rewind() applied to an AL_INITIAL Source is a legal NOP.
    static void
    Rewind() applied to an AL_INITIAL Source is a legal NOP.
    static void
    alSourceStop(int source)
    Stop() applied to an AL_INITIAL Source is a legal NOP.
    static void
    Stop() applied to an AL_INITIAL Source is a legal NOP.
    static int
    Overloads alSourceUnqueueBuffers.
    static void
    alSourceUnqueueBuffers(int source, IntBuffer buffers)
    Once a queue entry for a buffer has been appended to a queue and is pending processing, it should not be changed.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • AL_INVALID

      public static final int AL_INVALID
      Bad value
      See Also:
    • AL_NONE

      public static final int AL_NONE
      Disable value
      See Also:
    • AL_FALSE

      public static final int AL_FALSE
      Boolean False
      See Also:
    • AL_TRUE

      public static final int AL_TRUE
      Boolean True
      See Also:
    • AL_SOURCE_TYPE

      public static final int AL_SOURCE_TYPE
      Indicate the type of SOURCE. Sources can be spatialized
      See Also:
    • AL_SOURCE_ABSOLUTE

      public static final int AL_SOURCE_ABSOLUTE
      Indicate source has absolute coordinates
      See Also:
    • AL_SOURCE_RELATIVE

      public static final int AL_SOURCE_RELATIVE
      Indicate Source has listener relative coordinates
      See Also:
    • AL_CONE_INNER_ANGLE

      public static final int AL_CONE_INNER_ANGLE
      Directional source, inner cone angle, in degrees Range: [0-360] Default: 360
      See Also:
    • AL_CONE_OUTER_ANGLE

      public static final int AL_CONE_OUTER_ANGLE
      Directional source, outer cone angle, in degrees. Range: [0-360] Default: 360
      See Also:
    • AL_PITCH

      public static final int AL_PITCH
      Specify the pitch to be applied, either at source, or on mixer results, at listener. Range: [0.5-2.0] Default: 1.0
      See Also:
    • AL_POSITION

      public static final int AL_POSITION
      Specify the current location in three dimensional space. OpenAL, like OpenGL, uses a right handed coordinate system, where in a frontal default view X (thumb) points right, Y points up (index finger), and Z points towards the viewer/camera (middle finger). To switch from a left handed coordinate system, flip the sign on the Z coordinate. Listener position is always in the world coordinate system.
      See Also:
    • AL_DIRECTION

      public static final int AL_DIRECTION
      Specify the current direction as forward vector.
      See Also:
    • AL_VELOCITY

      public static final int AL_VELOCITY
      Specify the current velocity in three dimensional space.
      See Also:
    • AL_LOOPING

      public static final int AL_LOOPING
      Indicate whether source has to loop infinite. Type: ALboolean Range: [TRUE, FALSE] Default: FALSE
      See Also:
    • AL_BUFFER

      public static final int AL_BUFFER
      Indicate the buffer to provide sound samples. Type: ALuint. Range: any valid Buffer id.
      See Also:
    • AL_GAIN

      public static final int AL_GAIN
      Indicate the gain (volume amplification) applied. Type: ALfloat. Range: ]0.0- ] A value of 1.0 means un-attenuated/unchanged. Each division by 2 equals an attenuation of -6dB. Each multiplicaton with 2 equals an amplification of +6dB. A value of 0.0 is meaningless with respect to a logarithmic scale; it is interpreted as zero volume - the channel is effectively disabled.
      See Also:
    • AL_MIN_GAIN

      public static final int AL_MIN_GAIN
      Indicate minimum source attenuation. Type: ALfloat Range: [0.0 - 1.0]
      See Also:
    • AL_MAX_GAIN

      public static final int AL_MAX_GAIN
      Indicate maximum source attenuation. Type: ALfloat Range: [0.0 - 1.0]
      See Also:
    • AL_ORIENTATION

      public static final int AL_ORIENTATION
      Specify the current orientation. Type: ALfv6 (at/up) Range: N/A
      See Also:
    • AL_REFERENCE_DISTANCE

      public static final int AL_REFERENCE_DISTANCE
      Specify the current orientation. Type: ALfv6 (at/up) Range: N/A
      See Also:
    • AL_ROLLOFF_FACTOR

      public static final int AL_ROLLOFF_FACTOR
      Indicate the rolloff factor for the source. Type: ALfloat Range: [0.0 - ] Default: 1.0
      See Also:
    • AL_CONE_OUTER_GAIN

      public static final int AL_CONE_OUTER_GAIN
      Indicate the gain (volume amplification) applied. Type: ALfloat. Range: ]0.0- ] A value of 1.0 means un-attenuated/unchanged. Each division by 2 equals an attenuation of -6dB. Each multiplicaton with 2 equals an amplification of +6dB. A value of 0.0 is meaningless with respect to a logarithmic scale; it is interpreted as zero volume - the channel is effectively disabled.
      See Also:
    • AL_MAX_DISTANCE

      public static final int AL_MAX_DISTANCE
      Specify the maximum distance. Type: ALfloat Range: [0.0 - ]
      See Also:
    • AL_CHANNEL_MASK

      public static final int AL_CHANNEL_MASK
      Specify the channel mask. (Creative) Type: ALuint Range: [0 - 255]
      See Also:
    • AL_SOURCE_STATE

      public static final int AL_SOURCE_STATE
      Source state information
      See Also:
    • AL_INITIAL

      public static final int AL_INITIAL
      Source state information
      See Also:
    • AL_PLAYING

      public static final int AL_PLAYING
      Source state information
      See Also:
    • AL_PAUSED

      public static final int AL_PAUSED
      Source state information
      See Also:
    • AL_STOPPED

      public static final int AL_STOPPED
      Source state information
      See Also:
    • AL_BUFFERS_QUEUED

      public static final int AL_BUFFERS_QUEUED
      Buffer Queue params
      See Also:
    • AL_BUFFERS_PROCESSED

      public static final int AL_BUFFERS_PROCESSED
      Buffer Queue params
      See Also:
    • AL_FORMAT_MONO8

      public static final int AL_FORMAT_MONO8
      Sound buffers: format specifier.
      See Also:
    • AL_FORMAT_MONO16

      public static final int AL_FORMAT_MONO16
      Sound buffers: format specifier.
      See Also:
    • AL_FORMAT_STEREO8

      public static final int AL_FORMAT_STEREO8
      Sound buffers: format specifier.
      See Also:
    • AL_FORMAT_STEREO16

      public static final int AL_FORMAT_STEREO16
      Sound buffers: format specifier.
      See Also:
    • AL_FORMAT_VORBIS_EXT

      public static final int AL_FORMAT_VORBIS_EXT
      Ogg Vorbis format specifier.
      See Also:
    • AL_FREQUENCY

      public static final int AL_FREQUENCY
      Sound buffers: frequency, in units of Hertz [Hz]. This is the number of samples per second. Half of the sample frequency marks the maximum significant frequency component.
      See Also:
    • AL_BITS

      public static final int AL_BITS
      Sound buffers: The number of bits per sample for the data contained in the buffer.
      See Also:
    • AL_CHANNELS

      public static final int AL_CHANNELS
      Sound buffers: The number of channels for the data contained in the buffer.
      See Also:
    • AL_SIZE

      public static final int AL_SIZE
      Sound buffers: Size in bytes of the buffer data.
      See Also:
    • AL_DATA

      public static final int AL_DATA
      Deprecated.
      This token is a relict of the early OpenAL days and is no longer supported. Neither the OpenAL spec nor OpenAL Soft define it.
      See Also:
    • AL_UNUSED

      public static final int AL_UNUSED
      Buffer state.

      Not supported for public use (yet).

      See Also:
    • AL_PENDING

      public static final int AL_PENDING
      Buffer state.

      Not supported for public use (yet).

      See Also:
    • AL_PROCESSED

      public static final int AL_PROCESSED
      Buffer state.

      Not supported for public use (yet).

      See Also:
    • AL_NO_ERROR

      public static final int AL_NO_ERROR
      Errors: No Error.
      See Also:
    • AL_INVALID_NAME

      public static final int AL_INVALID_NAME
      Illegal name passed as an argument to an AL call.
      See Also:
    • AL_INVALID_ENUM

      public static final int AL_INVALID_ENUM
      Illegal enum passed as an argument to an AL call.
      See Also:
    • AL_INVALID_VALUE

      public static final int AL_INVALID_VALUE
      Illegal value passed as an argument to an AL call. Applies to parameter values, but not to enumerations.
      See Also:
    • AL_INVALID_OPERATION

      public static final int AL_INVALID_OPERATION
      A function was called at inappropriate time, or in an inappropriate way, causing an illegal state. This can be an incompatible ALenum, object ID, and/or function.
      See Also:
    • AL_OUT_OF_MEMORY

      public static final int AL_OUT_OF_MEMORY
      A function could not be completed, because there is not enough memory available.
      See Also:
    • AL_VENDOR

      public static final int AL_VENDOR
      Context strings: Vendor
      See Also:
    • AL_VERSION

      public static final int AL_VERSION
      Context strings: Version
      See Also:
    • AL_RENDERER

      public static final int AL_RENDERER
      Context strings: Renderer
      See Also:
    • AL_EXTENSIONS

      public static final int AL_EXTENSIONS
      Context strings: Extensions
      See Also:
    • AL_DOPPLER_FACTOR

      public static final int AL_DOPPLER_FACTOR
      Doppler scale. Default 1.0
      See Also:
    • AL_DOPPLER_VELOCITY

      public static final int AL_DOPPLER_VELOCITY
      Doppler velocity. Default 1.0
      See Also:
    • AL_DISTANCE_MODEL

      public static final int AL_DISTANCE_MODEL
      Distance model. Default INVERSE_DISTANCE_CLAMPED
      See Also:
    • AL_INVERSE_DISTANCE

      public static final int AL_INVERSE_DISTANCE
      Distance model
      See Also:
    • AL_INVERSE_DISTANCE_CLAMPED

      public static final int AL_INVERSE_DISTANCE_CLAMPED
      Distance model
      See Also:
  • Method Details

    • alEnable

      public static void alEnable(int capability)
      The application can temporarily disable certain AL capabilities on a per Context basis. This allows the driver implementation to optimize for certain subsets of operations. Enabling and disabling capabilities is handled using a function pair.

      Parameters:
      capability - name of a capability to enable
    • alDisable

      public static void alDisable(int capability)
      The application can temporarily disable certain AL capabilities on a per Context basis. This allows the driver implementation to optimize for certain subsets of operations. Enabling and disabling capabilities is handled using a function pair.

      Parameters:
      capability - name of a capability to disable
    • alIsEnabled

      public static boolean alIsEnabled(int capability)
      The application can also query whether a given capability is currently enabled or not.

      If the token used to specify target is not legal, an AL_INVALID_ENUM error will be generated.

      At this time, this mechanism is not used. There are no valid targets.

      Parameters:
      capability - name of a capability to check
      Returns:
      true if named feature is enabled
    • alGetBoolean

      public static boolean alGetBoolean(int pname)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Returns:
      boolean state described by pname will be returned.
    • alGetInteger

      public static int alGetInteger(int pname)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Returns:
      int state described by pname will be returned.
    • alGetFloat

      public static float alGetFloat(int pname)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Returns:
      float state described by pname will be returned.
    • alGetDouble

      public static double alGetDouble(int pname)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Returns:
      double state described by pname will be returned.
    • alGetInteger

      public static void alGetInteger(int pname, IntBuffer data)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Parameters:
      pname - state to be queried
      data - Buffer to place the integers in
    • alGetFloat

      public static void alGetFloat(int pname, FloatBuffer data)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Parameters:
      pname - state to be queried
      data - Buffer to place the floats in
    • alGetDouble

      public static void alGetDouble(int pname, DoubleBuffer data)
      Like OpenGL, AL uses a simplified interface for querying global state.

      Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY, AL_DISTANCE_MODEL.

      null destinations are quietly ignored. AL_INVALID_ENUM is the response to errors in specifying pName. The amount of memory required in the destination depends on the actual state requested.

      Parameters:
      pname - state to be queried
      data - Buffer to place the doubles in
    • alGetString

      public static String alGetString(int pname)
      The application can retrieve state information global to the current AL Context. GetString will return a pointer to a constant string. Valid values for param are VERSION, RENDERER, VENDOR, and EXTENSIONS, as well as the error codes defined by AL. The application can use GetString to retrieve a string for an error code.

      Parameters:
      pname - The property to be returned
      Returns:
      OpenAL String property
    • alGetError

      public static int alGetError()
      The AL detects only a subset of those conditions that could be considered errors. This is because in many cases error checking would adversely impact the performance of an error-free program.

      Each detectable error is assigned a numeric code. When an error is detected by AL, a flag is set and the error code is recorded. Further errors, if they occur, do not affect this recorded code. When GetError is called, the code is returned and the flag is cleared, so that a further error will again record its code. If a call to GetError returns AL_NO_ERROR then there has been no detectable error since the last call to GetError (or since the AL was initialized).

      Error codes can be mapped to strings. The GetString function returns a pointer to a constant (literal) string that is identical to the identifier used for the enumeration value, as defined in the specification.

      AL_NO_ERROR - "No Error" token.
      AL_INVALID_NAME - Invalid Name parameter.
      AL_INVALID_ENUM - Invalid parameter.
      AL_INVALID_VALUE - Invalid enum parameter value.
      AL_INVALID_OPERATION - Illegal call.
      AL_OUT_OF_MEMORY - Unable to allocate memory.

      The table summarizes the AL errors. Currently, when an error flag is set, results of AL operations are undefined only if AL_OUT_OF_MEMORY has occured. In other cases, the command generating the error is ignored so that it has no effect on AL state or output buffer contents. If the error generating command returns a value, it returns zero. If the generating command modifies values through a pointer argument, no change is made to these values. These error semantics apply only to AL errors, not to system errors such as memory access errors.

      Several error generation conditions are implicit in the description of the various AL commands. First, if a command that requires an enumerated value is passed a value that is not one of those specified as allowable for that command, the error AL_INVALID_ENUM results. This is the case even if the argument is a pointer to a symbolic constant if that value is not allowable for the given command. This will occur whether the value is allowable for other functions, or an invalid integer value.

      Integer parameters that are used as names for AL objects such as Buffers and Sources are checked for validity. If an invalid name parameter is specified in an AL command, an AL_INVALID_NAME error will be generated, and the command is ignored.

      If a negative integer is provided where an argument of type sizei is specified, the error AL_INVALID_VALUE results. The same error will result from attempts to set integral and floating point values for attributes exceeding the legal range for these. The specification does not guarantee that the implementation emits AL_INVALID_VALUE if a NaN or Infinity value is passed in for a float or double argument (as the specification does not enforce possibly expensive testing of floating point values).

      Commands can be invalid. For example, certain commands might not be applicable to a given object. There are also illegal combinations of tokens and values as arguments to a command. AL responds to any such illegal command with an AL_INVALID_OPERATION error.

      If memory is exhausted as a side effect of the execution of an AL command, either on system level or by exhausting the allocated resources at AL's internal disposal, the error AL_OUT_OF_MEMORY may be generated. This can also happen independent of recent commands if AL has to request memory for an internal task and fails to allocate the required memory from the operating system.

      Otherwise errors are generated only for conditions that are explicitely described in this specification.

      Returns:
      current error state
    • alIsExtensionPresent

      public static boolean alIsExtensionPresent(String fname)
      To verify that a given extension is available for the current context and the device it is associated with, use this method.

      A null name argument returns AL_FALSE, as do invalid and unsupported string tokens. A null deviceHandle will result in an INVALID_DEVICE error.

      Parameters:
      fname - String describing the desired extension
      Returns:
      true if extension is available, false if not
    • alGetEnumValue

      public static int alGetEnumValue(String ename)

      To obtain enumeration values for extensions, the application has to use GetEnumValue of an extension token. Enumeration values are defined within the AL namespace and allocated according to specification of the core API and the extensions, thus they are context-independent.

      Returns 0 if the enumeration can not be found. The presence of an enum value does not guarantee the applicability of an extension to the current context. A non-zero return indicates merely that the implementation is aware of the existence of this extension. Implementations should not attempt to return 0 to indicate that the extensions is not supported for the current context.

      Parameters:
      ename - String describing an OpenAL enum
      Returns:
      Actual int for the described enumeration name
    • alListeneri

      public static void alListeneri(int pname, int value)
      Listener attributes are changed using the Listener group of commands.

      Parameters:
      pname - name of the attribute to be set
      value - value to set the attribute to
    • alListenerf

      public static void alListenerf(int pname, float value)
      Listener attributes are changed using the Listener group of commands.

      Parameters:
      pname - name of the attribute to be set
      value - floating point value to set the attribute to
    • alListener

      public static void alListener(int pname, FloatBuffer value)
      Listener attributes are changed using the Listener group of commands.

      Parameters:
      pname - name of the attribute to be set
      value - FloatBuffer containing value to set the attribute to
    • alListener3f

      public static void alListener3f(int pname, float v1, float v2, float v3)
      Listener attributes are changed using the Listener group of commands.

      Parameters:
      pname - name of the attribute to be set
      v1 - value value 1
      v2 - value value 2
      v3 - float value 3
    • alGetListeneri

      public static int alGetListeneri(int pname)
      Listener state is maintained inside the AL implementation and can be queried in full.

      Parameters:
      pname - name of the attribute to be retrieved
      Returns:
      int
    • alGetListenerf

      public static float alGetListenerf(int pname)
      Listener state is maintained inside the AL implementation and can be queried in full.

      Parameters:
      pname - name of the attribute to be retrieved
      Returns:
      float
    • alGetListener

      public static void alGetListener(int pname, FloatBuffer floatdata)
      Listener state is maintained inside the AL implementation and can be queried in full.

      Parameters:
      pname - name of the attribute to be retrieved
      floatdata - Buffer to write floats to
    • alGenSources

      public static void alGenSources(IntBuffer sources)
      The application requests a number of Sources using GenSources.

      Parameters:
      sources - array holding sources
    • alGenSources

      public static int alGenSources()
      Overloads alGenSources.
    • alDeleteSources

      public static void alDeleteSources(IntBuffer sources)
      The application requests deletion of a number of Sources by DeleteSources.

      Parameters:
      sources - Source array to delete from
    • alDeleteSources

      public static void alDeleteSources(int source)
      Overloads alDeleteSources.
    • alIsSource

      public static boolean alIsSource(int id)
      The application can verify whether a source name is valid using the IsSource query.

      Parameters:
      id - id of source to be testes for validity
      Returns:
      true if id is valid, false if not
    • alSourcei

      public static void alSourcei(int source, int pname, int value)
      Specifies the position and other properties as taken into account during sound processing.

      Parameters:
      source - Source to det property on
      pname - property to set
      value - value of property
    • alSourcef

      public static void alSourcef(int source, int pname, float value)
      Specifies the position and other properties as taken into account during sound processing.

      Parameters:
      source - Source to det property on
      pname - property to set
      value - value of property
    • alSource

      public static void alSource(int source, int pname, FloatBuffer value)
      Specifies the position and other properties as taken into account during sound processing.

      Parameters:
      source - Source to set property on
      pname - property to set
      value - FloatBuffer containing value of property
    • alSource3f

      public static void alSource3f(int source, int pname, float v1, float v2, float v3)
      Specifies the position and other properties as taken into account during sound processing.

      Parameters:
      source - Source to set property on
      pname - property to set
      v1 - value 1 of property
      v2 - value 2 of property
      v3 - value 3 of property
    • alGetSourcei

      public static int alGetSourcei(int source, int pname)
      Source state is maintained inside the AL implementation, and the current attributes can be queried. The performance of such queries is implementation dependent, no performance guarantees are made.

      Parameters:
      source - source to get property from
      pname - name of property
      Returns:
      int
    • alGetSourcef

      public static float alGetSourcef(int source, int pname)
      Source state is maintained inside the AL implementation, and the current attributes can be queried. The performance of such queries is implementation dependent, no performance guarantees are made.

      Parameters:
      source - source to get property from
      pname - name of property
      Returns:
      float
    • alGetSource

      public static void alGetSource(int source, int pname, FloatBuffer floatdata)
      Source state is maintained inside the AL implementation, and the current attributes can be queried. The performance of such queries is implementation dependent, no performance guarantees are made.

      Parameters:
      source - Source to get property from
      pname - property to get
      floatdata - Buffer to write floats to
    • alSourcePlay

      public static void alSourcePlay(IntBuffer sources)
      Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus the data found in the Buffer will be fed into the processing, starting at the beginning. Play() applied to a AL_PLAYING Source will restart the Source from the beginning. It will not affect the configuration, and will leave the Source in AL_PLAYING state, but reset the sampling offset to the beginning. Play() applied to a AL_PAUSED Source will resume processing using the Source state as preserved at the Pause() operation. Play() applied to a AL_STOPPED Source will propagate it to AL_INITIAL then to AL_PLAYING immediately.

      Parameters:
      sources - array of sources to play
    • alSourcePause

      public static void alSourcePause(IntBuffer sources)
      Pause() applied to an AL_INITIAL Source is a legal NOP. Pause() applied to a AL_PLAYING Source will change its state to AL_PAUSED. The Source is exempt from processing, its current state is preserved. Pause() applied to a AL_PAUSED Source is a legal NOP. Pause() applied to a AL_STOPPED Source is a legal NOP.

      Parameters:
      sources - array of sources to pause
    • alSourceStop

      public static void alSourceStop(IntBuffer sources)
      Stop() applied to an AL_INITIAL Source is a legal NOP. Stop() applied to a AL_PLAYING Source will change its state to AL_STOPPED. The Source is exempt from processing, its current state is preserved. Stop() applied to a AL_PAUSED Source will change its state to AL_STOPPED, with the same consequences as on a AL_PLAYING Source. Stop() applied to a AL_STOPPED Source is a legal NOP.

      Parameters:
      sources - array of sources to stop
    • alSourceRewind

      public static void alSourceRewind(IntBuffer sources)
      Rewind() applied to an AL_INITIAL Source is a legal NOP. Rewind() applied to a AL_PLAYING Source will change its state to AL_STOPPED then AL_INITIAL. The Source is exempt from processing, its current state is preserved, with the exception of the sampling offset which is reset to the beginning. Rewind() applied to a AL_PAUSED Source will change its state to AL_INITIAL, with the same consequences as on a AL_PLAYING Source. Rewind() applied to a AL_STOPPED Source promotes the Source to AL_INITIAL, resetting the sampling offset to the beginning.

      Parameters:
      sources - array of sources to rewind
    • alSourcePlay

      public static void alSourcePlay(int source)
      Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus the data found in the Buffer will be fed into the processing, starting at the beginning. Play() applied to a AL_PLAYING Source will restart the Source from the beginning. It will not affect the configuration, and will leave the Source in AL_PLAYING state, but reset the sampling offset to the beginning. Play() applied to a AL_PAUSED Source will resume processing using the Source state as preserved at the Pause() operation. Play() applied to a AL_STOPPED Source will propagate it to AL_INITIAL then to AL_PLAYING immediately.

      Parameters:
      source - Source to play
    • alSourcePause

      public static void alSourcePause(int source)
      Pause() applied to an AL_INITIAL Source is a legal NOP. Pause() applied to a AL_PLAYING Source will change its state to AL_PAUSED. The Source is exempt from processing, its current state is preserved. Pause() applied to a AL_PAUSED Source is a legal NOP. Pause() applied to a AL_STOPPED Source is a legal NOP.

      Parameters:
      source - Source to pause
    • alSourceStop

      public static void alSourceStop(int source)
      Stop() applied to an AL_INITIAL Source is a legal NOP. Stop() applied to a AL_PLAYING Source will change its state to AL_STOPPED. The Source is exempt from processing, its current state is preserved. Stop() applied to a AL_PAUSED Source will change its state to AL_STOPPED, with the same consequences as on a AL_PLAYING Source. Stop() applied to a AL_STOPPED Source is a legal NOP.

      Parameters:
      source - Source to stop
    • alSourceRewind

      public static void alSourceRewind(int source)
      Rewind() applied to an AL_INITIAL Source is a legal NOP. Rewind() applied to a AL_PLAYING Source will change its state to AL_STOPPED then AL_INITIAL. The Source is exempt from processing, its current state is preserved, with the exception of the sampling offset which is reset to the beginning. Rewind() applied to a AL_PAUSED Source will change its state to AL_INITIAL, with the same consequences as on a AL_PLAYING Source. Rewind() applied to a AL_STOPPED Source promotes the Source to AL_INITIAL, resetting the sampling offset to the beginning.

      Parameters:
      source - Source to rewind
    • alGenBuffers

      public static void alGenBuffers(IntBuffer buffers)
      The application requests a number of Buffers using GenBuffers.

      Parameters:
      buffers - holding buffers
    • alGenBuffers

      public static int alGenBuffers()
      Overloads alGenBuffers.
    • alDeleteBuffers

      public static void alDeleteBuffers(IntBuffer buffers)

      The application requests deletion of a number of Buffers by calling DeleteBuffers.

      Once deleted, Names are no longer valid for use with AL function calls. Any such use will cause an AL_INVALID_NAME error. The implementation is free to defer actual release of resources.

      IsBuffer(bname) can be used to verify deletion of a buffer. Deleting bufferName 0 is a legal NOP in both scalar and vector forms of the command. The same is true for unused buffer names, e.g. such as not allocated yet, or as released already.

      Parameters:
      buffers - Buffer to delete from
    • alDeleteBuffers

      public static void alDeleteBuffers(int buffer)
      Overloads alDeleteBuffers.
    • alIsBuffer

      public static boolean alIsBuffer(int buffer)
      The application can verify whether a buffer Name is valid using the IsBuffer query.

      Parameters:
      buffer - buffer to be tested for validity
      Returns:
      true if supplied buffer is valid, false if not
    • alBufferData

      public static void alBufferData(int buffer, int format, ByteBuffer data, int freq)

      A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer. Applications can specify sample data using BufferData.

      The data specified is copied to an internal software, or if possible, hardware buffer. The implementation is free to apply decompression, conversion, resampling, and filtering as needed. The internal format of the Buffer is not exposed to the application, and not accessible. Valid formats are AL_FORMAT_MONO8, AL_FORMAT_MONO16, AL_FORMAT_STEREO8, and AL_FORMAT_STEREO16. An implementation may expose other formats, see the chapter on Extensions for information on determining if additional formats are supported.

      Applications should always check for an error condition after attempting to specify buffer data in case an implementation has to generate an AL_OUT_OF_MEMORY or conversion related AL_INVALID_VALUE error. The application is free to reuse the memory specified by the data pointer once the call to BufferData returns. The implementation has to dereference, e.g. copy, the data during BufferData execution.

      Parameters:
      buffer - Buffer to fill
      format - format sound data is in
      data - location of data
      freq - frequency of data
    • alBufferData

      public static void alBufferData(int buffer, int format, IntBuffer data, int freq)

      A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer. Applications can specify sample data using BufferData.

      The data specified is copied to an internal software, or if possible, hardware buffer. The implementation is free to apply decompression, conversion, resampling, and filtering as needed. The internal format of the Buffer is not exposed to the application, and not accessible. Valid formats are AL_FORMAT_MONO8, AL_FORMAT_MONO16, AL_FORMAT_STEREO8, and AL_FORMAT_STEREO16. An implementation may expose other formats, see the chapter on Extensions for information on determining if additional formats are supported.

      Applications should always check for an error condition after attempting to specify buffer data in case an implementation has to generate an AL_OUT_OF_MEMORY or conversion related AL_INVALID_VALUE error. The application is free to reuse the memory specified by the data pointer once the call to BufferData returns. The implementation has to dereference, e.g. copy, the data during BufferData execution.

      Parameters:
      buffer - Buffer to fill
      format - format sound data is in
      data - location of data
      freq - frequency of data
    • alBufferData

      public static void alBufferData(int buffer, int format, ShortBuffer data, int freq)

      A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer. Applications can specify sample data using BufferData.

      The data specified is copied to an internal software, or if possible, hardware buffer. The implementation is free to apply decompression, conversion, resampling, and filtering as needed. The internal format of the Buffer is not exposed to the application, and not accessible. Valid formats are AL_FORMAT_MONO8, AL_FORMAT_MONO16, AL_FORMAT_STEREO8, and AL_FORMAT_STEREO16. An implementation may expose other formats, see the chapter on Extensions for information on determining if additional formats are supported.

      Applications should always check for an error condition after attempting to specify buffer data in case an implementation has to generate an AL_OUT_OF_MEMORY or conversion related AL_INVALID_VALUE error. The application is free to reuse the memory specified by the data pointer once the call to BufferData returns. The implementation has to dereference, e.g. copy, the data during BufferData execution.

      Parameters:
      buffer - Buffer to fill
      format - format sound data is in
      data - location of data
      freq - frequency of data
    • alGetBufferi

      public static int alGetBufferi(int buffer, int pname)
      Buffer state is maintained inside the AL implementation and can be queried in full.
      ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].
      ALC_SIZE - Size in bytes of the buffer data.

      Parameters:
      buffer - buffer to get property from
      pname - name of property to retrieve
    • alGetBufferf

      public static float alGetBufferf(int buffer, int pname)
      Buffer state is maintained inside the AL implementation and can be queried in full.
      ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].
      ALC_SIZE - Size in bytes of the buffer data.

      Parameters:
      buffer - buffer to get property from
      pname - name of property to retrieve
      Returns:
      float
    • alSourceQueueBuffers

      public static void alSourceQueueBuffers(int source, IntBuffer buffers)

      The application can queue up one or multiple buffer names using SourceQueueBuffers. The buffers will be queued in the sequence in which they appear in the array.

      This command is legal on a Source in any state (to allow for streaming, queueing has to be possible on a AL_PLAYING Source). Queues are read-only with exception of the unqueue operation. The Buffer Name AL_NONE (i.e. 0) can be queued.

      Parameters:
      source - source to queue buffers onto
      buffers - buffers to be queued
    • alSourceQueueBuffers

      public static void alSourceQueueBuffers(int source, int buffer)
      Overloads alSourceQueueBuffers.
    • alSourceUnqueueBuffers

      public static void alSourceUnqueueBuffers(int source, IntBuffer buffers)

      Once a queue entry for a buffer has been appended to a queue and is pending processing, it should not be changed. Removal of a given queue entry is not possible unless either the Source is AL_STOPPED (in which case then entire queue is considered processed), or if the queue entry has already been processed (AL_PLAYING or AL_PAUSED Source).

      The Unqueue command removes a number of buffers entries that have finished processing, in the order of appearance, from the queue. The operation will fail if more buffers are requested than available, leaving the destination arguments unchanged. An AL_INVALID_VALUE error will be thrown. If no error, the destination argument will have been updated accordingly.

      Parameters:
      source - source to unqueue buffers from
      buffers - IntBuffer containing list of names that were unqueued
    • alSourceUnqueueBuffers

      public static int alSourceUnqueueBuffers(int source)
      Overloads alSourceUnqueueBuffers.
    • alDistanceModel

      public static void alDistanceModel(int value)

      Samples usually use the entire dynamic range of the chosen format/encoding, independent of their real world intensity. In other words, a jet engine and a clockwork both will have samples with full amplitude. The application will then have to adjust Source AL_GAIN accordingly to account for relative differences.

      Source AL_GAIN is then attenuated by distance. The effective attenuation of a Source depends on many factors, among which distance attenuation and source and Listener AL_GAIN are only some of the contributing factors. Even if the source and Listener AL_GAIN exceed 1.0 (amplification beyond the guaranteed dynamic range), distance and other attenuation might ultimately limit the overall AL_GAIN to a value below 1.0.

      AL currently supports three modes of operation with respect to distance attenuation. It supports two distance-dependent attenuation models, one which is similar to the IASIG I3DL2 (and DS3D) model. The application choses one of these two models (or can chose to disable distance-dependent attenuation effects model) on a per-context basis.

      Legal arguments are AL_NONE, AL_INVERSE_DISTANCE, and AL_INVERSE_DISTANCE_CLAMPED.

      AL_NONE bypasses all distance attenuation calculation for all Sources. The implementation is expected to optimize this situation.

      AL_INVERSE_DISTANCE_CLAMPED is the DS3D model, with AL_REFERENCE_DISTANCE indicating both the reference distance and the distance below which gain will be clamped.

      AL_INVERSE_DISTANCE is equivalent to the DS3D model with the exception that AL_REFERENCE_DISTANCE does not imply any clamping.

      The AL implementation is still free to apply any range clamping as necessary. The current distance model chosen can be queried using GetIntegerv and AL_DISTANCE_MODEL.

      Parameters:
      value - distance model to be set
    • alDopplerFactor

      public static void alDopplerFactor(float value)
      The Doppler Effect depends on the velocities of Source and Listener relative to the medium, and the propagation speed of sound in that medium. The application might want to emphasize or de-emphasize the Doppler Effect as physically accurate calculation might not give the desired results. The amount of frequency shift (pitch change) is proportional to the speed of listener and source along their line of sight. The application can increase or decrease that frequency shift by specifying the scaling factor AL should apply to the result of the calculation.

      The Doppler Effect as implemented by AL is described by the formula below. Effects of the medium (air, water) moving with respect to listener and source are ignored. AL_DOPPLER_VELOCITY is the propagation speed relative to which the Source velocities are interpreted.

               VD: AL_DOPPLER_VELOCITY
               DF: AL_DOPPLER_FACTOR
               vl: Listener velocity (scalar, projected on source-listener vector)
               vs: Source verlocity (scalar, projected on source-listener vector)
               f: Frequency in sample
               f': effective Doppler shifted frequency
       

      f' = DF * f * (VD-vl)/(VD+vs)

      vl<0, vs>0 : source and listener approaching each other vl>0, vs<0 : source and listener moving away from each other

      The implementation has to clamp the projected Listener velocity vl, if abs(vl) is greater or equal VD. It similarly has to clamp the projected Source velocity vs if abs(vs) is greater or equal VD.

      There are two API calls global to the current context that provide control of the two related parameters.

      AL_DOPPLER_FACTOR is a simple scaling to exaggerate or deemphasize the Doppler (pitch) shift resulting from the calculation.

      A negative value will result in an AL_INVALID_VALUE error, the command is then ignored. The default value is 1. The current setting can be queried using GetFloatv and AL_DOPPLER_FACTOR. The implementation is free to optimize the case of AL_DOPPLER_FACTOR being set to zero, as this effectively disables the effect.

      Parameters:
      value - Doppler scale value to set
    • alDopplerVelocity

      public static void alDopplerVelocity(float value)
      The Doppler Effect depends on the velocities of Source and Listener relative to the medium, and the propagation speed of sound in that medium. The application might want to emphasize or de-emphasize the Doppler Effect as physically accurate calculation might not give the desired results. The amount of frequency shift (pitch change) is proportional to the speed of listener and source along their line of sight. The application can increase or decrease that frequency shift by specifying the scaling factor AL should apply to the result of the calculation.

      The Doppler Effect as implemented by AL is described by the formula below. Effects of the medium (air, water) moving with respect to listener and source are ignored. AL_DOPPLER_VELOCITY is the propagation speed relative to which the Source velocities are interpreted.

               VD: AL_DOPPLER_VELOCITY
               DF: AL_DOPPLER_FACTOR
               vl: Listener velocity (scalar, projected on source-listener vector)
               vs: Source verlocity (scalar, projected on source-listener vector)
               f: Frequency in sample
               f': effective Doppler shifted frequency
       

      f' = DF * f * (VD-vl)/(VD+vs)

      vl<0, vs>0 : source and listener approaching each other vl>0, vs<0 : source and listener moving away from each other

      The implementation has to clamp the projected Listener velocity vl, if abs(vl) is greater or equal VD. It similarly has to clamp the projected Source velocity vs if abs(vs) is greater or equal VD.

      There are two API calls global to the current context that provide control of the two related parameters.

      AL_DOPPLER_VELOCITY allows the application to change the reference (propagation) velocity used in the Doppler Effect calculation. This permits the application to use a velocity scale appropriate to its purposes.

      A negative or zero value will result in an AL_INVALID_VALUE error, the command is then ignored. The default value is 1. The current setting can be queried using GetFloatv and AL_DOPPLER_VELOCITY.

      Parameters:
      value - Doppler velocity value to set