net.rim.device.api.openvg
Class VGField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.openvg.VGField

public abstract class VGField
extends Field

Defines an abstract OpenVG Field.

Overview

Extending this class makes it much easier to write OpenVG applications. This VGField implementation contains optimized code to:

• Simplify EGL lifecycle management for EGLContext and EGLSurface objects.
• Simplify EGL sychronization of EGLContext and EGLSurface objects.
• Simplify EGL error handling.
• Simplify UI buffering in special cases such as menus, popup dialogs, virtual keyboard, etc.
• Support throttled rendering in a separate thread supporting smooth rendering for games and animation.

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

Basic OpenVG Usage (UI)

Implementing a VGField

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());
     }
 }
 

Adding a VGField to the Screen

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"));
     }
 }
 

Advanced OpenVG Usage (Games/Animation)

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.

Implementing an Animated VGField

 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)
     }
 }
 

Adding an animated VGField to a FullScreen

 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);
     }
 }
 

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 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.

Threading and UI Interaction

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)

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 OpenVG 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	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 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 OpenVG 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

VGField

protected VGField(int version)

Creates a new VGField for the specified version of OpenVG.

Parameters:

version - The OpenVG 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 OpenVG.

Since:

BlackBerry API 6.0.0

VGField

protected VGField(int version,
                  long style)

Creates a new VGField for the specified version of OpenVG.

Parameters:

version - The OpenVG version to request (one of the VERSION constants).

style - The field style.

Throws:

IllegalArgumentException - If version is not a valid VERSION constant.

UnsupportedOperationException - If the device does not support the specified version of OpenVG.

Since:

BlackBerry API 6.0.0

Method Detail

initialize

protected abstract void initialize(VG vg)

Initializes this OpenVG field using the given OpenVG 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:

vg - The OpenVG 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(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.

Since:

BlackBerry API 6.0.0

render

protected abstract void render(VG vg)

Renders the contents of this OpenVG field using the given OpenVG handle.

Parameters:

vg - The OpenVG 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(VG vg,
                           int width,
                           int height)

Called when the field and underlying surface is resized.

Subclasses can override this method to execute logic when the field and underlying surface is resized. The default implementation of this method does nothing.

Parameters:

vg - The OpenVG 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 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().

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:

VGField.setTargetFrameRate(int)

Since:

BlackBerry API 6.0.0

getCurrentFrameRate

public final int getCurrentFrameRate()

Retrieves 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