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

Method Summary
static boolean	freeBuffer(Buffer buffer) Attempts to explicitly free any native memory that is currently allocated for the specified direct buffer.
static void	glTexImage2D(GL gl, int level, int format, int type, Bitmap bitmap, XYRect region) Loads a texture from the given Bitmap.
static void	gluBuild2DMipmaps(GL gl, int format, int type, Bitmap bitmap) Builds a two-dimensional texture mipmap chain for the specified Bitmap.
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.

Methods inherited from class java.lang.Object

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

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, use glGetString(int).

Returns:

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

Since:

BlackBerry API 5.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 texutre 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

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.

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.

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 texutre data to load.

Throws:

IllegalArgumentException - if gl or bitmap are null.

Since:

BlackBerry API 6.0.0