| Exit Print View | |
Oracle® Java Micro Edition Embedded Client Reference Guide, Version 1.0 |
|
Part II Java Virtual Machine Reference
4. Java Virtual Machine Capabilities
8. External PBP Porting Layer Plugin
8.5 Java VM Shutdown With PBP Application
The Oracle Java ME Embedded Client has a feature to plug in a 3rd party porting interface for Personal Basis Profile (PBP) 1.1. This feature implements a framework named JGFX. The JGFX framework was designed to best leverage the commonalities between different graphics library ports for PBP and also allow 3rd party plugins implementing the native interfaces required to simply PBP to be easily integrated. The native porting layer can either be plugged in as a shared library or as a static archive.
The native porting layer plugin might implement a set of javacalls and additionally some algorithms to best leverage the underlying graphics platform capabilities. The set of javacalls must be implemented, while the algorithms may or may not be implemented depending on platform capabilities.
Note - In version 1.0 the only available target is headless, therefore applications developed with PBP libraries can only be run with the SDK and the emulator.
As mentioned above, a 3rd party PBP porting layer must implement a set of javacall APIs which the core PBP implementation uses to achieve functionalities required from the native platform. These javacalls implement very specific functionalities and below is a brief description of each one of them.
jgfx_javacall_open_screen: Method to initialize screen, registering algorithms for the primary display surface.
jgfx_javacall_set_resolution: Method to set screen resolution.
jgfx_javacall_release_surface: Method to release native window/surface.
jgfx_javacall_reset_context: Method to reset platform specific context pointer, context pointer could point any porting specific data structure.
jgfx_javacall_destroy_context: Method to destroy the context pointer.
jgfx_javacall_set_surface_color_parms: Method to set up AlphaComposite rules, foreground/background colors of a native surface/window.
jgfx_javacall_sync_clip: Method to set/update clip region of a native surface/window.
jgfx_javacall_create_font: Method to create/register a font with the native Graphics system.
jgfx_javacall_destroy_font: Method to destroy/unregister a font created/registered with a native Graphics system.
jgfx_javacall_get_string_width: Method to get width of an input string.
jgfx_javacall_get_string_bounds: Method to get dimensions of the bounding rectangle for an input string.
jgfx_javacall_init_events: Method to initialize input event module (key events, mouse events, etcetera).
The 3rd party PBP porting layer plugin can implement some algorithms which are used by the PBP core to best leverage the graphics capabilities of a platform. Implementing these algorithms is optional, but the porting layer plugin may implement them for more optimized PBP implementation, such as leveraging graphics hardware accelerations and related features.
In situations where these algorithms are not implemented, PBP uses its software modules to implement the functionality achieved by these algorithms. There is a facility to associate capabilities of each algorithms. If one algorithm is not capable of handling a certain case then the core PBP JGFX framework leverages its software module to provide the missing capability.
Brief descriptions of these algorithms follow:
JGFXAlg_CreateSurface: Algorithm to create off-screen surface(s). If it is not implemented PBP uses memory allocation modules at runtime to allocate memory to hold surfaces.
JGFXAlg_ReleaseSurface: Algorithm to release off screen surface(s). If an implementation provides an algorithm to create a surface, then it must provide an algorithm to release it as well.
JGFXAlg_GetSurfaceMemory: Algorithm to get the handle to a surface memory. On some platforms, surface memory is retrieved by locking the surface.
JGFXAlg_ReleaseSurfaceMemory: Algorithm to release the handle to a surface memory. On some platforms, the handle to surface memory is retrieved by locking the surface. This method is supposed to unlock surface memory during release operation.
JGFXAlg_GetPixel: Algorithm to get pixel value in raw pixel format. A platform may have a different mechanism of storing pixel data or even have APIs to access pixel information rather than direct access to the screen or window. In such cases implementation of this algorithm is necessary.
JGFXAlg_GetPixels: Algorithm to get an array of pixel values in raw pixel format. Some platforms may have faster ways of accessing this information rather than going over all the members of the array list. Others might iterate over all the elements and get the data.
JGFXAlg_SetPixel: Algorithm to set a pixel value in raw pixel format. As in the case of JGFXAlg_GetPixel, JGFXAlg_SetPixel might need to use a special API to access this information on some platforms. On others, the way pixel information is stored could be different. It is better if the porting plug-in defines this algorithm.
JGFXAlg_SetPixels: Algorithm to set an array of pixel values in raw pixel format. Some platforms have faster ways of achieving this other than iterating over all the elements of the array.
JGFXAlg_GetColor: Algorithm to get the color value of a pixel in ARGB8888 format. For many platforms functionality achieved by this algorithm could be the same as JGFXAlg_GetPixel. For color model other than ARGB8888, the implementation must convert the color to ARGB8888 format.
JGFXAlg_SetColor: Algorithm to set color value of a pixel in ARGB8888 format. For many platforms the functionality could be the same as JGFXAlg_SetPixel. For platforms that support a color models other than ARGB8888, the implementation needs to convert the color from ARGB8888 mode to the platform color model.
JGFXAlg_DrawLine: Algorithm to draw a line. It can be any form, and is not restricted to vertical or horizontal. The implementation can leverage any hardware acceleration that might be present on the platform for faster rendering.
JGFXAlg_DrawLines: Algorithm to draw a set of lines with specified array of coordinates. Some platforms may have a graphics library API to achieve this. Others the implementation must iterate over the coordinates and draw all the lines.
JGFXAlg_DrawRect: Algorithm to draw a rectangle with specified coordinates. Absence of this algorithm directs JGFX core to draw a rectangle using the put pixel mechanism. It is a good idea to implement this algorithm to leverage any hardware acceleration available on the platform for this operation.
JGFXAlg_FillRect: Algorithm to draw a filled rectangle with specified coordinates. In many platforms this operation is hardware accelerated, so a platform specific implementation for this algorithm is highly desirable.
JGFXAlg_FillRectRGB: Algorithm to draw a filled rectangle with specified coordinates and color. Like the FillRect operation, this operation is hardware-accelerated on many platforms. In such cases it is highly desirable to have a platform-specific implementation for this algorithm.
JGFXAlg_DrawArc: Algorithm to draw or fill an arc with specific coordinates and angles. If native graphics library supports this operation then it is ideal to implement this algorithm.
JGFXAlg_RoundRect: Algorithm to draw or fill a rounded rectangle with specified coordinates for the rectangle and horizontal and vertical diameters of the arc at the four corners. If a native graphics library supports this operation, then it is desirable to implement this algorithm to leverage any hardware acceleration facility available.
JGFXAlg_DrawString: Algorithm to draw a text string at a specific coordinate. Since different graphics platform follow different ways of rendering a text string, JGFX core expects an implementation to implement this algorithm.
JGFXAlg_LoadImage: Algorithm to load and decode images. Most graphics libraries have support for this feature and an implementation can implement this to take advantage of hardware-level decoding or any software optimizations present in the native graphics system. In absence of this algorithm, the JGFX core falls back on internal image decoders.
Implementation can also choose to implement different image decoders for GIF, JPEG and PNG. Or implement only the ones available for the native graphics platform, the others are decoded via built-in software image decoders with JVM.
JGFXAlg_Flip: Algorithm to flip the contents of the back-buffer to the front-buffer of the double-buffered surface (could be primary screen surface or double-buffered off-screen surfaces). Most graphics platforms have hardware acceleration support for this operation and it is highly desirable for the porting layer to implement this algorithm. Absence of this algorithm would force JGFX core to use pixel copy functions to flip contents of back-buffer to the front-buffer and this could be a slow process.
JGFXAlg_Blit: Algorithm to block transfer of contents from one surface to another or from one part of a same surface to the other. Usually such operations have hardware acceleration support from graphics subsystem. Since this API is used frequently, it is highly desirable to have an implementation for this algorithm with native graphics system APIs, leveraging available hardware acceleration.
JGFXAlg_StretchBlit: Algorithm to block transfer and stretch and shrink the contents from one surface to another. If the platform has hardware acceleration for these operations it is desirable to have an implementation of this algorithm to leverage hardware acceleration. Without an implementation the JGFX core uses software algorithms to achieve this functionality and it could be a slow process.
JGFXAlg_GetEvent: Algorithm to get input events on a platform from sources such as remote controller, key board, etc. Many graphics subsystems map the input events in their own suitable form and pass on these events to applications. It is desirable to implement this algorithm to suit the native graphics system.
Unlike javacalls, these algorithms must be registered at surface creation. This allows an implementation to have an algorithm registered for the primary screen surface, but not for an off-screen surface. This is useful if the graphics platform does not support the operation for off-screen surfaces.
The JGFX framework also enables the integrator to specify capabilities of each algorithm. The capabilities are as follows:
JGFX_ALGFLAG_HWACCEL = 0x00000001 /* whether the operation is hw accelerated */ JGFX_ALGFLAG_NEED_SURFMEM = 0x00000002 /* whether the operation required surface memory to be mapped */ JGFX_ALGFLAG_STRETCHFLIP = 0x00000004 /* whether the algorithm can flip pixels around while stretching */ JGFX_ALGFLAG_HANDLESCLIP = 0x00000008 /* whether the algorithm can handle clip settings */ JGFX_ALGFLAG_NEED_SW_PIXELS = 0x00000010 /* whether the algorithm needs foreground pixel to be calculated */
Depending on the capabilities attached, the JGFX core acts according to the situation when it performs the actual operation. For example, if the algorithm is not capable of handling clip regions and JGFX understands the need to render with respect to a particular clip setting, then it might handle the operation using its own software modules instead of calling the registered algorithm.
Along with these capabilities, some of the algorithms also have a facility to add the Alpha Composite rules that the algorithm supports. The possible modes are as follows:
JGFXCR_CLEAR = 0x01, JGFXCR_SRC = 0x02, JGFXCR_SRC_OVER = 0x04, JGFXCR_XOR = 0x08, JGFXCR_ALL = 0x0F,
Ideally an algorithm could support ALL of these modes, but if the algorithm lacks support for any of these rules (due to absence of platform support or something else), then the algorithm can notify JGFX core about the missing support. JGFX core then falls back on its software algorithms to implement the functionality for the missing Alpha Composite rule. For example, if an algorithm cannot implement operations in XOR mode due to lack of platform support, then JGFX can handle these operations via the software algorithm once notified.
Note - JGFX header files are not included in the release bundle, but they can be obtained from Oracle on request. They are important only if a plugin for JGFX must be implemented, otherwise they are not of much importance.
The image decoding module can use native graphics system APIs to leverage any platform support available for image decoding and thus improving performance on image decodes.
The Oracle Java ME Embedded Client implementation contains built-in Java image decoders. On graphics platforms where there is no support for image decoding as a whole or for a particular image format, the PBP implementation can still fall back on the built-in image decoders. The implementation falls back on built-in image decoders even in cases where a particular image cannot be decoded properly by the native graphics system.
The important runtime properties to control the native image decoding feature are as follows:
The default value of this property is true.
Setting this property to false disables the native image decoding module completely and forces usage of built-in Java decoders.
java.awt.NativeImageDecoding.PNG
The default value of this property is true.
Setting this property to false disables the native image decoding of PNG images and these images are decoded using built-in Java decoders.
java.awt.NativeImageDecoding.JPEG
The default value of this property is true.
Setting this property to false disables the native image decoding of JPEG images and these images are decoded using built-in Java decoders.
java.awt.NativeImageDecoding.GIF
The default value of this property is false.
Setting this property to true enables native image decoding of GIF images.
Note: This property is set to false by default, because Java image decoders for GIF images had better performance in JIT mode.
When many images are decoded and loaded to memory there is eventually a need to dispose of some of the images. It is possible to cache the decoded images on the hard disk automatically. When the image is loaded again, it is loaded directly from the cached file. This saves CPU cycles as the image is decoded only once, even if its memory is disposed.
This enhancement allows JVM to shutdown properly when a PBP application chooses to gracefully exit by meeting the following conditions:
Java Main thread exits
No User threads are alive
No components are displayable
No native events are pending to be processed
JVM cleans up all the resources allocated by itself and the application while exiting.
The purpose of this interface is to allow the BD-J implementation to BLIT Java images from native functions. It is used to implement the Frame Accurate Animation (FAA) API.
Java API java.awt.Frame.setSize() supports screen or window resolution modification. The specified width and height parameter values are used to determine the new resolution.
To comply with the BD-J specification, the Oracle Java ME Embedded Client stack has been enhanced to set the background color of the main Window to Clear.
This enhancement can affect certain interactive TCK tests, which assumes a Java SE Solid Non-Black background.
Given the PBP stack, a Java SE AWT implementation can be used to set the default background color to Light Gray. At runtime the parameter can reset the background color (in ARGB format) at JVM startup. The new background color affects the main AWT Window plus any default graphics instances that do not inherit a background color.
USAGE:
To modify the default background color, set the runtime flag:
java.awt.DefaultBackgroundColor=[0x]<32bit ARGB hex value> -Djava.awt.DefaultBackgroundColor=0xFFFF0000 (for solid Red) -Djava.awt.DefaultBackgroundColor=0x8000FF00 (for 50% Green) -Djava.awt.DefaultBackgroundColor=0x00000000 (for Clear)
The IXC generic implementation supports javax.tv.xlet.XletContext as well as javax.microedition.xlet.XletContext and can be used for javax.tv.xlet based Xlets.
The IxcRegistry implementation is generic accordingly and is integrated with com.sun.xlet.ixc package. Oracle provides an implementation for the org.dvb.io.ixc.IxcRegistry class that supports the DVB persistent storage requirements. Since the Class lacks support for the unbindAll() API, com.sun.dvb.io.ixc.IxcRegistryExtension provides this functionality.
|
