shadowfacts/lwjgl2-arm64
1
0
Fork 0
mirror of https://github.com/shadowfacts/lwjgl2-arm64.git synced 2026-04-04 14:07:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added OpenAL specification to javadoc

Browse source
This commit is contained in:
Brian Matzon 2003-08-03 17:32:48 +00:00
parent f7ce5c39ed
commit cd85805588
9 changed files with 621 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/java/org/lwjgl/openal/AL.java
View file

@ -33,7 +33,7 @@ package org.lwjgl.openal;
/**
* $Id$
*
* <br>
* This is the OpenAL class. It extends the latest core.
*
* @author Brian Matzon <brian@matzon.dk>

155
src/java/org/lwjgl/openal/ALC.java
View file

@ -35,9 +35,29 @@ import java.nio.Buffer;
/**
* $Id$
*
*
* <p>
* This is the context class for OpenAL. This class implements functions
* in alc.h
* </p>
*
* <p>
* 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).
* </p>
*
* <p>
* <b>NOTE:</b><br>
* The LWJGL implementation of OpenAL does not expose the device, nor the context.
* Whenever <code>AL</code> is created using the <code>create</code> 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.
* </p>
*
* @author Brian Matzon <brian@matzon.dk>
* @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.
*
* <code>ALC_DEFAULT_DEVICE_SPECIFIER</code> - The specifer string for the default device
* <code>ALC_DEVICE_SPECIFIER</code> - The specifer string for the device
* <code>ALC_EXTENSIONS</code> - The extensions string for diagnostics and printing.
*
* In addition, printable error message strings are provided for all valid error tokens,
* including <code>ALC_NO_ERROR</code>,<code>ALC_INVALID_DEVICE</code>, <code>ALC_INVALID_CONTEXT</code>,
* <code>ALC_INVALID_ENUM</code>, <code>ALC_INVALID_VALUE</code>.
*
* @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, <code>null</code> is a legal deviceHandle. In other cases, specifying a <code>null</code>
* device will generate an <code>ALC_INVALID_DEVICE</code> error. The application has to
* specify the size of the destination buffer provided. A <code>null</code> destination or a zero
* size parameter will cause ALC to ignore the query.
*
* <code>ALC_MAJOR_VERSION</code> - Major version query.
* <code>ALC_MINOR_VERSION</code> - Minor version query.
* <code>ALC_ATTRIBUTES_SIZE</code> - The size required for the zero-terminated attributes list,
* for the current context. <code>null</code> is an invalid device. <code>null</code> (no current context
* for the specified device) is legal.
* <code>ALC_ALL_ATTRIBUTES</code> - Expects a destination of <code>ALC_CURRENT_ATTRIBUTES_SIZE</code>,
* and provides the attribute list for the current context of the specified device.
* <code>null</code> is an invalid device. <code>null</code> (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 <code>alcOpenDevice</code> function allows the application (i.e. the client program) to
* connect to a device (i.e. the server).
*
* If the function returns <code>null</code>, then no sound driver/device has been found. The
* argument is a null terminated string that requests a certain device or device
* configuration. If <code>null</code> 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 <code>alcCloseDevice</code> function allows the application (i.e. the client program) to
* disconnect from a device (i.e. the server).
*
* If deviceHandle is <code>null</code> or invalid, an <code>ALC_INVALID_DEVICE</code> 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 <code>alcCreateContext</code>. The device parameter has to be a valid
* device. The attribute list can be <code>null</code>, 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), <code>alcMakeContextCurrent</code> is used. The context parameter can be <code>null</code>
* 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 <code>alcProcessContext</code>.
*
* Repeated calls to <code>alcProcessContext</code> 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, <code>null</code> 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 <code>alcSuspendContext</code>.
*
* Repeated calls to <code>alcSuspendContext</code> are legal, and do not affect a context that is
* already marked as suspended. The default state of a context created by
* <code>alcCreateContext</code> 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 <code>alcMakeCurrent</code> and
* <code>null</code>. 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 <code>alcGetError</code> 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.
* <code>ALC_INVALID_DEVICE</code> - The Context argument does not name a valid context.
* <code>ALC_INVALID_CONTEXT</code> - The Context argument does not name a valid context.
* <code>ALC_INVALID_ENUM</code> - A token used is not valid, or not applicable.
* <code>ALC_INVALID_VALUE</code> - 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 <code>null</code> name argument returns <code>ALC_FALSE</code>, 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 <code>null</code> name parameter will cause an <code>ALC_INVALID_VALUE</code> error.
*
* @param enumName name of enum to find
* @return value of enumeration

2
src/java/org/lwjgl/openal/ALCcontext.java
View file

@ -37,7 +37,7 @@ import java.nio.ByteOrder;
/**
* $Id$
*
* <br>
* Wrapper class, to make ALC contexts behave like the orginal api.
*
* @author Brian Matzon <brian@matzon.dk>

2
src/java/org/lwjgl/openal/ALCdevice.java
View file

@ -33,7 +33,7 @@ package org.lwjgl.openal;
/**
* $Id$
*
* <br>
* Wrapper class, to make ALC devices behave like the orginal api.
*
* @author Brian Matzon <brian@matzon.dk>

2
src/java/org/lwjgl/openal/ALConstants.java
View file

@ -33,7 +33,7 @@ package org.lwjgl.openal;
/**
* $Id$
*
* <br>
* This class contains all OpenAL constants, including extensions.
*
* @author Brian Matzon <brian@matzon.dk>

2
src/java/org/lwjgl/openal/BaseAL.java
View file

@ -39,7 +39,7 @@ import org.lwjgl.Sys;
/**
* $Id$
*
* <br>
* The base AL functionality (no actual AL methods).
*
* This has been provided as a base class that we can use for either the

2
src/java/org/lwjgl/openal/BaseALConstants.java
View file

@ -33,7 +33,7 @@ package org.lwjgl.openal;
/**
* $Id$
*
* <br>
* This class implements all basic OpenAL constants.
*
* @author Brian Matzon <brian@matzon.dk>

534
src/java/org/lwjgl/openal/CoreAL.java
View file

@ -39,7 +39,7 @@ import java.nio.DoubleBuffer;
/**
* $Id$
*
* <br>
* 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.
* <p>
* If the token used to specify target is not legal, an AL_INVALID_ENUM error will be
* generated.
* </p>
* <p>
* At this time, this mechanism is not used. There are no valid targets.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* <code>null</code> 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.
* </p>
*
* @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.
* <p>
* 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).
* </p>
* <p>
* 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.
* </p>
* <p>
* AL_NO_ERROR - "No Error" token.<br>
* AL_INVALID_NAME - Invalid Name parameter.<br>
* AL_INVALID_ENUM - Invalid parameter.<br>
* AL_INVALID_VALUE - Invalid enum parameter value.<br>
* AL_INVALID_OPERATION - Illegal call.<br>
* AL_OUT_OF_MEMORY - Unable to allocate memory.<br>
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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).
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* Otherwise errors are generated only for conditions that are explicitely described in
* this specification.
* </p>
*
* @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.
* <p>
* A <code>null</code> name argument returns AL_FALSE, as do invalid and unsupported string
* tokens. A <code>null</code> deviceHandle will result in an INVALID_DEVICE error.
* </p>
*
* @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.
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
*
* @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.
* <p>
* The application requests deletion of a number of Buffers by calling DeleteBuffers.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
*
* @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.<br>
* ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].<br>
* ALC_SIZE - Size in bytes of the buffer data.<br>
*
* @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.<br>
* ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].<br>
* ALC_SIZE - Size in bytes of the buffer data.<br>
*
* @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.
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
*
* @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.
* <p>
* 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).
* </p>
* <p>
* 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.
* </p>
*
* @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.
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* Legal arguments are AL_NONE, AL_INVERSE_DISTANCE, and
* AL_INVERSE_DISTANCE_CLAMPED.
* <br>
* <br>
* AL_NONE bypasses all distance attenuation
* calculation for all Sources. The implementation is expected to optimize this
* situation.
* <br>
* <br>
* 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.
* <br>
* <br>
* AL_INVERSE_DISTANCE is equivalent to the DS3D
* model with the exception that AL_REFERENCE_DISTANCE does not imply any
* clamping.
* <br>
* <br>
* 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.
* </p>
*
* @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.
* <br>
* <br>
* 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.
*
* <p>
* <pre>
* 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
* </pre>
* </p>
* <p>
* 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.
* </p>
* <p>
* There are two API calls global to the current context that provide control of the two
* related parameters.
* </p>
* <p>
* AL_DOPPLER_FACTOR is a simple scaling to exaggerate or
* deemphasize the Doppler (pitch) shift resulting from the calculation.
* </p>
* <p>
* 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.
* </p>
*
* @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.
* <br>
* <br>
* 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.
*
* <p>
* <pre>
* 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
* </pre>
* </p>
* <p>
* 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.
* </p>
* <p>
* There are two API calls global to the current context that provide control of the two
* related parameters.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
*
* @param value Doppler velocity value to set
*/
public static native void alDopplerVelocity(float value);

2
src/java/org/lwjgl/openal/OpenALException.java
View file

@ -33,7 +33,7 @@ package org.lwjgl.openal;
/**
* $Id$
*
* <br>
* Thrown by the debug build library of the LWJGL if any OpenAL operation
* causes an error.
*