From cd85805588beacfe9896b1bc45fc26f2db8eff9c Mon Sep 17 00:00:00 2001 From: Brian Matzon Date: Sun, 3 Aug 2003 17:32:48 +0000 Subject: [PATCH] Added OpenAL specification to javadoc --- src/java/org/lwjgl/openal/AL.java | 2 +- src/java/org/lwjgl/openal/ALC.java | 155 ++++- src/java/org/lwjgl/openal/ALCcontext.java | 2 +- src/java/org/lwjgl/openal/ALCdevice.java | 2 +- src/java/org/lwjgl/openal/ALConstants.java | 2 +- src/java/org/lwjgl/openal/BaseAL.java | 2 +- .../org/lwjgl/openal/BaseALConstants.java | 2 +- src/java/org/lwjgl/openal/CoreAL.java | 534 ++++++++++++++++-- .../org/lwjgl/openal/OpenALException.java | 2 +- 9 files changed, 621 insertions(+), 82 deletions(-) diff --git a/src/java/org/lwjgl/openal/AL.java b/src/java/org/lwjgl/openal/AL.java index 256c5c52..1286105f 100644 --- a/src/java/org/lwjgl/openal/AL.java +++ b/src/java/org/lwjgl/openal/AL.java @@ -33,7 +33,7 @@ package org.lwjgl.openal; /** * $Id$ - * + *
* This is the OpenAL class. It extends the latest core. * * @author Brian Matzon diff --git a/src/java/org/lwjgl/openal/ALC.java b/src/java/org/lwjgl/openal/ALC.java index 22218ace..cb60ff43 100644 --- a/src/java/org/lwjgl/openal/ALC.java +++ b/src/java/org/lwjgl/openal/ALC.java @@ -35,9 +35,29 @@ import java.nio.Buffer; /** * $Id$ - * + * + *

* This is the context class for OpenAL. This class implements functions * in alc.h + *

+ * + *

+ * ALC introduces the notion of a Device. A Device can be, depending on the + * implementation, a hardware device, or a daemon/OS service/actual server. This + * mechanism also permits different drivers (and hardware) to coexist within the same + * system, as well as allowing several applications to share system resources for audio, + * including a single hardware output device. The details are left to the + * implementation, which has to map the available backends to unique device + * specifiers (represented as strings). + *

+ * + *

+ * NOTE:
+ * The LWJGL implementation of OpenAL does not expose the device, nor the context. + * Whenever AL is created using the create method, an underlying + * device and context is created. Thus more advanced usage of multiple contexts and/or devices + * are not possible. The above mentioned features are very rarely used in games. + *

* * @author Brian Matzon * @version $Revision$ @@ -58,17 +78,39 @@ public class ALC { /** Errors: No Error */ public static final int ALC_NO_ERROR = ALC_FALSE; + /** Major version query. */ public static final int ALC_MAJOR_VERSION = 0x1000; + + /** Minor version query. */ public static final int ALC_MINOR_VERSION = 0x1001; + + /** + * The size required for the zero-terminated attributes list, for the current context. + **/ public static final int ALC_ATTRIBUTES_SIZE = 0x1002; + + /** + * Expects a destination of ALC_CURRENT_ATTRIBUTES_SIZE, + * and provides the attribute list for the current context of the specified device. + */ public static final int ALC_ALL_ATTRIBUTES = 0x1003; + /** The specifier string for the default device */ public static final int ALC_DEFAULT_DEVICE_SPECIFIER = 0x1004; + + /** The specifier string for the device */ public static final int ALC_DEVICE_SPECIFIER = 0x1005; + + /** The extensions string for diagnostics and printing */ public static final int ALC_EXTENSIONS = 0x1006; + /** Frequency for mixing output buffer, in units of Hz. */ public static final int ALC_FREQUENCY = 0x1007; + + /** Refresh intervalls, in units of Hz. */ public static final int ALC_REFRESH = 0x1008; + + /** Flag, indicating a synchronous context. */ public static final int ALC_SYNC = 0x1009; /** The device argument does not name a valid device */ @@ -158,8 +200,16 @@ public class ALC { protected static native void nDestroy(); /** - * Returns strings related to the context. + * The application can obtain certain strings from ALC. + * + * ALC_DEFAULT_DEVICE_SPECIFIER - The specifer string for the default device + * ALC_DEVICE_SPECIFIER - The specifer string for the device + * ALC_EXTENSIONS - The extensions string for diagnostics and printing. * + * In addition, printable error message strings are provided for all valid error tokens, + * including ALC_NO_ERROR,ALC_INVALID_DEVICE, ALC_INVALID_CONTEXT, + * ALC_INVALID_ENUM, ALC_INVALID_VALUE. + * * @param pname Property to get * @return String property from device */ @@ -170,7 +220,21 @@ public class ALC { native static String nGetString(int device, int pname); /** - * Returns integers related to the context. + * The application can query ALC for information using an integer query function. + * For some tokens, null is a legal deviceHandle. In other cases, specifying a null + * device will generate an ALC_INVALID_DEVICE error. The application has to + * specify the size of the destination buffer provided. A null destination or a zero + * size parameter will cause ALC to ignore the query. + * + * ALC_MAJOR_VERSION - Major version query. + * ALC_MINOR_VERSION - Minor version query. + * ALC_ATTRIBUTES_SIZE - The size required for the zero-terminated attributes list, + * for the current context. null is an invalid device. null (no current context + * for the specified device) is legal. + * ALC_ALL_ATTRIBUTES - Expects a destination of ALC_CURRENT_ATTRIBUTES_SIZE, + * and provides the attribute list for the current context of the specified device. + * null is an invalid device. null (no current context for the specified device) + * will return the default attributes defined by the specified device. * * @param pname Property to get * @param size Size of destination buffer provided @@ -183,8 +247,13 @@ public class ALC { native static void nGetIntegerv(int device, int pname, int size, Buffer integerdata); /** - * Opens the named device. If null is specied, the implementation will - * provide an implementation specic default. + * The alcOpenDevice function allows the application (i.e. the client program) to + * connect to a device (i.e. the server). + * + * If the function returns null, then no sound driver/device has been found. The + * argument is a null terminated string that requests a certain device or device + * configuration. If null is specified, the implementation will provide an + * implementation specific default. * * @param devicename name of device to open * @return opened device, or null @@ -192,14 +261,26 @@ public class ALC { native static ALCdevice alcOpenDevice(String devicename); /** - * Closes the supplied device. + * The alcCloseDevice function allows the application (i.e. the client program) to + * disconnect from a device (i.e. the server). + * + * If deviceHandle is null or invalid, an ALC_INVALID_DEVICE error will be + * generated. Once closed, a deviceHandle is invalid. * * @param device address of native device to close */ native static void alcCloseDevice(int device); /** - * Creates a context using a specified device. + * A context is created using alcCreateContext. The device parameter has to be a valid + * device. The attribute list can be null, or a zero terminated list of integer pairs + * composed of valid ALC attribute tokens and requested values. + * + * Context creation will fail if the application requests attributes that, by themselves, + * can not be provided. Context creation will fail if the combination of specified + * attributes can not be provided. Context creation will fail if a specified attribute, or + * the combination of attributes, does not match the default values for unspecified + * attributes. * * @param device address of device to associate context to * @param attrList Buffer to read attributes from @@ -208,7 +289,15 @@ public class ALC { native static ALCcontext alcCreateContext(int device, Buffer attrList); /** - * Makes the supplied context the current one + * To make a Context current with respect to AL Operation (state changes by issueing + * commands), alcMakeContextCurrent is used. The context parameter can be null + * or a valid context pointer. The operation will apply to the device that the context + * was created for. + * + * For each OS process (usually this means for each application), only one context can + * be current at any given time. All AL commands apply to the current context. + * Commands that affect objects shared among contexts (e.g. buffers) have side effects + * on other contexts. * * @param context address of context to make current * @return true if successfull, false if not @@ -216,7 +305,15 @@ public class ALC { native static boolean alcMakeContextCurrent(int context); /** - * Tells a context to begin processing. + * The current context is the only context accessible to state changes by AL commands + * (aside from state changes affecting shared objects). However, multiple contexts can + * be processed at the same time. To indicate that a context should be processed (i.e. + * that internal execution state like offset increments are supposed to be performed), + * the application has to use alcProcessContext. + * + * Repeated calls to alcProcessContext are legal, and do not affect a context that is + * already marked as processing. The default state of a context created by + * alcCreateContext is that it is not marked as processing. */ public static void alcProcessContext() { nProcessContext(AL.context.context); @@ -225,14 +322,15 @@ public class ALC { native static void nProcessContext(int context); /** - * Gets the current context + * The application can query for, and obtain an handle to, the current context for the + * application. If there is no current context, null is returned. * * @return Current ALCcontext */ native static ALCcontext alcGetCurrentContext(); /** - * Retrives the device associated with the supplied context + * The application can query for, and obtain an handle to, the device of a given context. * * @param context address of context to get device for * @param ALCdevice associated with context @@ -240,21 +338,39 @@ public class ALC { native static ALCdevice alcGetContextsDevice(int context); /** - * Suspends processing on supplied context + * The application can suspend any context from processing (including the current + * one). To indicate that a context should be suspended from processing (i.e. that + * internal execution state like offset increments is not supposed to be changed), the + * application has to use alcSuspendContext. + * + * Repeated calls to alcSuspendContext are legal, and do not affect a context that is + * already marked as suspended. The default state of a context created by + * alcCreateContext is that it is marked as suspended. * * @param context address of context to suspend */ native static void alcSuspendContext(int context); /** - * Destroys supplied context + * The correct way to destroy a context is to first release it using alcMakeCurrent and + * null. Applications should not attempt to destroy a current context. * * @param context address of context to Destroy */ native static void alcDestroyContext(int context); /** - * Retrieves the current context error state. + * ALC uses the same conventions and mechanisms as AL for error handling. In + * particular, ALC does not use conventions derived from X11 (GLX) or Windows + * (WGL). The alcGetError function can be used to query ALC errors. + * + * Error conditions are specific to the device. + * + * ALC_NO_ERROR - The device handle or specifier does name an accessible driver/server. + * ALC_INVALID_DEVICE - The Context argument does not name a valid context. + * ALC_INVALID_CONTEXT - The Context argument does not name a valid context. + * ALC_INVALID_ENUM - A token used is not valid, or not applicable. + * ALC_INVALID_VALUE - An value (e.g. attribute) is not valid, or not applicable. * * @return Errorcode from ALC statemachine */ @@ -265,7 +381,10 @@ public class ALC { native static int nGetError(int device); /** - * Query if a specified context extension is available. + * Verify that a given extension is available for the current context and the device it + * is associated with. + * A null name argument returns ALC_FALSE, as do invalid and unsupported string + * tokens. * * @param extName name of extension to find * @return true if extension is available, false if not @@ -277,7 +396,11 @@ public class ALC { native static boolean nIsExtensionPresent(int device, String extName); /** - * retrieves the enum value for a specified enumeration name. + * Enumeration/token values are device independend, but tokens defined for + * extensions might not be present for a given device. But only the tokens defined + * by the AL core are guaranteed. Availability of extension tokens dependends on the ALC extension. + * + * Specifying a null name parameter will cause an ALC_INVALID_VALUE error. * * @param enumName name of enum to find * @return value of enumeration diff --git a/src/java/org/lwjgl/openal/ALCcontext.java b/src/java/org/lwjgl/openal/ALCcontext.java index 45ba1cf1..af2207e3 100644 --- a/src/java/org/lwjgl/openal/ALCcontext.java +++ b/src/java/org/lwjgl/openal/ALCcontext.java @@ -37,7 +37,7 @@ import java.nio.ByteOrder; /** * $Id$ - * + *
* Wrapper class, to make ALC contexts behave like the orginal api. * * @author Brian Matzon diff --git a/src/java/org/lwjgl/openal/ALCdevice.java b/src/java/org/lwjgl/openal/ALCdevice.java index 786c680f..a74e3338 100644 --- a/src/java/org/lwjgl/openal/ALCdevice.java +++ b/src/java/org/lwjgl/openal/ALCdevice.java @@ -33,7 +33,7 @@ package org.lwjgl.openal; /** * $Id$ - * + *
* Wrapper class, to make ALC devices behave like the orginal api. * * @author Brian Matzon diff --git a/src/java/org/lwjgl/openal/ALConstants.java b/src/java/org/lwjgl/openal/ALConstants.java index 37c0b690..75ca670c 100644 --- a/src/java/org/lwjgl/openal/ALConstants.java +++ b/src/java/org/lwjgl/openal/ALConstants.java @@ -33,7 +33,7 @@ package org.lwjgl.openal; /** * $Id$ - * + *
* This class contains all OpenAL constants, including extensions. * * @author Brian Matzon diff --git a/src/java/org/lwjgl/openal/BaseAL.java b/src/java/org/lwjgl/openal/BaseAL.java index 77c11985..31e918c8 100644 --- a/src/java/org/lwjgl/openal/BaseAL.java +++ b/src/java/org/lwjgl/openal/BaseAL.java @@ -39,7 +39,7 @@ import org.lwjgl.Sys; /** * $Id$ - * + *
* The base AL functionality (no actual AL methods). * * This has been provided as a base class that we can use for either the diff --git a/src/java/org/lwjgl/openal/BaseALConstants.java b/src/java/org/lwjgl/openal/BaseALConstants.java index 3b39a944..5175ffaf 100644 --- a/src/java/org/lwjgl/openal/BaseALConstants.java +++ b/src/java/org/lwjgl/openal/BaseALConstants.java @@ -33,7 +33,7 @@ package org.lwjgl.openal; /** * $Id$ - * + *
* This class implements all basic OpenAL constants. * * @author Brian Matzon diff --git a/src/java/org/lwjgl/openal/CoreAL.java b/src/java/org/lwjgl/openal/CoreAL.java index 67233ce6..739aae3a 100644 --- a/src/java/org/lwjgl/openal/CoreAL.java +++ b/src/java/org/lwjgl/openal/CoreAL.java @@ -39,7 +39,7 @@ import java.nio.DoubleBuffer; /** * $Id$ - * + *
* This is the core OpenAL class. This class implements * AL.h version 1.0 * @@ -49,21 +49,33 @@ import java.nio.DoubleBuffer; public abstract class CoreAL extends BaseAL implements BaseALConstants { /** - * Enables a feature of the OpenAL driver. + * 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. * * @param capability name of a capability to enable */ public static native void alEnable(int capability); /** - * Disables a feature of the OpenAL driver. + * 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. * * @param capability name of a capability to disable */ public static native void alDisable(int capability); /** - * Checks if a specific feature is enabled in the OpenAL driver. + * 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. + *

* * @param capability name of a capability to check * @return true if named feature is enabled @@ -74,41 +86,81 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { * Hinting for implementation * NOTE: This method is a NOP, but is provided for completeness. * - * @param target FIXME - * @param mode FIXME + * @param target The target to hint + * @param mode Mode to hint */ public static native void alHint(int target, int mode); /** - * Returns a boolean OpenAL state. + * 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. + *

* * @return boolean state described by pname will be returned. */ public static native boolean alGetBoolean(int pname); /** - * Returns an int OpenAL state. + * 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. + *

* * @return int state described by pname will be returned. */ public static native int alGetInteger(int pname); /** - * Returns a float OpenAL state. + * 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. + *

* * @return float state described by pname will be returned. */ public static native float alGetFloat(int pname); /** - * Returns a double OpenAL state. + * 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. + *

* * @return double state described by pname will be returned. */ public static native double alGetDouble(int pname); /** - * Returns a boolean OpenAL state. + * 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. + *

* * @param pname state to be queried * @param data Buffer to place the booleans in @@ -116,7 +168,15 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetBooleanv(int pname, ByteBuffer data); /** - * Returns an integer OpenAL state. + * 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. + *

* * @param pname state to be queried * @param data Buffer to place the integers in @@ -124,7 +184,15 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetIntegerv(int pname, IntBuffer data); /** - * Returns a floating point OpenAL state. + * 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. + *

* * @param pname state to be queried * @param data Buffer to place the floats in @@ -132,15 +200,27 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetFloatv(int pname, FloatBuffer data); /** - * Returns a double OpenAL state. - * - * @param pname state to be queried - * @param data Buffer to place the floats in - */ + * 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. + *

+ * + * @param pname state to be queried + * @param data Buffer to place the floats in + */ public static native void alGetDoublev(int pname, DoubleBuffer data); /** - * Retrieve an OpenAL string property. + * 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. * * @param pname The property to be returned * @return OpenAL String property @@ -148,14 +228,91 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native String alGetString(int pname); /** - * Retrieve the current error state and then clears the error state. + * 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. + *

* * @return current error state */ public static native int alGetError(); /** - * Test if a specific extension is available for the OpenAL driver. + * 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. + *

* * @param fname String describing the desired extension * @return true if extension is available, false if not @@ -163,7 +320,19 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native boolean alIsExtensionPresent(String fname); /** - * Returns the enumeration value of an OpenAL enum described by a string. + *

+ * 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. + *

* * @param ename String describing an OpenAL enum * @return Actual int for the described enumeration name @@ -171,7 +340,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native int alGetEnumValue(String ename); /** - * Sets an integer property of the listener + * Listener attributes are changed using the Listener group of commands. * * @param pname name of the attribute to be set * @param value value to set the attribute to @@ -179,7 +348,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alListeneri(int pname, int value); /** - * Sets a floating point property of the listener + * Listener attributes are changed using the Listener group of commands. * * @param pname name of the attribute to be set * @param value floating point value to set the attribute to @@ -187,7 +356,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alListenerf(int pname, float value); /** - * Sets a floating point property of the listener + * Listener attributes are changed using the Listener group of commands. * * @param pname name of the attribute to be set * @param v1 value value 1 @@ -198,7 +367,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { /** - * Sets a floating point vector property of the listener + * Listener attributes are changed using the Listener group of commands. * * @param pname name of the attribute to be set * @param floatdata Buffer to read floats from @@ -206,7 +375,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alListenerfv(int pname, FloatBuffer floatdata); /** - * Gets an integer property of the listener. + * Listener state is maintained inside the AL implementation and can be queried in + * full. * * @param pname name of the attribute to be retrieved * @param integerdata Buffer to write integer to @@ -214,7 +384,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetListeneri(int pname, IntBuffer integerdata); /** - * Gets a floating point property of the listener. + * Listener state is maintained inside the AL implementation and can be queried in + * full. * * @param pname name of the attribute to be retrieved * @param floatdata Buffer to write float to @@ -222,7 +393,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetListenerf(int pname, FloatBuffer floatdata); /** - * Retrieves a floating point vector property of the listener. + * Listener state is maintained inside the AL implementation and can be queried in + * full. * * @param pname name of the attribute to be retrieved * @param floatdata Buffer to write floats to @@ -230,7 +402,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetListenerfv(int pname, FloatBuffer floatdata); /** - * Generate one or more sources. + * The application requests a number of Sources using GenSources. * * @param n number of sources to generate * @param sources array holding sources @@ -238,7 +410,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGenSources(int n, IntBuffer sources); /** - * Delete one or more sources. + * The application requests deletion of a number of Sources by DeleteSources. * * @param n Number of sources to delete * @param source Source array to delete from @@ -246,7 +418,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alDeleteSources(int n, IntBuffer source); /** - * Tests if a source is valid. + * The application can verify whether a source name is valid using the IsSource query. * * @param id id of source to be testes for validity * @return true if id is valid, false if not @@ -254,7 +426,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native boolean alIsSource(int id); /** - * Set an integer property of a source. + * Specifies the position and other properties as taken into account during + * sound processing. * * @param source Source to det property on * @param pname property to set @@ -263,7 +436,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourcei(int source, int pname, int value); /** - * Set a floating point property of a source. + * Specifies the position and other properties as taken into account during + * sound processing. * * @param source Source to det property on * @param pname property to set @@ -272,7 +446,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourcef(int source, int pname, float value); /** - * Sets a source property requiring three floating point values. + * Specifies the position and other properties as taken into account during + * sound processing. * * @param source Source to set property on * @param pname property to set @@ -289,7 +464,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { /** - * Sets a floating point vector property of a source. + * Specifies the position and other properties as taken into account during + * sound processing. * * @param source source whichs attribute is being set * @param pname name of the attribute being set @@ -298,7 +474,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourcefv(int source, int pname, FloatBuffer floatdata); /** - * Retrieves an integer property of a source. + * 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. * * @param source source to get property from * @param pname name of property @@ -307,7 +485,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetSourcei(int source, int pname, IntBuffer integerdata); /** - * Retrieves a floating point property of a source. + * 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. * * @param source source to get property from * @param pname name of property @@ -316,7 +496,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetSourcef(int source, int pname, FloatBuffer floatdata); /** - * Gets a floating point vector property from a Source object. + * 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. * * @param source Source to get property from * @param pname property to get @@ -325,7 +507,14 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetSourcefv(int source, int pname, FloatBuffer floatdata); /** - * Plays a set of 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. * * @param n number of sources to play * @param sources array of sources to play @@ -333,7 +522,10 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourcePlayv(int n, IntBuffer sources); /** - * Pauses a set of 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. * * @param n number of sources to pause * @param sources array of sources to pause @@ -341,7 +533,11 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourcePausev(int n, IntBuffer sources); /** - * Stops a set of 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. * * @param n number of sources to stop * @param sources array of sources to stop @@ -349,7 +545,13 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourceStopv(int n, IntBuffer sources); /** - * Rewinds a set of 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. * * @param n number of sources to rewind * @param sources array of sources to rewind @@ -357,35 +559,55 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourceRewindv(int n, IntBuffer sources); /** - * Play a 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. * * @param source Source to play */ public static native void alSourcePlay(int source); /** - * Pauses a 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. * * @param source Source to pause */ public static native void alSourcePause(int source); /** - * Stops a 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. * * @param source Source to stop */ public static native void alSourceStop(int source); /** - * Rewinds a 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. * * @param source Source to rewind */ public static native void alSourceRewind(int source); /** - * Generate one or more buffers. + * The application requests a number of Buffers using GenBuffers. * * @param n number of buffers to generate * @param buffers holding buffers @@ -393,7 +615,18 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGenBuffers(int n, IntBuffer buffers); /** - * Delete one or more 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. * * @param n Number of buffers to delete * @param buffers Buffer to delete from @@ -401,7 +634,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alDeleteBuffers(int n, IntBuffer buffers); /** - * Tests if buffer is valid. + * The application can verify whether a buffer Name is valid using the IsBuffer query. * * @param buffer buffer to be tested for validity * @return true if supplied buffer is valid, false if not @@ -409,7 +642,26 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native boolean alIsBuffer(int buffer); /** - * Fill a buffer with audio data. + *

+ * 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. + *

* * @param buffer Buffer to fill * @param format format sound data is in @@ -425,7 +677,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { int freq); /** - * Retrieves an integer property from a buffer. + * 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.
* * @param buffer buffer to get property from * @param pname name of property to retrieve @@ -434,7 +688,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetBufferi(int buffer, int pname, IntBuffer integerdata); /** - * Retrieves a floating point property from a buffer. + * 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.
* * @param buffer buffer to get property from * @param pname name of property to retrieve @@ -443,7 +699,16 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alGetBufferf(int buffer, int pname, FloatBuffer floatdata); /** - * Queues a set of buffers on a source. + *

+ * 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. + *

* * @param source source to queue buffers onto * @param n number of buffers to be queued @@ -452,7 +717,20 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourceQueueBuffers(int source, int n, IntBuffer buffers); /** - * Unqueues a set of buffers attached to a source. + *

+ * 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 nished + * 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. + *

* * @param source source to unqueue buffers from * @param n number of buffers to be unqueued @@ -461,22 +739,160 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants { public static native void alSourceUnqueueBuffers(int source, int n, IntBuffer buffers); /** - * Selects the OpenAL distance model. + *

+ * 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. + *

* * @param value distance model to be set */ public static native void alDistanceModel(int value); /** - * Selects the OpenAL Doppler factor 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. + *

* * @param value Doppler scale value to set */ public static native void alDopplerFactor(float value); /** - * Selects the OpenAL Doppler velocity 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. + *

+ * * @param value Doppler velocity value to set */ public static native void alDopplerVelocity(float value); diff --git a/src/java/org/lwjgl/openal/OpenALException.java b/src/java/org/lwjgl/openal/OpenALException.java index 570a606a..11534b1d 100644 --- a/src/java/org/lwjgl/openal/OpenALException.java +++ b/src/java/org/lwjgl/openal/OpenALException.java @@ -33,7 +33,7 @@ package org.lwjgl.openal; /** * $Id$ - * + *
* Thrown by the debug build library of the LWJGL if any OpenAL operation * causes an error. *