net.rim.device.api.ui.Field
net.rim.device.api.openvg.VGField
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
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
may be called subsequently if the EGLContent is lost due to memory management.
The VGField.update() and VGField.render(VG) methods are called
once every frame.
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"));
}
}
To make the background of a VGField transparent,
pass the VGField.TRANSPARENT style bit and then set the VG_CLEAR_COLOR parameter,
specifying an alpha component less than 1 to configure the degree of transparency.
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.
public class MyGameVGField extends VGField
{
private static final float[] MY_CLEAR_COLOR = new float[] { 0.6f, 0.8f, 1.0f, 1.0f };
public MyGameVGField(int version)
{
super(version);
}
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()
{
VGField field = new MyVGField(VGField.VERSION_1_1);
field.setTargetFrameRate(30);
// Add the fullscreen field to the screen
add(field);
}
}
VGField.MIXED_MODE_RENDERING. Your game will save time by skipping UI synchronization.
VGField.TRANSPARENT unless you need your VGField to be transparent, such as in an augmented reality app.
VGField.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 change while the game is running.
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.
| 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 VGField is transparent and blended with the fields beneath it. |
|
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()
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(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 long MIXED_MODE_RENDERING
public static final long TRANSPARENT
Pass this flag if you need fields below the VGField to be visible, such as in an augmented reality application where the VGField will be drawn on top of other fields.
Transparent VGFields 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 OpenVG scene.
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()
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