diff --git a/src/java/org/lwjgl/Display.java b/src/java/org/lwjgl/Display.java index 9f155009..5ace57a8 100644 --- a/src/java/org/lwjgl/Display.java +++ b/src/java/org/lwjgl/Display.java @@ -196,8 +196,10 @@ public final class Display { * @param contrast The contrast, larger than 0.0. */ public static void setDisplayConfiguration(float gamma, float brightness, float contrast) throws Exception { - assert brightness >= -1.0f && brightness <= 1.0f; - assert contrast >= 0.0f; + if (brightness < -1.0f || brightness > 1.0f) + throw new IllegalArgumentException("Invalid brightness value"); + if (contrast < 0.0f) + throw new IllegalArgumentException("Invalid contrast value"); int rampSize = getGammaRampLength(); if (rampSize == 0) { throw new Exception("Display configuration not supported"); diff --git a/src/java/org/lwjgl/input/Controller.java b/src/java/org/lwjgl/input/Controller.java index 9635a142..8d5c4af7 100644 --- a/src/java/org/lwjgl/input/Controller.java +++ b/src/java/org/lwjgl/input/Controller.java @@ -164,9 +164,8 @@ public class Controller { * @throws Exception if the controller could not be created for any reason */ public static void create() throws Exception { - - assert Window.isCreated() : "Window must be created prior to creating controller"; - + if (!Window.isCreated()) + throw new IllegalStateException("Window must be created before you can create Controller"); if (!initialized) { initialize(); } @@ -203,7 +202,8 @@ public class Controller { * Polls the controller. */ public static void poll() { - assert created : "The controller has not been created."; + if (!created) + throw new IllegalStateException("Controller must be created before you can poll the device"); nPoll(); } @@ -215,7 +215,8 @@ public class Controller { * @see #buttonCount */ public static boolean isButtonDown(int button) { - assert created : "The controller has not been created."; + if (!created) + throw new IllegalStateException("Controller must be created before you can query button state"); return buttons[button]; } @@ -231,7 +232,7 @@ public class Controller { * it always throws a RuntimeException. */ public static void read() { - throw new RuntimeException("Buffering is not implemented for Controllers."); + throw new UnsupportedOperationException("Buffering is not implemented for Controllers."); } /** diff --git a/src/java/org/lwjgl/input/Cursor.java b/src/java/org/lwjgl/input/Cursor.java index c2714616..5977ef2d 100644 --- a/src/java/org/lwjgl/input/Cursor.java +++ b/src/java/org/lwjgl/input/Cursor.java @@ -50,185 +50,190 @@ import org.lwjgl.Sys; public class Cursor { - /** Lazy initialization */ - private static boolean initialized = false; - - /** First element to display */ - private CursorElement[] cursors = null; - - /** Index into list of cursors */ - private int index = -1; - - /** - * Constructs a new Cursor, with the given parameters. Mouse must have been created before you can create - * Cursor objects. Cursor images are in ARGB format, but only one bit transparancy is guaranteed to be supported. - * So to maximize portability, lwjgl applications should only create cursor images with 0x00 or 0xff as alpha values. - * The constructor will copy the images and delays, so there's no need to keep them around. - * - * @param width cursor image width - * @param height cursor image height - * @param xHotspot the x coordinate of the cursor hotspot - * @param yHotspot the y coordinate of the cursor hotspot - * @param numImages number of cursor images specified. Must be 1 if animations are not supported. - * @param images A buffer containing the images. The origin is at the lower left corner, like OpenGL. - * @param delays An int buffer of animation frame delays, if numImages is greater than 1, else null - * @throws Exception if the cursor could not be created for any reason - */ - public Cursor(int width, int height, int xHotspot, int yHotspot, int numImages, IntBuffer images, IntBuffer delays) throws Exception { - assert Mouse.isCreated(); - assert width*height*numImages <= images.remaining() : "width*height*numImages > images.remaining()"; - assert delays == null || numImages <= delays.remaining() : "delays != null && numImages > delays.remaining()"; - assert xHotspot < width && xHotspot >= 0 : "xHotspot > width || xHotspot < 0"; - assert yHotspot < height && yHotspot >= 0 : "yHotspot > height || yHotspot < 0"; - - // initialize - if (!initialized) { - initialize(); - } - - // Hmm - yHotspot = height - 1 - yHotspot; - - // create cursor (or cursors if multiple images supplied) - createCursors(width, height, xHotspot, yHotspot, numImages, images, delays); - } - - /** - * Initializes the cursor class - */ - private static void initialize() { - System.loadLibrary(Sys.getLibraryName()); - initialized = true; - } + /** Lazy initialization */ + private static boolean initialized = false; + + /** First element to display */ + private CursorElement[] cursors = null; + + /** Index into list of cursors */ + private int index = -1; + + /** + * Constructs a new Cursor, with the given parameters. Mouse must have been created before you can create + * Cursor objects. Cursor images are in ARGB format, but only one bit transparancy is guaranteed to be supported. + * So to maximize portability, lwjgl applications should only create cursor images with 0x00 or 0xff as alpha values. + * The constructor will copy the images and delays, so there's no need to keep them around. + * + * @param width cursor image width + * @param height cursor image height + * @param xHotspot the x coordinate of the cursor hotspot + * @param yHotspot the y coordinate of the cursor hotspot + * @param numImages number of cursor images specified. Must be 1 if animations are not supported. + * @param images A buffer containing the images. The origin is at the lower left corner, like OpenGL. + * @param delays An int buffer of animation frame delays, if numImages is greater than 1, else null + * @throws Exception if the cursor could not be created for any reason + */ + public Cursor(int width, int height, int xHotspot, int yHotspot, int numImages, IntBuffer images, IntBuffer delays) throws Exception { + if (!Mouse.isCreated()) + throw new IllegalStateException("Mouse must be created before creating cursor objects"); + if (width*height*numImages > images.remaining()) + throw new IllegalArgumentException("width*height*numImages > images.remaining()"); + if (delays != null && numImages > delays.remaining()) + throw new IllegalArgumentException("delays != null && numImages > delays.remaining()"); + if (xHotspot >= width || xHotspot < 0) + throw new IllegalArgumentException("xHotspot > width || xHotspot < 0"); + if (yHotspot >= height || yHotspot < 0) + throw new IllegalArgumentException("yHotspot > height || yHotspot < 0"); + + // initialize + if (!initialized) { + initialize(); + } + + // Hmm + yHotspot = height - 1 - yHotspot; + + // create cursor (or cursors if multiple images supplied) + createCursors(width, height, xHotspot, yHotspot, numImages, images, delays); + } + + /** + * Initializes the cursor class + */ + private static void initialize() { + System.loadLibrary(Sys.getLibraryName()); + initialized = true; + } - /** - * Creates the actual cursor, using a platform specific class - */ - private void createCursors(int width, int height, int xHotspot, int yHotspot, int numImages, IntBuffer images, IntBuffer delays) throws Exception { - // create copy and flip images to match ogl - IntBuffer images_copy = ByteBuffer.allocateDirect(images.remaining()*4).order(ByteOrder.nativeOrder()).asIntBuffer(); - flipImages(width, height, numImages, images, images_copy); - - // create our cursor elements - cursors = new CursorElement[numImages]; - for(int i=0; i>1; y++) { - int index_y_1 = y*width + start_index; - int index_y_2 = (height - y - 1)*width + start_index; - for (int x = 0; x < width; x++) { - int index1 = index_y_1 + x; - int index2 = index_y_2 + x; - int temp_pixel = images.get(index1 + images.position()); - images_copy.put(index1, images.get(index2 + images.position())); - images_copy.put(index2, temp_pixel); - } - } - } - - /** - * Gets the native handle associated with the cursor object. - */ - public long getHandle() { - return cursors[index].cursorHandle; - } - - /** - * Destroy the native cursor. Cursor must not be current. - */ - public void destroy() { + /** + * @param width Width of image + * @param height Height of images + * @param start_index index into source buffer to copy to + * @param images Source images + * @param images_copy Destination images + */ + private static void flipImage(int width, int height, int start_index, IntBuffer images, IntBuffer images_copy) { + for (int y = 0; y < height>>1; y++) { + int index_y_1 = y*width + start_index; + int index_y_2 = (height - y - 1)*width + start_index; + for (int x = 0; x < width; x++) { + int index1 = index_y_1 + x; + int index2 = index_y_2 + x; + int temp_pixel = images.get(index1 + images.position()); + images_copy.put(index1, images.get(index2 + images.position())); + images_copy.put(index2, temp_pixel); + } + } + } + + /** + * Gets the native handle associated with the cursor object. + */ + public long getHandle() { + return cursors[index].cursorHandle; + } + + /** + * Destroy the native cursor. Cursor must not be current. + */ + public void destroy() { for(int i=0; i 1 && cursors[index].timeout < System.currentTimeMillis(); - } + /** + * Determines whether this cursor has timed out + * @return true if the this cursor has timed out, false if not + */ + protected boolean hasTimedOut() { + return cursors.length > 1 && cursors[index].timeout < System.currentTimeMillis(); + } - /** - * Changes to the next cursor - */ - protected void nextCursor() { - index = ++index % cursors.length; - } + /** + * Changes to the next cursor + */ + protected void nextCursor() { + index = ++index % cursors.length; + } - /** - * Resets the index of the cursor animation to the first in the list. - */ - public void resetAnimation() { - index = 0; - } - - /** - * Native method to create a native cursor - */ - private static native long nCreateCursor(int width, int height, int xHotspot, int yHotspot, int numImages, IntBuffer images, int images_offset); + /** + * Resets the index of the cursor animation to the first in the list. + */ + public void resetAnimation() { + index = 0; + } + + /** + * Native method to create a native cursor + */ + private static native long nCreateCursor(int width, int height, int xHotspot, int yHotspot, int numImages, IntBuffer images, int images_offset); - /** - * Native method to destroy a native cursor - */ - private static native void nDestroyCursor(long cursorHandle); - - /** - * A single cursor element, used when animating - */ - protected class CursorElement { - /** Handle to cursor */ - long cursorHandle; - - /** How long a delay this element should have */ - long delay; - - /** Absolute time this element times out */ - long timeout; - } + /** + * Native method to destroy a native cursor + */ + private static native void nDestroyCursor(long cursorHandle); + + /** + * A single cursor element, used when animating + */ + protected class CursorElement { + /** Handle to cursor */ + long cursorHandle; + + /** How long a delay this element should have */ + long delay; + + /** Absolute time this element times out */ + long timeout; + } } diff --git a/src/java/org/lwjgl/input/Keyboard.java b/src/java/org/lwjgl/input/Keyboard.java index 9770cd52..e739635b 100644 --- a/src/java/org/lwjgl/input/Keyboard.java +++ b/src/java/org/lwjgl/input/Keyboard.java @@ -285,7 +285,8 @@ public class Keyboard { * @throws Exception if the keyboard could not be created for any reason */ public static void create() throws Exception { - assert Window.isCreated() : "Window must be created prior to creating keyboard"; + if (!Window.isCreated()) + throw new IllegalStateException("Window must be created before you can create Keyboard"); if (!initialized) initialize(); if (created) @@ -334,7 +335,8 @@ public class Keyboard { * @see org.lwjgl.input.Keyboard#read() */ public static void poll() { - assert created : "The keyboard has not been created."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can poll the device"); nPoll(keyDownBuffer); } @@ -361,8 +363,10 @@ public class Keyboard { * @see org.lwjgl.input.Keyboard#getEventCharacter() */ public static void read() { - assert created : "The keyboard has not been created."; - assert readBuffer != null : "Keyboard buffering has not been enabled."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can read events"); + if (readBuffer == null) + throw new IllegalStateException("Event buffering must be enabled before you can read events"); readBuffer.compact(); int numEvents = nRead(readBuffer, readBuffer.position()); if (translationEnabled) @@ -383,8 +387,10 @@ public class Keyboard { * and keyboard buffering must be enabled. */ public static void enableTranslation() throws Exception { - assert created : "The keyboard has not been created."; - assert readBuffer != null : "Keyboard buffering has not been enabled."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can read events"); + if (readBuffer == null) + throw new IllegalStateException("Event buffering must be enabled before you can read events"); nEnableTranslation(); translationEnabled = true; } @@ -398,7 +404,8 @@ public class Keyboard { * Enable keyboard buffering. Must be called after the keyboard is created. */ public static void enableBuffer() throws Exception { - assert created : "The keyboard has not been created."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can enable buffering"); readBuffer = BufferUtils.createByteBuffer(4*BUFFER_SIZE); readBuffer.limit(0); nEnableBuffer(); @@ -417,7 +424,8 @@ public class Keyboard { * @return true if the key is down according to the last poll() */ public static boolean isKeyDown(int key) { - assert created : "The keyboard has not been created."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can query key state"); return keyDownBuffer.get(key) != 0; } @@ -442,7 +450,8 @@ public class Keyboard { * @return STATE_ON if on, STATE_OFF if off and STATE_UNKNOWN if the state is unknown */ public static int isStateKeySet(int key) { - assert created : "The keyboard has not been created."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can query key state"); return nisStateKeySet(key); } private static native int nisStateKeySet(int key); @@ -473,7 +482,8 @@ public class Keyboard { * @return the number of keyboard events */ public static int getNumKeyboardEvents() { - assert created : "The keyboard has not been created."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can read events"); if (translationEnabled) return readBuffer.remaining()/4; else @@ -492,8 +502,10 @@ public class Keyboard { * @return true if a keyboard event was read, false otherwise */ public static boolean next() { - assert created : "The keyboard has not been created."; - assert readBuffer != null : "Keyboard buffering has not been enabled."; + if (!created) + throw new IllegalStateException("Keyboard must be created before you can read events"); + if (readBuffer == null) + throw new IllegalStateException("Event buffering must be enabled before you can read events"); if (readBuffer.hasRemaining()) { eventKey = readBuffer.get() & 0xFF; diff --git a/src/java/org/lwjgl/input/Mouse.java b/src/java/org/lwjgl/input/Mouse.java index eb3f0197..ba075e4b 100644 --- a/src/java/org/lwjgl/input/Mouse.java +++ b/src/java/org/lwjgl/input/Mouse.java @@ -167,7 +167,10 @@ public class Mouse { * @throws Exception if the cursor could not be set for any reason */ public static Cursor setNativeCursor(Cursor cursor) throws Exception { - assert created && ((getNativeCursorCaps() | CURSOR_ONE_BIT_TRANSPARENCY) != 0); + if (!created) + throw new IllegalStateException("Create the Mouse before setting the native cursor"); + if ((getNativeCursorCaps() & CURSOR_ONE_BIT_TRANSPARENCY) == 0) + throw new IllegalStateException("Mouse doesn't support native cursors"); Cursor oldCursor = currentCursor; currentCursor = cursor; if (currentCursor != null) { @@ -239,7 +242,8 @@ public class Mouse { */ public static void create() throws Exception { - assert Window.isCreated() : "Window must be created prior to creating mouse"; + if (!Window.isCreated()) + throw new IllegalStateException("Window must be created prior to creating mouse"); if (!initialized) { initialize(); @@ -327,7 +331,8 @@ public class Mouse { * @see org.lwjgl.input.Mouse#read() */ public static void poll() { - assert created : "The mouse has not been created."; + if (!created) + throw new IllegalStateException("Mouse must be created before you can poll it"); nPoll(); // set absolute position @@ -363,7 +368,8 @@ public class Mouse { * @return true if the specified button is down */ public static boolean isButtonDown(int button) { - assert created : "The mouse has not been created."; + if (!created) + throw new IllegalStateException("Mouse must be created before you can poll the button state"); if (button >= buttonCount || button < 0) return false; else @@ -398,7 +404,8 @@ public class Mouse { * Enable mouse button buffering. Must be called after the mouse is created. */ public static void enableBuffer() throws Exception { - assert created : "The mouse has not been created."; + if (!created) + throw new IllegalStateException("Mouse must be created before you can enable buffering"); readBuffer = BufferUtils.createByteBuffer(2*BUFFER_SIZE); readBuffer.limit(0); nEnableBuffer(); @@ -424,8 +431,10 @@ public class Mouse { * @see org.lwjgl.input.Mouse#getEventButtonState() */ public static void read() { - assert created : "The mouse has not been created."; - assert readBuffer != null : "Mouse buffering has not been enabled."; + if (!created) + throw new IllegalStateException("Mouse must be created before you can read events"); + if (readBuffer == null) + throw new IllegalStateException("Event buffering must be enabled before you can read events"); readBuffer.compact(); int numEvents = nRead(readBuffer, readBuffer.position()); readBuffer.position(readBuffer.position() + numEvents*2); @@ -447,8 +456,10 @@ public class Mouse { * @return true if a mouse event was read, false otherwise */ public static boolean next() { - assert created : "The mouse has not been created."; - assert readBuffer != null : "Mouse buffering has not been enabled."; + if (!created) + throw new IllegalStateException("Mouse must be created before you can read events"); + if (readBuffer == null) + throw new IllegalStateException("Event buffering must be enabled before you can read events"); if (readBuffer.hasRemaining()) { eventButton = readBuffer.get() & 0xFF; diff --git a/src/java/org/lwjgl/openal/AL10.java b/src/java/org/lwjgl/openal/AL10.java index e1563360..036cbe92 100644 --- a/src/java/org/lwjgl/openal/AL10.java +++ b/src/java/org/lwjgl/openal/AL10.java @@ -44,321 +44,321 @@ import java.nio.IntBuffer; * @version $Revision$ */ public final class AL10 { - - /** Bad value */ - public static final int AL_INVALID = -1; + + /** Bad value */ + public static final int AL_INVALID = -1; - /** Disable value */ - public static final int AL_NONE = 0; + /** Disable value */ + public static final int AL_NONE = 0; - /** Boolean False */ - public static final int AL_FALSE = 0; + /** Boolean False */ + public static final int AL_FALSE = 0; - /** Boolean True */ - public static final int AL_TRUE = 1; - - /** - * Indicate the type of SOURCE. - * Sources can be spatialized - */ - public static final int AL_SOURCE_TYPE = 0x200; - - /** Indicate source has absolute coordinates */ - public static final int AL_SOURCE_ABSOLUTE = 0x201; - - /** Indicate Source has listener relative coordinates */ - public static final int AL_SOURCE_RELATIVE = 0x202; - - /** - * Directional source, inner cone angle, in degrees - * Range: [0-360] - * Default: 360 - */ - public static final int AL_CONE_INNER_ANGLE = 0x1001; - - /** - * Directional source, outer cone angle, in degrees. - * Range: [0-360] - * Default: 360 - */ - public static final int AL_CONE_OUTER_ANGLE = 0x1002; - - /** - * Specify the pitch to be applied, either at source, - * or on mixer results, at listener. - * Range: [0.5-2.0] - * Default: 1.0 - */ - public static final int AL_PITCH = 0x1003; - - /** - * Specify the current location in three dimensional space. - * OpenAL, like OpenGL, uses a right handed coordinate system, - * where in a frontal default view X (thumb) points right, - * Y points up (index finger), and Z points towards the - * viewer/camera (middle finger). - * To switch from a left handed coordinate system, flip the - * sign on the Z coordinate. - * Listener position is always in the world coordinate system. - */ - public static final int AL_POSITION = 0x1004; - - /** Specify the current direction as forward vector. */ - public static final int AL_DIRECTION = 0x1005; - - /** Specify the current velocity in three dimensional space. */ - public static final int AL_VELOCITY = 0x1006; - - /** - * Indicate whether source has to loop infinite. - * Type: ALboolean - * Range: [TRUE, FALSE] - * Default: FALSE - */ - public static final int AL_LOOPING = 0x1007; - - /** - * Indicate the buffer to provide sound samples. - * Type: ALuint. - * Range: any valid Buffer id. - */ - public static final int AL_BUFFER = 0x1009; - - /** - * Indicate the gain (volume amplification) applied. - * Type: ALfloat. - * Range: ]0.0- ] - * A value of 1.0 means un-attenuated/unchanged. - * Each division by 2 equals an attenuation of -6dB. - * Each multiplicaton with 2 equals an amplification of +6dB. - * A value of 0.0 is meaningless with respect to a logarithmic - * scale; it is interpreted as zero volume - the channel - * is effectively disabled. - */ - public static final int AL_GAIN = 0x100A; - - /** - * Indicate minimum source attenuation. - * Type: ALfloat - * Range: [0.0 - 1.0] - */ - public static final int AL_MIN_GAIN = 0x100D; - - /** - * Indicate maximum source attenuation. - * Type: ALfloat - * Range: [0.0 - 1.0] - */ - public static final int AL_MAX_GAIN = 0x100E; - - /** - * Specify the current orientation. - * Type: ALfv6 (at/up) - * Range: N/A - */ - public static final int AL_ORIENTATION = 0x100F; - - /* byte offset into source (in canon format). -1 if source - * is not playing. Don't set this, get this. - * - * Type: ALfloat - * Range: [0.0 - ] - * Default: 1.0 - */ - public static final int AL_REFERENCE_DISTANCE = 0x1020; - - /** - * Indicate the rolloff factor for the source. - * Type: ALfloat - * Range: [0.0 - ] - * Default: 1.0 - */ - public static final int AL_ROLLOFF_FACTOR = 0x1021; - - /** - * Indicate the gain (volume amplification) applied. - * Type: ALfloat. - * Range: ]0.0- ] - * A value of 1.0 means un-attenuated/unchanged. - * Each division by 2 equals an attenuation of -6dB. - * Each multiplicaton with 2 equals an amplification of +6dB. - * A value of 0.0 is meaningless with respect to a logarithmic - * scale; it is interpreted as zero volume - the channel - * is effectively disabled. - */ - public static final int AL_CONE_OUTER_GAIN = 0x1022; - - /** - * Specify the maximum distance. - * Type: ALfloat - * Range: [0.0 - ] - */ - public static final int AL_MAX_DISTANCE = 0x1023; - - /** - * Specify the channel mask. (Creative) - * Type: ALuint - * Range: [0 - 255] - */ - public static final int AL_CHANNEL_MASK = 0x3000; - - /** Source state information */ - public static final int AL_SOURCE_STATE = 0x1010; - - /** Source state information */ - public static final int AL_INITIAL = 0x1011; - - /** Source state information */ - public static final int AL_PLAYING = 0x1012; - - /** Source state information */ - public static final int AL_PAUSED = 0x1013; - - /** Source state information */ - public static final int AL_STOPPED = 0x1014; - - /** Buffer Queue params */ - public static final int AL_BUFFERS_QUEUED = 0x1015; - - /** Buffer Queue params */ - public static final int AL_BUFFERS_PROCESSED = 0x1016; - - /** Sound buffers: format specifier. */ - public static final int AL_FORMAT_MONO8 = 0x1100; - - /** Sound buffers: format specifier. */ - public static final int AL_FORMAT_MONO16 = 0x1101; - - /** Sound buffers: format specifier. */ - public static final int AL_FORMAT_STEREO8 = 0x1102; - - /** Sound buffers: format specifier. */ - public static final int AL_FORMAT_STEREO16 = 0x1103; - - /** Ogg Vorbis format specifier. */ - public static final int AL_FORMAT_VORBIS_EXT = 0x10003; - - /** - * Sound buffers: frequency, in units of Hertz [Hz]. - * This is the number of samples per second. Half of the - * sample frequency marks the maximum significant - * frequency component. - */ - public static final int AL_FREQUENCY = 0x2001; - - /** - * Sound buffers: frequency, in units of Hertz [Hz]. - * This is the number of samples per second. Half of the - * sample frequency marks the maximum significant - * frequency component. - */ - public static final int AL_BITS = 0x2002; - - /** - * Sound buffers: frequency, in units of Hertz [Hz]. - * This is the number of samples per second. Half of the - * sample frequency marks the maximum significant - * frequency component. - */ - public static final int AL_CHANNELS = 0x2003; - - /** - * Sound buffers: frequency, in units of Hertz [Hz]. - * This is the number of samples per second. Half of the - * sample frequency marks the maximum significant - * frequency component. - */ - public static final int AL_SIZE = 0x2004; - - /** - * Sound buffers: frequency, in units of Hertz [Hz]. - * This is the number of samples per second. Half of the - * sample frequency marks the maximum significant - * frequency component. - */ - public static final int AL_DATA = 0x2005; - - /** - * Buffer state. - * - * Not supported for public use (yet). - */ - public static final int AL_UNUSED = 0x2010; - - /** - * Buffer state. - * - * Not supported for public use (yet). - */ - public static final int AL_PENDING = 0x2011; - - /** - * Buffer state. - * - * Not supported for public use (yet). - */ - public static final int AL_PROCESSED = 0x2012; - - /** Errors: No Error. */ - public static final int AL_NO_ERROR = AL_FALSE; - - /** Illegal name passed as an argument to an AL call. */ - public static final int AL_INVALID_NAME = 0xA001; - - /** Illegal enum passed as an argument to an AL call. */ - public static final int AL_INVALID_ENUM = 0xA002; - - /** - * Illegal value passed as an argument to an AL call. - * Applies to parameter values, but not to enumerations. - */ - public static final int AL_INVALID_VALUE = 0xA003; - - /** - * A function was called at inappropriate time, - * or in an inappropriate way, causing an illegal state. - * This can be an incompatible ALenum, object ID, - * and/or function. - */ - public static final int AL_INVALID_OPERATION = 0xA004; - - /** - * A function could not be completed, - * because there is not enough memory available. - */ - public static final int AL_OUT_OF_MEMORY = 0xA005; - - /** Context strings: Vendor */ - public static final int AL_VENDOR = 0xB001; - - /** Context strings: Version */ - public static final int AL_VERSION = 0xB002; - - /** Context strings: Renderer */ - public static final int AL_RENDERER = 0xB003; - - /** Context strings: Extensions */ - public static final int AL_EXTENSIONS = 0xB004; - - /** Doppler scale. Default 1.0 */ - public static final int AL_DOPPLER_FACTOR = 0xC000; - - /** Doppler velocity. Default 1.0 */ - public static final int AL_DOPPLER_VELOCITY = 0xC001; - - /** Distance model. Default INVERSE_DISTANCE_CLAMPED */ - public static final int AL_DISTANCE_MODEL = 0xD000; - - /** Distance model */ - public static final int AL_INVERSE_DISTANCE = 0xD001; - - /** Distance model */ - public static final int AL_INVERSE_DISTANCE_CLAMPED = 0xD002; + /** Boolean True */ + public static final int AL_TRUE = 1; /** - * 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. + * Indicate the type of SOURCE. + * Sources can be spatialized + */ + public static final int AL_SOURCE_TYPE = 0x200; + + /** Indicate source has absolute coordinates */ + public static final int AL_SOURCE_ABSOLUTE = 0x201; + + /** Indicate Source has listener relative coordinates */ + public static final int AL_SOURCE_RELATIVE = 0x202; + + /** + * Directional source, inner cone angle, in degrees + * Range: [0-360] + * Default: 360 + */ + public static final int AL_CONE_INNER_ANGLE = 0x1001; + + /** + * Directional source, outer cone angle, in degrees. + * Range: [0-360] + * Default: 360 + */ + public static final int AL_CONE_OUTER_ANGLE = 0x1002; + + /** + * Specify the pitch to be applied, either at source, + * or on mixer results, at listener. + * Range: [0.5-2.0] + * Default: 1.0 + */ + public static final int AL_PITCH = 0x1003; + + /** + * Specify the current location in three dimensional space. + * OpenAL, like OpenGL, uses a right handed coordinate system, + * where in a frontal default view X (thumb) points right, + * Y points up (index finger), and Z points towards the + * viewer/camera (middle finger). + * To switch from a left handed coordinate system, flip the + * sign on the Z coordinate. + * Listener position is always in the world coordinate system. + */ + public static final int AL_POSITION = 0x1004; + + /** Specify the current direction as forward vector. */ + public static final int AL_DIRECTION = 0x1005; + + /** Specify the current velocity in three dimensional space. */ + public static final int AL_VELOCITY = 0x1006; + + /** + * Indicate whether source has to loop infinite. + * Type: ALboolean + * Range: [TRUE, FALSE] + * Default: FALSE + */ + public static final int AL_LOOPING = 0x1007; + + /** + * Indicate the buffer to provide sound samples. + * Type: ALuint. + * Range: any valid Buffer id. + */ + public static final int AL_BUFFER = 0x1009; + + /** + * Indicate the gain (volume amplification) applied. + * Type: ALfloat. + * Range: ]0.0- ] + * A value of 1.0 means un-attenuated/unchanged. + * Each division by 2 equals an attenuation of -6dB. + * Each multiplicaton with 2 equals an amplification of +6dB. + * A value of 0.0 is meaningless with respect to a logarithmic + * scale; it is interpreted as zero volume - the channel + * is effectively disabled. + */ + public static final int AL_GAIN = 0x100A; + + /** + * Indicate minimum source attenuation. + * Type: ALfloat + * Range: [0.0 - 1.0] + */ + public static final int AL_MIN_GAIN = 0x100D; + + /** + * Indicate maximum source attenuation. + * Type: ALfloat + * Range: [0.0 - 1.0] + */ + public static final int AL_MAX_GAIN = 0x100E; + + /** + * Specify the current orientation. + * Type: ALfv6 (at/up) + * Range: N/A + */ + public static final int AL_ORIENTATION = 0x100F; + + /* byte offset into source (in canon format). -1 if source + * is not playing. Don't set this, get this. + * + * Type: ALfloat + * Range: [0.0 - ] + * Default: 1.0 + */ + public static final int AL_REFERENCE_DISTANCE = 0x1020; + + /** + * Indicate the rolloff factor for the source. + * Type: ALfloat + * Range: [0.0 - ] + * Default: 1.0 + */ + public static final int AL_ROLLOFF_FACTOR = 0x1021; + + /** + * Indicate the gain (volume amplification) applied. + * Type: ALfloat. + * Range: ]0.0- ] + * A value of 1.0 means un-attenuated/unchanged. + * Each division by 2 equals an attenuation of -6dB. + * Each multiplicaton with 2 equals an amplification of +6dB. + * A value of 0.0 is meaningless with respect to a logarithmic + * scale; it is interpreted as zero volume - the channel + * is effectively disabled. + */ + public static final int AL_CONE_OUTER_GAIN = 0x1022; + + /** + * Specify the maximum distance. + * Type: ALfloat + * Range: [0.0 - ] + */ + public static final int AL_MAX_DISTANCE = 0x1023; + + /** + * Specify the channel mask. (Creative) + * Type: ALuint + * Range: [0 - 255] + */ + public static final int AL_CHANNEL_MASK = 0x3000; + + /** Source state information */ + public static final int AL_SOURCE_STATE = 0x1010; + + /** Source state information */ + public static final int AL_INITIAL = 0x1011; + + /** Source state information */ + public static final int AL_PLAYING = 0x1012; + + /** Source state information */ + public static final int AL_PAUSED = 0x1013; + + /** Source state information */ + public static final int AL_STOPPED = 0x1014; + + /** Buffer Queue params */ + public static final int AL_BUFFERS_QUEUED = 0x1015; + + /** Buffer Queue params */ + public static final int AL_BUFFERS_PROCESSED = 0x1016; + + /** Sound buffers: format specifier. */ + public static final int AL_FORMAT_MONO8 = 0x1100; + + /** Sound buffers: format specifier. */ + public static final int AL_FORMAT_MONO16 = 0x1101; + + /** Sound buffers: format specifier. */ + public static final int AL_FORMAT_STEREO8 = 0x1102; + + /** Sound buffers: format specifier. */ + public static final int AL_FORMAT_STEREO16 = 0x1103; + + /** Ogg Vorbis format specifier. */ + public static final int AL_FORMAT_VORBIS_EXT = 0x10003; + + /** + * Sound buffers: frequency, in units of Hertz [Hz]. + * This is the number of samples per second. Half of the + * sample frequency marks the maximum significant + * frequency component. + */ + public static final int AL_FREQUENCY = 0x2001; + + /** + * Sound buffers: frequency, in units of Hertz [Hz]. + * This is the number of samples per second. Half of the + * sample frequency marks the maximum significant + * frequency component. + */ + public static final int AL_BITS = 0x2002; + + /** + * Sound buffers: frequency, in units of Hertz [Hz]. + * This is the number of samples per second. Half of the + * sample frequency marks the maximum significant + * frequency component. + */ + public static final int AL_CHANNELS = 0x2003; + + /** + * Sound buffers: frequency, in units of Hertz [Hz]. + * This is the number of samples per second. Half of the + * sample frequency marks the maximum significant + * frequency component. + */ + public static final int AL_SIZE = 0x2004; + + /** + * Sound buffers: frequency, in units of Hertz [Hz]. + * This is the number of samples per second. Half of the + * sample frequency marks the maximum significant + * frequency component. + */ + public static final int AL_DATA = 0x2005; + + /** + * Buffer state. + * + * Not supported for public use (yet). + */ + public static final int AL_UNUSED = 0x2010; + + /** + * Buffer state. + * + * Not supported for public use (yet). + */ + public static final int AL_PENDING = 0x2011; + + /** + * Buffer state. + * + * Not supported for public use (yet). + */ + public static final int AL_PROCESSED = 0x2012; + + /** Errors: No Error. */ + public static final int AL_NO_ERROR = AL_FALSE; + + /** Illegal name passed as an argument to an AL call. */ + public static final int AL_INVALID_NAME = 0xA001; + + /** Illegal enum passed as an argument to an AL call. */ + public static final int AL_INVALID_ENUM = 0xA002; + + /** + * Illegal value passed as an argument to an AL call. + * Applies to parameter values, but not to enumerations. + */ + public static final int AL_INVALID_VALUE = 0xA003; + + /** + * A function was called at inappropriate time, + * or in an inappropriate way, causing an illegal state. + * This can be an incompatible ALenum, object ID, + * and/or function. + */ + public static final int AL_INVALID_OPERATION = 0xA004; + + /** + * A function could not be completed, + * because there is not enough memory available. + */ + public static final int AL_OUT_OF_MEMORY = 0xA005; + + /** Context strings: Vendor */ + public static final int AL_VENDOR = 0xB001; + + /** Context strings: Version */ + public static final int AL_VERSION = 0xB002; + + /** Context strings: Renderer */ + public static final int AL_RENDERER = 0xB003; + + /** Context strings: Extensions */ + public static final int AL_EXTENSIONS = 0xB004; + + /** Doppler scale. Default 1.0 */ + public static final int AL_DOPPLER_FACTOR = 0xC000; + + /** Doppler velocity. Default 1.0 */ + public static final int AL_DOPPLER_VELOCITY = 0xC001; + + /** Distance model. Default INVERSE_DISTANCE_CLAMPED */ + public static final int AL_DISTANCE_MODEL = 0xD000; + + /** Distance model */ + public static final int AL_INVERSE_DISTANCE = 0xD001; + + /** Distance model */ + public static final int AL_INVERSE_DISTANCE_CLAMPED = 0xD002; + + /** + * 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 */ @@ -366,8 +366,8 @@ public final class AL10 { /** * 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. + * 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 */ @@ -375,14 +375,14 @@ public final class AL10 { /** * 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. - *

+ * 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 @@ -399,96 +399,98 @@ public final class AL10 { public static native void alHint(int target, int mode); /** - * 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. - *

+ * 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); /** - * 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. - */ + * 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); /** - * 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. - */ + * 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); /** - * 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 - */ + * 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 + */ public static void alGetInteger(int pname, IntBuffer data) { - assert data.remaining() > 0; + if (data.remaining() <= 0) + throw new IllegalArgumentException("data.remaining() <= 0"); nalGetIntegerv(pname, data, data.position()); } private static native void nalGetIntegerv(int pname, IntBuffer data, int offset); /** - * 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 - */ + * 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 void alGetFloat(int pname, FloatBuffer data) { - assert data.remaining() > 0; + if (data.remaining() <= 0) + throw new IllegalArgumentException("data.remaining() <= 0"); nalGetFloatv(pname, data, data.position()); } private static native void nalGetFloatv(int pname, FloatBuffer data, int position); /** * 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. + * 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 @@ -497,78 +499,78 @@ public final class AL10 { /** * 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. - *

+ * 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 */ @@ -576,11 +578,11 @@ public final class AL10 { /** * 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. - *

+ * 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 @@ -588,19 +590,19 @@ public final class AL10 { public static native boolean alIsExtensionPresent(String fname); /** - *

+ *

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

+ * 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 @@ -622,32 +624,32 @@ public final class AL10 { * @param value floating point value to set the attribute to */ public static native void alListenerf(int pname, float value); - - /** - * Listener attributes are changed using the Listener group of commands. - * - * @param pname name of the attribute to be set - * @param value FloatBuffer containing value to set the attribute to - */ - public static void alListener(int pname, FloatBuffer value) { - nalListenerfv(pname, value, value.position()); - } - public static native void nalListenerfv(int pname, FloatBuffer value, int offset); - - /** - * Listener attributes are changed using the Listener group of commands. - * - * @param pname name of the attribute to be set - * @param v1 value value 1 - * @param v2 value value 2 - * @param v3 float value 3 - */ - public static native void alListener3f(int pname, float v1, float v2, float v3); - + + /** + * Listener attributes are changed using the Listener group of commands. + * + * @param pname name of the attribute to be set + * @param value FloatBuffer containing value to set the attribute to + */ + public static void alListener(int pname, FloatBuffer value) { + nalListenerfv(pname, value, value.position()); + } + public static native void nalListenerfv(int pname, FloatBuffer value, int offset); + + /** + * Listener attributes are changed using the Listener group of commands. + * + * @param pname name of the attribute to be set + * @param v1 value value 1 + * @param v2 value value 2 + * @param v3 float value 3 + */ + public static native void alListener3f(int pname, float v1, float v2, float v3); + /** - * Listener state is maintained inside the AL implementation and can be queried in - * full. + * Listener state is maintained inside the AL implementation and can be queried in + * full. * * @param pname name of the attribute to be retrieved * @return int @@ -655,8 +657,8 @@ public final class AL10 { public static native int alGetListeneri(int pname); /** - * Listener state is maintained inside the AL implementation and can be queried in - * full. + * Listener state is maintained inside the AL implementation and can be queried in + * full. * * @param pname name of the attribute to be retrieved * @return float @@ -665,7 +667,7 @@ public final class AL10 { /** * Listener state is maintained inside the AL implementation and can be queried in - * full. + * full. * * @param pname name of the attribute to be retrieved * @param floatdata Buffer to write floats to @@ -704,8 +706,8 @@ public final class AL10 { public static native boolean alIsSource(int id); /** - * Specifies the position and other properties as taken into account during - * sound processing. + * 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 @@ -714,50 +716,50 @@ public final class AL10 { public static native void alSourcei(int source, int pname, int value); /** - * Specifies the position and other properties as taken into account during - * sound processing. + * 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 * @param value value of property */ public static native void alSourcef(int source, int pname, float value); - - /** - * 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 - * @param value FloatBuffer containing value of property - */ - public static void alSource(int source, int pname, FloatBuffer value) { - nalSourcefv(source, pname, value, value.position()); - } - public static native void nalSourcefv(int source, int pname, FloatBuffer value, int offset); - - /** - * 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 - * @param v1 value 1 of property - * @param v2 value 2 of property - * @param v3 value 3 of property - */ - public static native void alSource3f( - int source, - int pname, - float v1, - float v2, - float v3); - + + /** + * Specifies the position and other properties as taken into account during + * sound processing. + * + * @param source Source to det property on + * @param pname property to set + * @param value FloatBuffer containing value of property + */ + public static void alSource(int source, int pname, FloatBuffer value) { + nalSourcefv(source, pname, value, value.position()); + } + public static native void nalSourcefv(int source, int pname, FloatBuffer value, int offset); + + /** + * 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 + * @param v1 value 1 of property + * @param v2 value 2 of property + * @param v3 value 3 of property + */ + public static native void alSource3f( + int source, + int pname, + float v1, + float v2, + float v3); + /** - * 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. + * 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 @@ -766,9 +768,9 @@ public final class AL10 { public static native int alGetSourcei(int source, int pname); /** - * Source state is maintained inside the AL implementation, and the current attributes - * can be queried. The performance of such queries is implementation dependent, no - * performance guarantees are made. + * 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 @@ -777,29 +779,30 @@ public final class AL10 { public static native float alGetSourcef(int source, int pname); /** - * Source state is maintained inside the AL implementation, and the current attributes - * can be queried. The performance of such queries is implementation dependent, no - * performance guarantees are made. + * 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 * @param floatdata Buffer to write floats to */ public static void alGetSource(int source, int pname, FloatBuffer floatdata) { - assert floatdata.remaining() > 0; + if (floatdata.remaining() <= 0) + throw new IllegalArgumentException("floatdata.remaining() <= 0"); nalGetSourcefv(source, pname, floatdata, floatdata.position()); } private static native void nalGetSourcefv(int source, int pname, FloatBuffer floatdata, int position); /** - * 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. + * 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 sources array of sources to play */ @@ -809,10 +812,10 @@ public final class AL10 { private static native void nalSourcePlayv(int n, IntBuffer sources, int offset); /** - * 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. + * 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 sources array of sources to pause */ @@ -822,11 +825,11 @@ public final class AL10 { private static native void nalSourcePausev(int n, IntBuffer sources, int offset); /** - * 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. + * 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 sources array of sources to stop */ @@ -836,13 +839,13 @@ public final class AL10 { private static native void nalSourceStopv(int n, IntBuffer sources, int offset); /** - * 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. + * 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 sources array of sources to rewind */ @@ -853,13 +856,13 @@ public final class AL10 { /** * 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. + * 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 */ @@ -867,9 +870,9 @@ public final class AL10 { /** * 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. + * 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 */ @@ -877,10 +880,10 @@ public final class AL10 { /** * 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. + * 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 */ @@ -888,12 +891,12 @@ public final class AL10 { /** * 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. + * 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 */ @@ -910,18 +913,18 @@ public final class AL10 { private static native void nalGenBuffers(int n, IntBuffer buffers, int offset); /** - *

+ *

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

+ *

+ * 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 buffers Buffer to delete from */ @@ -939,26 +942,26 @@ public final class AL10 { public static native boolean alIsBuffer(int buffer); /** - *

+ *

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

+ * 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 @@ -984,8 +987,8 @@ public final class AL10 { /** * 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.
+ * 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 @@ -993,9 +996,9 @@ public final class AL10 { public static native int alGetBufferi(int buffer, int pname); /** - * Buffer state is maintained inside the AL implementation and can be queried in full.
- * ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].
- * ALC_SIZE - Size in bytes of the buffer data.
+ * 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 @@ -1004,16 +1007,16 @@ public final class AL10 { public static native float alGetBufferf(int buffer, int pname); /** - *

+ *

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

+ * 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 buffers buffers to be queued @@ -1024,20 +1027,20 @@ public final class AL10 { private static native void nalSourceQueueBuffers(int source, int n, IntBuffer buffers, int offset); /** - *

+ *

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

+ * 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 buffers buffers to be unqueued @@ -1048,105 +1051,105 @@ public final class AL10 { private static native void nalSourceUnqueueBuffers(int source, int n, IntBuffer buffers, int offset); /** - *

+ *

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

+ * 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); /** - * 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. - *

+ * 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 */ @@ -1154,54 +1157,54 @@ public final class AL10 { /** * 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. + * 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. - *

- * + *

+ *

+	 *	 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/opengl/ARBVertexBufferObject.java b/src/java/org/lwjgl/opengl/ARBVertexBufferObject.java index 85b255b1..c8cdc29b 100644 --- a/src/java/org/lwjgl/opengl/ARBVertexBufferObject.java +++ b/src/java/org/lwjgl/opengl/ARBVertexBufferObject.java @@ -89,7 +89,7 @@ public final class ARBVertexBufferObject { case GL_ARRAY_BUFFER_ARB: VBOTracker.getVBOArrayStack().setState(buffer); break; - default: assert false: "Unsupported VBO target " + target; + default: throw new IllegalArgumentException("Unsupported VBO target " + target); } nglBindBufferARB(target, buffer); } diff --git a/src/java/org/lwjgl/opengl/ARBVertexShader.java b/src/java/org/lwjgl/opengl/ARBVertexShader.java index a902c389..0748dad0 100644 --- a/src/java/org/lwjgl/opengl/ARBVertexShader.java +++ b/src/java/org/lwjgl/opengl/ARBVertexShader.java @@ -67,7 +67,7 @@ public final class ARBVertexShader { // --------------------------- public static void glBindAttribLocationARB(int programObj, int index, ByteBuffer name) { if ( name.get(name.limit() - 1) != 0 ) { - throw new RuntimeException(" must be a null-terminated string."); + throw new IllegalArgumentException(" must be a null-terminated string."); } nglBindAttribLocationARB(programObj, index, name, name.position()); } @@ -99,7 +99,7 @@ public final class ARBVertexShader { // --------------------------- public static int glGetAttribLocationARB(int programObj, ByteBuffer name) { if ( name.get(name.limit() - 1) != 0 ) { - throw new RuntimeException(" must be a null-terminated string."); + throw new IllegalArgumentException(" must be a null-terminated string."); } return nglGetAttribLocationARB(programObj, name, name.position()); } @@ -107,4 +107,4 @@ public final class ARBVertexShader { private static native int nglGetAttribLocationARB(int programObj, ByteBuffer name, int nameOffset); // --------------------------- -} \ No newline at end of file +} diff --git a/src/java/org/lwjgl/opengl/ATIDrawBuffers.java b/src/java/org/lwjgl/opengl/ATIDrawBuffers.java index 1a5128a3..c0b312ad 100644 --- a/src/java/org/lwjgl/opengl/ATIDrawBuffers.java +++ b/src/java/org/lwjgl/opengl/ATIDrawBuffers.java @@ -68,7 +68,7 @@ public final class ATIDrawBuffers { // --------------------------- public static void glDrawBuffersATI(IntBuffer buffers) { if (buffers.remaining() == 0) { - throw new RuntimeException(" must have at least 1 integer available."); + throw new IllegalArgumentException(" must have at least 1 integer available."); } nglDrawBuffersATI(buffers.remaining(), buffers, buffers.position()); } @@ -76,4 +76,4 @@ public final class ATIDrawBuffers { private static native void nglDrawBuffersATI(int size, IntBuffer buffers, int buffersOffset); // --------------------------- -} \ No newline at end of file +} diff --git a/src/java/org/lwjgl/opengl/GL15.java b/src/java/org/lwjgl/opengl/GL15.java index 13bb1da5..61ca9535 100644 --- a/src/java/org/lwjgl/opengl/GL15.java +++ b/src/java/org/lwjgl/opengl/GL15.java @@ -87,7 +87,7 @@ public final class GL15 { VBOTracker.getVBOArrayStack().setState(buffer); break; default: - assert false: "Unsupported VBO target " + target; + throw new IllegalArgumentException("Unsupported VBO target " + target); } nglBindBuffer(target, buffer); } @@ -296,4 +296,4 @@ public final class GL15 { int paramsOffset); // --------------------------- -} \ No newline at end of file +} diff --git a/src/java/org/lwjgl/opengl/Window.java b/src/java/org/lwjgl/opengl/Window.java index 2c3eeb3a..a60cc47a 100644 --- a/src/java/org/lwjgl/opengl/Window.java +++ b/src/java/org/lwjgl/opengl/Window.java @@ -108,7 +108,8 @@ public final class Window { * @return the width of the window */ public static int getWidth() { - assert isCreated() : "Cannot get width on uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot get width on uncreated window"); return width; } @@ -116,7 +117,8 @@ public final class Window { * @return the height of the window */ public static int getHeight() { - assert isCreated() : "Cannot get height on uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot get height on uncreated window"); return height; } @@ -124,15 +126,17 @@ public final class Window { * @return the title of the window */ public static String getTitle() { - assert isCreated() : "Cannot get title on uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot get title on uncreated window"); return title; } - + /** * @return whether this window is in fullscreen mode */ public static boolean isFullscreen() { - assert isCreated() : "Cannot determine state of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine fullscreen state of uncreated window"); return fullscreen; } @@ -141,7 +145,8 @@ public final class Window { * @param newTitle The new window title */ public static void setTitle(String newTitle) { - assert isCreated() : "Cannot set title of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot set title on uncreated window"); title = newTitle; nSetTitle(title); } @@ -156,7 +161,8 @@ public final class Window { * @return true if the user or operating system has asked the window to close */ public static boolean isCloseRequested() { - assert isCreated() : "Cannot determine state of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine close requested state of uncreated window"); return nIsCloseRequested(); } @@ -166,7 +172,8 @@ public final class Window { * @return true if the window is minimized or otherwise not visible */ public static boolean isMinimized() { - assert isCreated() : "Cannot determine state of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine minimized state of uncreated window"); return nIsMinimized(); } @@ -176,7 +183,8 @@ public final class Window { * @return true if window is focused */ public static boolean isFocused() { - assert isCreated() : "Cannot determine state of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine focused state of uncreated window"); return nIsFocused(); } @@ -210,7 +218,8 @@ public final class Window { * and needs to repaint itself */ public static boolean isDirty() { - assert isCreated() : "Cannot determine state of uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine dirty state of uncreated window"); return nIsDirty(); } @@ -222,7 +231,8 @@ public final class Window { * @throws OpenGLException if an OpenGL error has occured since the last call to GL11.glGetError() */ public static void update() { - assert isCreated() : "Cannot paint uncreated window"; + if (!isCreated()) + throw new IllegalStateException("Cannot determine update uncreated window"); nUpdate(); if ((isDirty() && !isMinimized()) || (isFocused() && !isMinimized())) { Util.checkGLError(); @@ -259,7 +269,8 @@ public final class Window { * Make the Window the current rendering context for GL calls. */ public static synchronized void makeCurrent() { - assert isCreated() : "No window has been created."; + if (!isCreated()) + throw new IllegalStateException("No window created to make current"); nMakeCurrent(); GLContext.useContext(context); } @@ -315,7 +326,7 @@ public final class Window { */ public static void create(String title, int bpp, int alpha, int depth, int stencil, int samples) throws Exception { if (isCreated()) - throw new Exception("Only one LWJGL window may be instantiated at any one time."); + throw new IllegalStateException("Only one LWJGL window may be instantiated at any one time."); Window.fullscreen = true; Window.x = 0; Window.y = 0; @@ -371,7 +382,7 @@ public final class Window { public static void create(String title, int x, int y, int width, int height, int bpp, int alpha, int depth, int stencil, int samples) throws Exception { if (isCreated()) - throw new Exception("Only one LWJGL window may be instantiated at any one time."); + throw new IllegalStateException("Only one LWJGL window may be instantiated at any one time."); Window.fullscreen = false; Window.x = x; Window.y = y; @@ -518,7 +529,8 @@ public final class Window { * @return boolean */ public static boolean isVSyncEnabled() { - assert isCreated() : "Cannot determine sync of uncreated window"; + if (isCreated()) + throw new IllegalStateException("Cannot determine vsync state of uncreated window"); return nIsVSyncEnabled(); } @@ -531,11 +543,10 @@ public final class Window { * @param sync true to synchronize; false to ignore synchronization */ public static void setVSyncEnabled(boolean sync) { - assert isCreated() : "Cannot set sync of uncreated window"; + if (isCreated()) + throw new IllegalStateException("Cannot set vsync state of uncreated window"); nSetVSyncEnabled(sync); } private static native void nSetVSyncEnabled(boolean sync); - - }