Class AL

java.lang.Object
org.lwjgl.openal.AL
public final class AL extends Object
This class must be used before any OpenAL function is called. It has the following responsibilities:
  • Creates instances of ALCapabilities classes. An ALCapabilities instance contains flags for functionality that is available in an OpenAL context. Internally, it also contains function pointers that are only valid in that specific OpenAL context.
  • Maintains thread-local and global state for ALCapabilities instances, corresponding to OpenAL contexts that are current in those threads and the entire process, respectively.

ALCapabilities creation

Instances of ALCapabilities can be created with the createCapabilities(ALCCapabilities) method. An OpenAL context must be current in the current thread or process before it is called. Calling this method is expensive, so ALCapabilities instances should be cached in user code.

Thread-local state

Before a function for a given OpenAL context can be called, the corresponding ALCapabilities instance must be made current in the current thread or process. The user is also responsible for clearing the current ALCapabilities instance when the context is destroyed or made current in another thread.

Note that OpenAL contexts are made current process-wide by default. Current thread-local contexts are only available if the ALC_EXT_thread_local_context extension is supported by the OpenAL implementation. OpenAL Soft, the implementation that LWJGL ships with, supports this extension and performs better when it is used.

See Also:

  • Method Details

    • setCurrentProcess

      public static void setCurrentProcess(@Nullable ALCapabilities caps)
      Sets the specified ALCapabilities for the current process-wide OpenAL context.

      If the current thread had a context current (see setCurrentThread(ALCapabilities)), those ALCapabilities are cleared. Any OpenAL functions called in the current thread, or any threads that have no context current, will use the specified ALCapabilities.

      Parameters:
      caps - the ALCapabilities to make current, or null

    • setCurrentThread

      public static void setCurrentThread(@Nullable ALCapabilities caps)
      Sets the specified ALCapabilities for the current OpenAL context in the current thread.

      Any OpenAL functions called in the current thread will use the specified ALCapabilities.

      Parameters:
      caps - the ALCapabilities to make current, or null

    • getCapabilities

      public static ALCapabilities getCapabilities()
      Returns the ALCapabilities for the OpenAL context that is current in the current thread or process.
      Throws:
      IllegalStateException - if no OpenAL context is current in the current thread or process

    • createCapabilities

      public static ALCapabilities createCapabilities(ALCCapabilities alcCaps)
      Creates a new ALCapabilities instance for the OpenAL context that is current in the current thread or process.

      This method calls setCurrentProcess(ALCapabilities) (or setCurrentThread(ALCapabilities) if applicable) with the new instance before returning.

      Parameters:
      alcCaps - the ALCCapabilities of the device associated with the current context
      Returns:
      the ALCapabilities instance

    • createCapabilities

      public static ALCapabilities createCapabilities(ALCCapabilities alcCaps, @Nullable IntFunction<PointerBuffer> bufferFactory)
      Creates a new ALCapabilities instance for the OpenAL context that is current in the current thread or process.
      Parameters:
      alcCaps - the ALCCapabilities of the device associated with the current context
      bufferFactory - a function that allocates a PointerBuffer given a size. The buffer must be filled with zeroes. If null, LWJGL will allocate a GC-managed buffer internally.
      Returns:
      the ALCapabilities instance