net.rim.device.api.opengles
Class GLField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.opengles.GLField

public abstract class GLField
extends Field

Defines an abstract OpenGL ES Field.

Overview

Extending this class makes it much easier to write OpenGL ES applications. This GLField implementation contains optimized code to:

Extending this field allows developers to not have to write any code related to EGL.

Basic OpenGL ES Usage (UI)

Implementing a GLField

At minimal a developer will extend the GLField class and implement the following methods:

 public class MyGLField extends GLField
 {
     protected void layout(int width, int height)
     {
         // Sets the field dimensions to 100x100
         setExtent(100, 100);
     }
     
     protected void initialize(GL gl)
     {
         // Code to initialize any OpenGL ES resources...
         GL11 gl11 = (GL11)gl;
         gl11.glClearColor(0, 0, 0, 1);
     }
     
     protected void render(GL gl)
     {
         // Code to render with OpenGL ES...
         GL11 gl11 = (GL11)gl;
         gl11.glClear(GL10.GL_COLOR_BUFFER_BIT | GL10.GL_DEPTH_BUFFER_BIT);
     }
 }
 

Adding a GLField to the Screen

In this scenario the GLField is being added to the users screen. The field's GLField.initialize(GL) is called once on startup and the GLField.update() and GLField.render(GL) methods are called on every frame on paint's.

If the field is set to the default frame rate of 0, users must invalidate the screen themselves forcing a frame (paint, update and render) to be processed on UI event dispatch thread.

This is more ideal for developers who want to use OpenGL ES to render rich 2D/3D content in a more static UI application that may also have other types of fields.

 public class MyScreen extends MainScreen
 {
     public MyScreen()
     {
         // Add the OpenGL ES field to the screen
         add(new MyGLField(GLField.VERSION_1_1));
         
         // Add some other fields to the screen
         add(new ButtonField("Exit"));
     }
 }
 
Layout

If GLField is inside a scrollable manager then width or height may be passed to layout as Integer.MAX_Value/2 to indicate that the field is being laid out inside a manger with infinite virtual extent. If the extent of the GLField is set too large then an error will be returned via GLField.errorOccurred(int, int). Typically GLField will not be larger than the screen.

 protected void layout(int width, int height)
 {
     // Clamp the GLField to the display size
     setExtent(Math.min(width, Display.getWidth()), Math.min(height, Display.getHeight()));
 }
 

Advanced OpenGL ES Usage (Games/Animation)

For a more dynamic usage such as a game or very rich animated viewport a user will instantiate a GLField and then set a specified target frame rate of 20-30 FPS.

This will cause the GLField.update() and GLField.render(GL) methods to be invoked from a separate rendering thread rather than the ui event dispatch thread.

Implementing an Animated GLField

 public class MyGameGLField extends GLField
 {
     protected void layout(int width, int height)
     {
         // Sets the field dimensions to fullscreen
          setExtent(Math.min(width, Display.getWidth()), Math.min(height, Display.getHeight()));
     }
     
     protected void initialize(GL gl)
     {   
         GL11 gl11 = (GL11)gl;
         gl11.glClearColor(0, 0, 0, 1);
         
         // Initialize the scene with OpenGL ES 1.1
         intializeScene(gl11);
     }
     
     protected void update()
     {
         // Animate our scene.
         animateScene();
     }
     
     protected void render(GL gl)
     {
         GL11 gl11 = (GL11)gl;
         gl11.glClear(GL10.GL_COLOR_BUFFER_BIT | GL10.GL_DEPTH_BUFFER_BIT);
         
         // Render the scene with OpenGL ES 1.1
         renderScene(gl11)
     }
 }
 

Adding an animated GLField to a FullScreen

 public class MyGameScreen extends FullScreen
 {
     public MyGameScreen()
     {
         // Specify a style/hint which disables ui sychronization.
         GLField field = new MyGLField(GLField.VERSION_1_1, GLField.DISABLE_SURFACE_SYNC_HINT);
         field.setTargetFrameRate(30);
         
         // Add the fullscreen field to the screen
         add(field);
     }
 }
 

Animating Application Fields

In many animated applications you will want your separate render thread to wait until an event occurs which required rendering/drawing to occur. A developer should call GLField.setTargetFrameRate(int) passing 0 when there are no changes to be rendered. This causes the fields rendering thread to wait. Subsequently calling GLField.setTargetFrameRate(int) with a value > 0 will notify the thread to wake up and continue throttled frame rendering where GLField.update() and GLField.render(GL) calls will continue.

Threading and UI Interaction

When calling GLField.setTargetFrameRate(int) with a value > 0, the field will run frame operations on a separate thread. Developers must be conscious to protect against locking up the UI in any UI Interaction processing methods such as synchronizing on the UI event dispatch thread.

All UI Interaction processing within the following methods should consider processing with invokeLater:

Since:
BlackBerry API 6.0.0

Field Summary
static long DISABLE_SURFACE_SYNC_HINT
          Style flag used to indicate that if in fullscreen, we would like to disable surface sychronization with the ui.
static int ERROR_CHOOSE_CONFIG
          Indicates an error was received when choosing a configuration.
static int ERROR_COPY_BUFFERS
          Indicates an error was received swapping the surface buffer to the display.
static int ERROR_CREATE_CONTEXT
          Indicates an error was received during context creation.
static int ERROR_CREATE_SURFACE
          Indicates an error was received during surface creation.
static int ERROR_GET_DISPLAY
          Indicates an error was received when trying to get the display.
static int ERROR_INIT_DISPLAY
          Indicates an error was received when initializing the display.
static int ERROR_MAKE_CURRENT
          Indicates an error was received when trying to make current the display, surface and context.
static int ERROR_NO_CONFIGS
          Indicates an error was received due to no available configurations.
static int ERROR_SWAP_BUFFERS
          Indicates an error was received swapping the surface buffer to the display.
static int ERROR_WAIT_CLIENT
          Indicates an error was received waiting for the client (api) to be finished/flushed.
static int ERROR_WAIT_NATIVE
          Indicates an error was received waiting for the native engine.
static int VERSION_1_1
          Constant to indicate to use OpenGL ES 1.1 as the version.
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Constructor Summary
protected GLField(int version)
          Creates a new GLField for the specified version of OpenGL ES.
protected GLField(int version, long style)
          Creates a new GLField for the specified version of OpenGL ES.
 
Method Summary
protected  void errorOccurred(int error, int eglError)
          Notifies this field that the given error has occurred.
 int getCurrentFrameRate()
          Gets the current frame rate for the field.
protected  int getPreferredColorBufferSize()
          Gets the preferred color buffer size of the underlying EGL surface.
 int getTargetFrameRate()
          Gets the target frame rate for the field.
protected abstract  void initialize(GL gl)
          Initializes this OpenGL field using the given OpenGL handle.
protected  void onDisplay()
          All users implementing this function must call super.onDisplay() to ensure proper functionality.
protected  void onExposed()
          Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.
protected  void onObscured()
          Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack.
protected  void onUndisplay()
          Invoked when the screen this field is attached to is popped off the display stack.
protected  void onVisibilityChange(boolean visible)
          This method is called when the field's visibility changes.
protected  void paint(Graphics graphics)
          Invoked by the framework to redraw a portion of this field.
protected abstract  void render(GL gl)
          Renders the contents of this OpenGL field using the given OpenGL handle.
 void setTargetFrameRate(int framesPerSecond)
          Sets the target frame rate for the field.
protected  void sizeChanged(GL gl, int width, int height)
          Called when the field and underlying surface is resized.
protected  void update()
          This method is intended to help separate the update logic code from your rendering/drawing code.
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onFocus, onMenuDismissed, onMenuDismissed, onUnfocus, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

DISABLE_SURFACE_SYNC_HINT

public static final long DISABLE_SURFACE_SYNC_HINT
Style flag used to indicate that if in fullscreen, we would like to disable surface sychronization with the ui.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

VERSION_1_1

public static final int VERSION_1_1
Constant to indicate to use OpenGL ES 1.1 as the version.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_CREATE_CONTEXT

public static final int ERROR_CREATE_CONTEXT
Indicates an error was received during context creation.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_CREATE_SURFACE

public static final int ERROR_CREATE_SURFACE
Indicates an error was received during surface creation.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_MAKE_CURRENT

public static final int ERROR_MAKE_CURRENT
Indicates an error was received when trying to make current the display, surface and context.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_GET_DISPLAY

public static final int ERROR_GET_DISPLAY
Indicates an error was received when trying to get the display.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_INIT_DISPLAY

public static final int ERROR_INIT_DISPLAY
Indicates an error was received when initializing the display.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_CHOOSE_CONFIG

public static final int ERROR_CHOOSE_CONFIG
Indicates an error was received when choosing a configuration.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_NO_CONFIGS

public static final int ERROR_NO_CONFIGS
Indicates an error was received due to no available configurations.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_WAIT_NATIVE

public static final int ERROR_WAIT_NATIVE
Indicates an error was received waiting for the native engine.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_WAIT_CLIENT

public static final int ERROR_WAIT_CLIENT
Indicates an error was received waiting for the client (api) to be finished/flushed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_SWAP_BUFFERS

public static final int ERROR_SWAP_BUFFERS
Indicates an error was received swapping the surface buffer to the display.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ERROR_COPY_BUFFERS

public static final int ERROR_COPY_BUFFERS
Indicates an error was received swapping the surface buffer to the display.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Constructor Detail

GLField

protected GLField(int version)
Creates a new GLField for the specified version of OpenGL ES.

Parameters:
version - The OpenGL ES version to request (one of the VERSION constants).
Throws:
IllegalArgumentException - if version is not a valid VERSION constant.
UnsupportedOperationException - if the device does not support the specified version of OpenGL ES.
Since:
BlackBerry API 6.0.0

GLField

protected GLField(int version,
                  long style)
Creates a new GLField for the specified version of OpenGL ES.

Parameters:
version - The OpenGL ES version to request (one of the VERSION constants).
style - The field style. Use GLField.DISABLE_SURFACE_SYNC_HINT for fullscreen games.
Throws:
IllegalArgumentException - If version is not a valid VERSION constant.
UnsupportedOperationException - If the device does not support the specified version of OpenGL ES.
Since:
BlackBerry API 6.0.0


Method Detail

initialize

protected abstract void initialize(GL gl)
Initializes this OpenGL field using the given OpenGL handle.

This method is called once when the field is initialized and may be called subsequently if the EGLContent is lost due to power management.

Parameters:
gl - The OpenGL handle that this field should use to initialize itself.
Since:
BlackBerry API 6.0.0

update

protected void update()
This method is intended to help separate the update logic code from your rendering/drawing code. It is always called in the frame just prior to the render(GL gl) method call.

If the target framerate is > 0, then this method is called at an interval of the specified target frame rate from a separate thread. If the target framerate is 0, then it is called from the event dispatch thread.

Since:
BlackBerry API 6.0.0

render

protected abstract void render(GL gl)
Renders the contents of this OpenGL field using the given OpenGL handle.

Parameters:
gl - The OpenGL handle that this field should use to render itself.
Since:
BlackBerry API 6.0.0

getPreferredColorBufferSize

protected int getPreferredColorBufferSize()
Gets the preferred color buffer size of the underlying EGL surface.

Returns:
The preferred color buffer size.
Since:
BlackBerry API 6.0.0

sizeChanged

protected void sizeChanged(GL gl,
                           int width,
                           int height)
Called when the field and underlying surface is resized.

The default implementation for this method sets the OpenGL ES viewport to the values glViewport(0, 0, width, height).

Subclasses can override this method to provide additional functionality. For example a common use of this method is to specify a new OpenGL ES projection matrix.

Parameters:
gl - The OpenGL ES render context.
width - The width of the viewport.
height - The height of the viewport.
Since:
BlackBerry API 6.0.0

errorOccurred

protected void errorOccurred(int error,
                             int eglError)
Notifies this field that the given error has occurred.

Parameters:
error - The error code.
eglError - The EGL error.
Since:
BlackBerry API 6.0.0

setTargetFrameRate

public final void setTargetFrameRate(int framesPerSecond)
Sets the target frame rate for the field.

This method sets the target frame rate for the field to the given number of frames per second. The frame rate controls how often the update and render methods are called. The value passed may not reflect the actual realized frame rate, which may be the case if the application cannot execute fast enough to achieve the requested frame rate. The current/running frame rate of the field can be queried with the GLField.getCurrentFrameRate() method.

A positive value will result in the field attempting to call the update and render methods automatically at a rate that is approximately equal to the specified value. It is generally a good idea to pick the smallest value possible while still achieving acceptable performance here in order to minimize CPU and battery consumption. An acceptable range for most real-time applications is a value of 20-30.

A value of zero will disable automatic updates and rendering. When disabled, the field's GLField.update() method is not called automatically and screen updates should be controlled by calling Field.invalidate().

Parameters:
framesPerSecond - The target frame rate for the field. The default value is 0.
Throws:
IllegalArgumentException - If framesPerSecond is < 0.
Since:
BlackBerry API 6.0.0

getTargetFrameRate

public final int getTargetFrameRate()
Gets the target frame rate for the field.

Returns:
The target frame rate for the field.
See Also:
GLField.setTargetFrameRate(int)
Since:
BlackBerry API 6.0.0

getCurrentFrameRate

public final int getCurrentFrameRate()
Gets the current frame rate for the field.

This method returns the current frame rate. The value returned represents the actual current running frame rate, which is the number of times per second the update and render methods are being called. This value may be different than the value that was passed to setTargetFrameRate. This method always returns zero when the target frame rate is set to zero.

Returns:
The current frame rate.
Since:
BlackBerry API 6.0.0

onDisplay

protected void onDisplay()
All users implementing this function must call super.onDisplay() to ensure proper functionality.

Overrides:
onDisplay in class Field
See Also:
Screen.onDisplay()
Since:
BlackBerry API 6.0.0

onUndisplay

protected void onUndisplay()
Description copied from class: Field
Invoked when the screen this field is attached to is popped off the display stack.

The complementing callback is Field.onDisplay().

Overrides:
onUndisplay in class Field
See Also:
Screen.onUndisplay()
Since:
BlackBerry API 6.0.0

onVisibilityChange

protected void onVisibilityChange(boolean visible)
Description copied from class: Field
This method is called when the field's visibility changes.

Whenever an event occurs that changes the value returned from isVisible this method is called. This includes when the application is brought to the foreground or background, when fields are added and removed, and when screens are pushed or popped.

UI calls that affect the field hierarchy or screen stack should not be called from this method. These changes can be done by using Application.invokeLater.

Note that in some circumstances this method may notify of a change that is not yet reflected in a call to Field.isVisible(), for example, this method may be called with visible as false, but isVisible still returns true.

Overrides:
onVisibilityChange in class Field
Parameters:
visible - True if the field has just become visible; otherwise, false.
See Also:
Field.onVisibilityChange(boolean)
Since:
BlackBerry API 6.0.0

onObscured

protected void onObscured()
Description copied from class: Field
Invoked when the screen this field is attached to is obscured by a new screen pushed on the display stack.

The complementing callback is Field.onExposed().

Overrides:
onObscured in class Field
See Also:
Screen.onObscured()
Since:
BlackBerry API 6.0.0

onExposed

protected void onExposed()
Description copied from class: Field
Invoked when the screen this field is attached to is revealed by a screen getting popped off the display stack.

The complementing callback is Field.onObscured().

Overrides:
onExposed in class Field
See Also:
Screen.onExposed()
Since:
BlackBerry API 6.0.0

paint

protected void paint(Graphics graphics)
Description copied from class: Field
Invoked by the framework to redraw a portion of this field.

This is an abstract method; any class that extends Field must implement this method appropriate to its needs.

A field's manager invokes this method when an area of this field has been marked as invalid. All painting should be done in field-local coordinates (for example, 0,0 is the top left corner of the field's pane).

The clipping rectangle is available (in local coordinates) through Graphics.getClippingRect(). You can use this rectangle to determine the minimal amount of drawing required to satisfy the paint request. Large controls should make use of this for more efficient painting, particularly during scroll operations.

Preconditions for the paint method
Routines that invoke this method on a field ensure that this.getFont() == graphics.getFont() and that the appropriate clipping rect and transformation stack are set up, so that this method draws on the appropriate area of this field.

Should you implement a layout manager (for example) of your own, be aware that you must ensure these conditions are met before invoking this method in child Fields.

Specified by:
paint in class Field
Parameters:
graphics - Graphics context for drawing in this field.
See Also:
Field.paint(Graphics)
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.