net.rim.device.api.ui.Field
net.rim.device.api.opengles.GLField
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class GLField
Defines an abstract class that you can subclass to create an OpenGL ES field.
GLField makes it much easier to write OpenGL ES applications.
This GLField class includes code that is optimized to:
EGLContext and EGLSurface objects.EGLContext and EGLSurface objects.
If you create a field by extending GLField you do not have to
write code to initialize EGL.
To extend the GLField class you must implement the layout,
initialize, and render methods. The GLField.initialize(GL)
method is invoked once during startup and may be called subsequently if the EGLContent is
lost due to memory management. The GLField.update() and GLField.render(GL)
methods are invoked once per frame.
public class MyGLField extends GLField
{
protected void layout(int width, int height)
{
// Set field dimensions
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);
}
}
This is a good choice if you want to use OpenGL ES to render 2D or 3D content in a standard UI application that includes other types of fields.
public class MyScreen extends MainScreen
{
public MyScreen()
{
add(new MyGLField(GLField.VERSION_1_1));
// Add another field to the screen
add(new ButtonField("Exit"));
}
}
If you use a GLField inside a scrollable manager, you can
specify Integer.MAX_Value for the value of the width
or height parameters of layout() to indicate that
the field is in a manager with infinite virtual extent.
If you set the extent of a GLField too large, an error is returned by
GLField.errorOccurred(int, int). Typically, a GLField should not
be larger than the screen it appears on.
protected void layout(int width, int height)
{
// Clamp extent of field to the display size
setExtent(Math.min(width, Display.getWidth()), Math.min(height, Display.getHeight()));
}
To make the background of a GLField transparent,
pass the GLField.TRANSPARENT style bit and then call GL20.glClearColor(float, float, float, float),
specifying an alpha component less than 1 to configure the degree of transparency.
To use a GLField in a game or an animated viewport, you
instantiate the field and then set a specified target frame rate of 20-30 FPS.
public class MyGameGLField extends GLField
{
public MyGameGLField(int version)
{
super(version);
}
protected void layout(int width, int height)
{
// Set 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()
{
animateScene();
}
protected void render(GL gl)
{
GL11 gl11 = (GL11)gl;
gl11.glClear(GL10.GL_COLOR_BUFFER_BIT | GL10.GL_DEPTH_BUFFER_BIT);
renderScene(gl11)
}
}
FullScreen
public class MyGameScreen extends FullScreen
{
public MyGameScreen()
{
GLField field = new MyGameGLField(GLField.VERSION_1_1);
field.setTargetFrameRate(30);
// Add the fullscreen sized field to the screen
add(field);
}
}
GLField.MIXED_MODE_RENDERING. Your game will save time by skipping UI synchronization.
GLField.TRANSPARENT unless you need your GLField to be transparent, such as in an augmented reality app.
GLField.setTargetFrameRate(int) instead of manually throttling your rendering yourself.
30 fps is generally the lower bound for smooth real-time graphics.
60 fps is the upper limit because of the LCD refresh rate.
A higher fps will consume more battery power. The frame rate can be changed while the game is running.
In many animated applications you want your rendering thread to wait until
an event occurs that indicates that a frame needs to be drawn. You can
call GLField.setTargetFrameRate(int) with a parameter value of 0 if there are
no changes to render.
This causes the rendering thread to wait. Subsequently calling GLField.setTargetFrameRate(int)
with a value > 0 notifies the thread to wake up and continue throttled frame rendering
by repeatedly invoking GLField.update() and GLField.render(GL).
| Field Summary | ||
|---|---|---|
static long |
DISABLE_SURFACE_SYNC_HINT
Deprecated. This is now the default setting, pass MIXED_MODE_RENDERING to enable surface synchronization. |
|
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 long |
MIXED_MODE_RENDERING
Style flag used to indicate that we would like to enable surface synchronization with the ui. |
|
static long |
TRANSPARENT
Style flag used to indicate that this GLField is transparent and blended with the fields beneath it. |
|
static int |
VERSION_1_1
Constant to indicate to use OpenGL ES 1.1 as the version. |
|
static int |
VERSION_2_0
Constant to indicate to use OpenGL ES 2.0 as the version. |
|
| 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. |
|
protected int |
getPreferredDepthBufferSize()
Gets the preferred depth 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()
Invoked when the screen this field is attached to is pushed onto the display stack. |
|
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)
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 java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final long DISABLE_SURFACE_SYNC_HINT
public static final long MIXED_MODE_RENDERING
public static final long TRANSPARENT
Pass this flag if you need fields below the GLField to be visible, such as in an augmented reality application where the GLField will be drawn on top of other fields.
Transparent GLFields incur a performance overhead because they need to be blended with the pixels below.
This style flag should not be confused with transparency within the OpenGL scene.
public static final int VERSION_1_1
public static final int VERSION_2_0
public static final int ERROR_CREATE_CONTEXT
public static final int ERROR_CREATE_SURFACE
public static final int ERROR_MAKE_CURRENT
public static final int ERROR_GET_DISPLAY
public static final int ERROR_INIT_DISPLAY
public static final int ERROR_CHOOSE_CONFIG
public static final int ERROR_NO_CONFIGS
public static final int ERROR_WAIT_NATIVE
public static final int ERROR_WAIT_CLIENT
public static final int ERROR_SWAP_BUFFERS
public static final int ERROR_COPY_BUFFERS
| Constructor Detail |
|---|
protected GLField(int version)
version - The OpenGL ES version to request (one of the VERSION constants).
IllegalArgumentException - if version is not a valid VERSION constant.
UnsupportedOperationException - if the device does not support the specified version of OpenGL ES.
protected GLField(int version,
long style)
version - The OpenGL ES version to request (one of the VERSION constants).style - The field style. Use GLField.MIXED_MODE_RENDERING when drawing with software graphics in paint().
IllegalArgumentException - If version is not a valid VERSION constant.
UnsupportedOperationException - If the device does not support the specified version of OpenGL ES.| Method Detail |
|---|
protected abstract void initialize(GL gl)
This method is called once when the field is initialized and may be called subsequently if the EGLContent is lost due to power management.
gl - The OpenGL handle that this field should use to initialize itself.protected void update()
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.
protected abstract void render(GL gl)
gl - The OpenGL handle that this field should use to render itself.protected int getPreferredColorBufferSize()
Override this method to choose a preferred color buffer size.
protected int getPreferredDepthBufferSize()
Override this method to choose a preferred depth buffer size.
If the depth buffer size is 16, GLField will create a stencil buffer of size 4.
If the depth buffer size is 24, GLField will create a stencil buffer of size 8.
protected void sizeChanged(GL gl,
int width,
int height)
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.
gl - The OpenGL ES render context.width - The width of the viewport.height - The height of the viewport.
protected void errorOccurred(int error,
int eglError)
error - The error code.eglError - The EGL error.public final void setTargetFrameRate(int framesPerSecond)
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().
framesPerSecond - The target frame rate for the field. The default value is 0.
IllegalArgumentException - If framesPerSecond is < 0.public final int getTargetFrameRate()
GLField.setTargetFrameRate(int)public final int getCurrentFrameRate()
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.
protected void onDisplay()
FieldThis method is invoked by the system after the screen is pushed onto the stack and layout has been done, but before any painting occurs.
The complementing callback is #onUiEngineAttached.
onDisplay in class FieldField.onDisplay()protected void onUndisplay()
Field The complementing callback is Field.onDisplay().
onUndisplay in class FieldField.onUndisplay()protected void onVisibilityChange(boolean visible)
Field Whenever an event occurs that changes the value returned from
Field.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 isVisible. For example,
this method may be called with the visible parameter as
false, but isVisible still returns
true.
onVisibilityChange in class Fieldvisible - If true the field has just become visible, if
false the field has not just become visible.Field.onVisibilityChange(boolean)protected void onObscured()
Field The complementing callback is Field.onExposed().
onObscured in class FieldScreen.onObscured()protected void onExposed()
Field The complementing callback is Field.onObscured().
onExposed in class FieldScreen.onExposed()protected void paint(Graphics graphics)
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() returns an equivalent value to
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.
paint in class Fieldgraphics - The graphics context for drawing in this field.Field.paint(Graphics)
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal