net.rim.device.api.opengles
Class GLUtils

java.lang.Object
  net.rim.device.api.opengles.GLUtils

public final class GLUtils
extends Object

Provides a set of utility methods for OpenGL ES applications.

The methods in this library are GLU methods as well as modified OpenGL ES methods which support BlackBerry specific data types to simplify development.

GLU is the OpenGL Utility Library that contains set of functions to create texture mipmaps from a base image or map coordinates between screen and object space.

Since:

BlackBerry API 5.0.0

Field Summary
static int	VERSION_1_1 Constant uses to test support for OpenGL ES 1.1.
static int	VERSION_2_0 Constant uses to test support for OpenGL ES 2.0.

Method Summary
static boolean	freeBuffer(Buffer buffer) Attempts to explicitly free any native memory that is currently allocated for the specified direct buffer.
static int	glLoadShader(GL gl, int type, String source, String[] infolog, int infologOffset) Creates and loads a shader.
static void	glTexImage2D(GL gl, int target, int level, int format, int type, Bitmap bitmap, XYRect region) Loads a texture from the given Bitmap.
static void	glTexImage2D(GL gl, int target, int level, int format, int type, EncodedImage encodedImage, XYRect region) Loads a texture from the given EncodedImage.
static void	glTexImage2D(GL gl, int level, int format, int type, Bitmap bitmap, XYRect region) Loads a texture from the given Bitmap.
static void	glTexSubImage2D(GL gl, int target, int level, int xoffset, int yoffset, int format, int type, Bitmap bitmap, XYRect region) Loads a texture subimage from the given Bitmap.
static void	glTexSubImage2D(GL gl, int target, int level, int xoffset, int yoffset, int format, int type, EncodedImage encodedImage, XYRect region) Loads a texture subimage from the given EncodedImage.
static void	gluBuild2DMipmaps(GL gl, int format, int type, Bitmap bitmap) Builds a two-dimensional texture mipmap chain for the specified Bitmap.
static void	gluBuild2DMipmaps(GL gl, int format, int type, EncodedImage encodedImage) Builds a two-dimensional texture mipmap chain for the specified EncodedImage.
static void	gluLookAt(GL gl, float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ) Loads a view transformation matrix.
static void	gluOrtho2D(GL gl, float left, float right, float bottom, float top) Defines a 2D orthographic projection matrix.
static void	gluPerspective(GL gl, float fovy, float aspect, float zNear, float zFar) Loads a 3D perspective projection matrix.
static boolean	gluProject(float objX, float objY, float objZ, float[] model, float[] proj, int[] view, float[] win) Maps object coordinates to window coordinates.
static boolean	gluUnProject(float winX, float winY, float winZ, float[] model, float[] proj, int[] view, float[] obj) Maps window coordinates to object coordinates.
static boolean	isSupported() Determines whether or not the device supports OpenGL ES.
static boolean	isSupported(int version) Determines whether or not the device supports OpenGL ES 1.1 or OpenGL ES 2.0.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION_1_1

public static final int VERSION_1_1

Constant uses to test support for OpenGL ES 1.1.

See Also:

GLUtils.isSupported(int), Constant Field Values

Since:

BlackBerry API 7.0.0

VERSION_2_0

public static final int VERSION_2_0

Constant uses to test support for OpenGL ES 2.0.

See Also:

GLUtils.isSupported(int), Constant Field Values

Since:

BlackBerry API 7.0.0

Method Detail

isSupported

public static boolean isSupported()

Determines whether or not the device supports OpenGL ES.

To query the actual version of OpenGL ES supported for the device, you can also use glGetString(int).

Returns:

True if the device supports some version of OpenGL ES, false otherwise.

Since:

BlackBerry API 5.0.0

isSupported

public static boolean isSupported(int version)

Determines whether or not the device supports OpenGL ES 1.1 or OpenGL ES 2.0.

To query the actual version of OpenGL ES supported for the device, you can also use glGetString(int).

Parameters:

version - Must be GLUtils#VERSION_1_1 or GLUtils.VERSION_2_0 or will return false.

Returns:

True if the device supports the queried version of OpenGL ES, false otherwise.

Since:

BlackBerry API 7.0.0

glLoadShader

public static int glLoadShader(GL gl,
                               int type,
                               String source,
                               String[] infolog,
                               int infologOffset)

Creates and loads a shader. This method is equivalent to the following code (with error checking added):

 shader = gl.glCreateShader(type);
 gl.glShaderSource(shader, source);
 gl.glCompileShader(shader);
 

Parameters:

gl - The GL context to load the shader into.

type - The type of the shader; must be GL_VERTEX_SHADER or GL_FRAGMENT_SHADER.

source - The shader source code.

infolog - A String array of length at least 1. Returns the information log for the shader if the shader failed to compile. May be null.

infologOffset - The starting offset within the infolog array.

Returns:

The handle to the shader object or 0 if there was an error creating or compiling the shader.

Throws:

IllegalArgumentException - If gl or source is null.

IllegalArgumentException - If the given GL context does not support shaders (version < 2.0).

IllegalArgumentException - If infolog is non-null but infolog.length - infologOffset is smaller than 1.

IllegalArgumentException - If infologOffset is less than 0.

UnsupportedOperationException - If there is no shader compiler support.

Since:

BlackBerry API 7.0.0

glTexImage2D

public static void glTexImage2D(GL gl,
                                int level,
                                int format,
                                int type,
                                Bitmap bitmap,
                                XYRect region)

Loads a texture from the given Bitmap.

The texture is loaded into the currently bound GL texture name and active texture unit. The specified format and type need not match the native format of the bitmap since this method will perform any necessary conversions. When this method returns, the input bitmap can be safely discarded (set to null) since the texture data is stored on the server.

A GL error may be set if the texture fails to load (for example, if level, format or type are invalid. To check for possible errors, call glGetError().

Parameters:

gl - The GL context to load the texture into.

level - Target mipmap level to load the texture into (zero is the base level).

format - Format for the generated texture (one of GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA).

type - Data type of the generated pixel data (one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1).

bitmap - Bitmap containing the texture data to load.

region - Region of the bitmap to load into the texture (null to load the entire bitmap).

Throws:

IllegalArgumentException - if gl or bitmap are null.

See Also:

glTexImage2D(int,int,int,int,int,int,int,int,java.nio.Buffer)

Since:

BlackBerry API 5.0.0

glTexImage2D

public static void glTexImage2D(GL gl,
                                int target,
                                int level,
                                int format,
                                int type,
                                Bitmap bitmap,
                                XYRect region)

Loads a texture from the given Bitmap.

The texture is loaded into the currently bound GL texture name and active texture unit. The specified format and type need not match the native format of the bitmap since this method will perform any necessary conversions. When this method returns, the input bitmap can be safely discarded (set to null) since the texture data is stored on the server.

A GL error may be set if the texture fails to load (for example, if target, level, format or type are invalid. To check for possible errors, call glGetError().

Parameters:

gl - The GL context to load the texture into.

target - The texture target to load the texture for (must be GL_TEXTURE_2D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL_TEXTURE_CUBE_MAP_NEGATIVE_Z).

level - Target mipmap level to load the texture into (zero is the base level).

format - Format for the generated texture (one of GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA).

type - Data type of the generated pixel data (one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1).

bitmap - Bitmap containing the texture data to load.

region - Region of the bitmap to load into the texture (null to load the entire bitmap).

Throws:

IllegalArgumentException - if gl or bitmap are null.

IllegalArgumentException - if region does not define a positive region or region is not contained within the bitmap dimensions.

See Also:

glTexImage2D(int,int,int,int,int,int,int,int,java.nio.Buffer)

Since:

BlackBerry API 7.0.0

glTexImage2D

public static void glTexImage2D(GL gl,
                                int target,
                                int level,
                                int format,
                                int type,
                                EncodedImage encodedImage,
                                XYRect region)

Loads a texture from the given EncodedImage.

The texture is loaded into the currently bound GL texture name and active texture unit. The specified format and type need not match the native format of the EncodedImage since this method will perform any necessary conversions. When this method returns, the input EncodedImage can be safely discarded (set to null) since the texture data is stored on the server.

A GL error may be set if the texture fails to load (for example, if target, level, format or type are invalid. To check for possible errors, call glGetError().

Parameters:

gl - The GL context to load the texture into.

target - The texture target to load the texture for (must be GL_TEXTURE_2D, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Z).

level - Target mipmap level to load the texture into (zero is the base level).

format - Format for the generated texture (one of GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA).

type - Data type of the generated pixel data (one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1).

encodedImage - EncodedImage containing the texture data to load.

region - Region of the EncodedImage to load into the texture (null to load the entire EncodedImage).

Throws:

IllegalArgumentException - if gl or encodedImage are null.

IllegalArgumentException - if region does not define a positive region or region is not contained within the encodedImage dimensions.

See Also:

glTexImage2D(int,int,int,int,int,int,int,int,java.nio.Buffer)

Since:

BlackBerry API 7.0.0

glTexSubImage2D

public static void glTexSubImage2D(GL gl,
                                   int target,
                                   int level,
                                   int xoffset,
                                   int yoffset,
                                   int format,
                                   int type,
                                   Bitmap bitmap,
                                   XYRect region)

Loads a texture subimage from the given Bitmap.

See GL10.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer) or GL20.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer) for the list of possible GL errors.

Parameters:

gl - The GL context to load the texture into.

target - Specifies the target texture of the active texture unit. Must be GL_TEXTURE_2D, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Z.

level - Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

xoffset - Specifies a texel offset in the x direction within the texture array.

yoffset - Specifies a texel offset in the y direction within the texture array.

format - Specifies the format of the pixel data. The following symbolic values are accepted: GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA.

type - Specifies the data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1.

bitmap - Specifies the bitmap containing the texture data to load.

region - Specifies the region of the bitmap to load into the texture (null to load the entire bitmap).

Throws:

IllegalArgumentException - if gl or bitmap are null.

IllegalArgumentException - if region does not define a positive region or region is not contained within the bitmap dimensions.

See Also:

GL10.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer), GL20.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer)

Since:

BlackBerry API 7.0.0

glTexSubImage2D

public static void glTexSubImage2D(GL gl,
                                   int target,
                                   int level,
                                   int xoffset,
                                   int yoffset,
                                   int format,
                                   int type,
                                   EncodedImage encodedImage,
                                   XYRect region)

Loads a texture subimage from the given EncodedImage.

See GL10.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer) or GL20.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer) for the list of possible GL errors.

Parameters:

gl - The GL context to load the texture into.

target - Specifies the target texture of the active texture unit. Must be GL_TEXTURE_2D, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL20.GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL20.GL_TEXTURE_CUBE_MAP_NEGATIVE_Z.

level - Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

xoffset - Specifies a texel offset in the x direction within the texture array.

yoffset - Specifies a texel offset in the y direction within the texture array.

format - Specifies the format of the pixel data. The following symbolic values are accepted: GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA.

type - Specifies the data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1.

encodedImage - Specifies the EncodedImage containing the texture data to load.

region - Specifies the region of the bitmap to load into the texture (null to load the entire bitmap).

Throws:

IllegalArgumentException - if gl or encodedImage are null.

IllegalArgumentException - if region does not define a positive region or region is not contained within the encodedImage dimensions.

See Also:

GL10.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer), GL20.glTexSubImage2D(int, int, int, int, int, int, int, int, java.nio.Buffer)

Since:

BlackBerry API 7.0.0

gluOrtho2D

public static void gluOrtho2D(GL gl,
                              float left,
                              float right,
                              float bottom,
                              float top)

Defines a 2D orthographic projection matrix.

This method sets up a 2D orthographic viewing region that is equivalent to calling glOrthof with near equal to -1 and far equal to 1.

If the value of the left and right parameters are equal or the value of the bottom and top parameters are equal, OpenGL ES error GL_INVALID_VALUE is set and can be checked by calling glGetError().

Parameters:

gl - The GL context to operate on.

left - Left clipping plane coordinate.

right - Right clipping plane coordinate.

bottom - Bottom clipping plane coordinate.

top - Top clipping plane coordinate.

Throws:

IllegalArgumentException - if gl is null.

See Also:

glOrthof

Since:

BlackBerry API 5.0.0

gluPerspective

public static void gluPerspective(GL gl,
                                  float fovy,
                                  float aspect,
                                  float zNear,
                                  float zFar)

Loads a 3D perspective projection matrix.

This method sets up a viewing frustum into the world. The aspect parameter should typically be the same as the aspect ratio of the target viewport.

The matrix generated by this method is multiplied by the current GL matrix using glMultMatrixf. To overwrite the existing matrix instead, call glLoadIdentity prior to calling this method.

If the value of the aspect parameter or fovy parameter is 0 or the value of the zFar parameter or zNear parameter is less than or equal to 0, OpenGL ES error GL_INVALID_VALUE is set and can be checked by calling glGetError().

Parameters:

gl - The GL context to operate on.

fovy - Field of view angle in the y direction, in degrees.

aspect - Aspect ratio that determines the field of view in the x direction (usually width/height).

zNear - Distance to the near clipping plane (should be > 0).

zFar - Distance to the far clipping plane.

Throws:

IllegalArgumentException - if gl is null.

See Also:

glFrustumf

Since:

BlackBerry API 5.0.0

gluLookAt

public static void gluLookAt(GL gl,
                             float eyeX,
                             float eyeY,
                             float eyeZ,
                             float centerX,
                             float centerY,
                             float centerZ,
                             float upX,
                             float upY,
                             float upZ)

Loads a view transformation matrix.

This method creates a viewing matrix based on an eye point, a look-at point indicating the center of the scene and an up vector.

Parameters:

gl - The GL context to operate on.

eyeX - Eye X coordinate

eyeY - Eye Y coordinate

eyeZ - Eye Z coordinate

centerX - Center X coordinate

centerY - Center Y coordinate

centerZ - Center Z coordinate

upX - Up vector X value

upY - Up vector Y value

upZ - Up vector Z value

Throws:

IllegalArgumentException - if gl is null.

Since:

BlackBerry API 5.0.0

freeBuffer

public static boolean freeBuffer(Buffer buffer)

Attempts to explicitly free any native memory that is currently allocated for the specified direct buffer.

This method can be used to explicitly free native resources associated with a direct java.nio.Buffer. This is often useful for reclaiming native memory associated with a client-side OpenGL array. If this method succeeds, the state of the buffer will remain valid, however any further use of the buffer may result in the native resources being reallocated.

If the specified buffer has already been destroyed, or if it is wrapped, this method does nothing.

Note: There is no guarantee that underlying memory for the specified buffer will be freed immediately. This may be the case when the buffer (or a view of it) is currently in use. In this case, the buffer may be destroyed at a later time, by either invoking this method again or by letting the buffer fall out of scope and be garbage collected.

Parameters:

buffer - Buffer to free.

Returns:

True if the buffer is successfully freed, false otherwise.

Since:

BlackBerry API 5.0.0

gluProject

public static boolean gluProject(float objX,
                                 float objY,
                                 float objZ,
                                 float[] model,
                                 float[] proj,
                                 int[] view,
                                 float[] win)

Maps object coordinates to window coordinates.

This function is useful for calculating the position, in window coordinates, of the given object coordinates.

In OpenGL ES 1.x, the current modelview and projection matrices can be obtained by calling glGetFloatv, while the current viewport coordinates can be obtained by calling glGetIntegerv.

Parameters:

objX - Object X coordinate.

objY - Object Y coordinate.

objZ - Object Z coordinate.

model - The current modelview matrix.

proj - The current projection matrix.

view - The current viewport rectangle.

win - An array of size 3 that will contain the computed window coordinates and depth-value if gluProject returns true.

Returns:

True if the point is on the screen and window coordinates were calculated, false otherwise.

Throws:

IllegalArgumentException - if model or proj are null or have a length < 16, or if view is null or has a length < 4, or if win is null or has a length < 3.

Since:

BlackBerry API 6.0.0

gluUnProject

public static boolean gluUnProject(float winX,
                                   float winY,
                                   float winZ,
                                   float[] model,
                                   float[] proj,
                                   int[] view,
                                   float[] obj)

Maps window coordinates to object coordinates.

This function is useful for calculating the position, in object coordinates, of the given window coordinates. The z value of the passed in window position specifies distance between the near and far clip planes, where a value of 0.0f corresponds to the near clip plane and a value of 1.0f corresponds to the far clip plane.

In OpenGL ES 1.x, the current modelview and projection matrices can be obtained by calling glGetFloatv, while the current viewport coordinates can be obtained by calling glGetIntegerv.

Parameters:

winX - Window X coordinate.

winY - Window Y coordinate.

winZ - Window Z coordinate.

model - The current modelview matrix.

proj - The current projection matrix.

view - The current viewport rectangle.

obj - An array of size 3 that will contain the computed object coordinates and depth-value if gluUnProject returns true.

Returns:

True if object coordinates could be calculated, false otherwise.

Throws:

IllegalArgumentException - if model or proj are null or have a length < 16, or if view is null or has a length < 4, or if obj is null or has a length < 3.

Since:

BlackBerry API 6.0.0

gluBuild2DMipmaps

public static void gluBuild2DMipmaps(GL gl,
                                     int format,
                                     int type,
                                     Bitmap bitmap)

Builds a two-dimensional texture mipmap chain for the specified Bitmap.

If an error occurrs while building the mipmap chain, an OpenGL ES error will be set and can be checked by calling glGetError().

Note that the dimensions of the specified bitmap need not be a power of two.

Parameters:

gl - The GL context to load the texture mipmaps into.

format - Format for the generated texture (one of GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA).

type - Data type of the generated pixel data (one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1).

bitmap - Bitmap containing the texture data to load.

Throws:

IllegalArgumentException - if gl or bitmap are null.

Since:

BlackBerry API 6.0.0

gluBuild2DMipmaps

public static void gluBuild2DMipmaps(GL gl,
                                     int format,
                                     int type,
                                     EncodedImage encodedImage)

Builds a two-dimensional texture mipmap chain for the specified EncodedImage.

If an error occurrs while building the mipmap chain, an OpenGL ES error will be set and can be checked by calling glGetError().

Note that the dimensions of the specified EncodedImage need not be a power of two.

Parameters:

gl - The GL context to load the texture mipmaps into.

format - Format for the generated texture (one of GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE and GL_LUMINANCE_ALPHA).

type - Data type of the generated pixel data (one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4 and GL_UNSIGNED_SHORT_5_5_5_1).

encodedImage - EncodedImage containing the texture data to load.

Throws:

IllegalArgumentException - if gl or encodedImage are null.

Since:

BlackBerry API 7.0.0