|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.openvg.VGField
public abstract class VGField
Defines an abstract OpenVG Field.
Extending this class makes it much easier to write OpenVG applications.
This VGField
implementation contains optimized code to:
EGLContext
and EGLSurface
objects.EGLContext
and EGLSurface
objects.Extending this field allows developers to not have to write any code related to EGL.
At minimal a developer will extend the VGField
class and implement the following methods:
public class MyVGField extends VGField { private static final float[] MY_CLEAR_COLOR = new float[] { 0.6f, 0.8f, 1.0f, 1.0f }; protected void layout(int width, int height) { // Sets the field dimensions to 100x100 setExtent(100, 100); } protected void initialize(VG vg) { // Code to initialize any OpenVG resources... VG11 vg11 = (VG11)vg; vg11.vgSetfv(VG10.VG_CLEAR_COLOR, 4, MY_CLEAR_COLOR, 0); } protected void render(VG vg) { // Code to render with OpenVG... VG11 vg11 = (VG11)vg; vg11.vgClear(0, 0, this.getWidth(), this.getHeight()); } }
In this scenario the VGField is being added to the users screen.
The field's VGField.initialize(VG)
is called once on startup and
the VGField.update()
and VGField.render(VG)
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 OpenVG to render rich 2D content in a more static UI application that may also have other types of fields.
public class MyScreen extends MainScreen { public MyScreen() { // Add the OpenVG field to the screen add(new MyVGField(VGField.VERSION_1_1)); . // Add some other fields to the screen add(new ButtonField("Exit")); } }
For a more dynamic usage such as a game or very rich animated viewport a user will
instantiate a VGField
and then set a specified target frame rate of 20-30 FPS.
This will cause the VGField.update()
> and VGField.render(VG)
methods to be
invoked from a separate rendering thread rather than the ui event dispatch thread.
public class MyGameVGField extends VGField { private static final float[] MY_CLEAR_COLOR = new float[] { 0.6f, 0.8f, 1.0f, 1.0f }; protected void layout(int width, int height) { // Sets the field dimensions to fullscreen setExtent(width, height); } protected void initialize(VG vg) { VG11 vg11 = (VG11)vg; vg11.vgSetfv(VG10.VG_CLEAR_COLOR, 4, MY_CLEAR_COLOR, 0); // Initialize the scene with OpenVG 1.1 intializeScene(vg11); } protected void update() { // Animate our scene. animateScene(); } protected void render(VG vg) { VG11 vg11 = (VG11)vg; vg11.vgClear(0, 0, this.getWidth(), this.getHeight()); // Render the scene with OpenVG 1.1 renderScene(vg11) } }
public class MyGameScreen extends FullScreen { public MyGameScreen() { // Specify a style/hint which disables ui sychronization. VGField field = new MyVGField(VGField.VERSION_1_1, VGField.DISABLE_SURFACE_SYNC_HINT); field.setTargetFrameRate(30); // Add the fullscreen field to the screen add(field); } }
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 VGField.setTargetFrameRate(int)
passing 0 when there are no changes to be rendered.
This causes the fields thread to wait(). Subsequently calling VGField.setTargetFrameRate(int)
with a value > 0 will notify the thread to wake up and continue throttled frame rendering
where VGField.update()
and VGField.render(VG)
calls will continue.
When calling VGField.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
:
VGField.initialize(VG)
VGField.update()
VGField.render(VG)
VGField.sizeChanged(VG, int, int)
VGField.errorOccurred(int, int)
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 OpenVG 1.1 as the version. |
Constructor Summary | ||
---|---|---|
protected |
VGField(int version)
Creates a new VGField for the specified version of OpenVG. |
|
protected |
VGField(int version,
long style)
Creates a new VGField for the specified version of OpenVG. |
Method Summary | ||
---|---|---|
protected void |
errorOccurred(int error,
int eglError)
Notifies this field that the given error has occurred. |
|
int |
getCurrentFrameRate()
Retrieves 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(VG vg)
Initializes this OpenVG field using the given OpenVG 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(VG vg)
Renders the contents of this OpenVG field using the given OpenVG handle. |
|
void |
setTargetFrameRate(int framesPerSecond)
Sets the target frame rate for the field. |
|
protected void |
sizeChanged(VG vg,
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 int VERSION_1_1
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 VGField(int version)
version
- The OpenVG 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 OpenVG.protected VGField(int version, long style)
version
- The OpenVG version to request (one of the VERSION
constants).style
- The field style.
IllegalArgumentException
- If version
is not a valid VERSION
constant.
UnsupportedOperationException
- If the device does not support the specified version of OpenVG.Method Detail |
---|
protected abstract void initialize(VG vg)
This method is called once when the field is initialized and may be called subsequently if the EGLContent is lost due to power management.
vg
- The OpenVG handle that this field should use to initialize itself.protected void update()
render(VG vg)
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(VG vg)
vg
- The OpenVG handle that this field should use to render itself.protected int getPreferredColorBufferSize()
protected void sizeChanged(VG vg, int width, int height)
Subclasses can override this method to execute logic when the field and underlying surface is resized. The default implementation of this method does nothing.
vg
- The OpenVG 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 VGField.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 VGField.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()
VGField.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()
super.onDisplay()
to ensure proper functionality.
onDisplay
in class Field
Screen.onDisplay()
protected void onUndisplay()
Field
The complementing callback is Field.onDisplay()
.
onUndisplay
in class Field
Screen.onUndisplay()
protected void onVisibilityChange(boolean visible)
Field
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.
onVisibilityChange
in class Field
visible
- True if the field has just become visible; otherwise,
false.Field.onVisibilityChange(boolean)
protected void onObscured()
Field
The complementing callback is Field.onExposed()
.
onObscured
in class Field
Screen.onObscured()
protected void onExposed()
Field
The complementing callback is Field.onObscured()
.
onExposed
in class Field
Screen.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() == 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 Field
graphics
- 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-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.