Abstract
This paper aims to provide an introduction to JSR 287 (Scalable 2D Vector Graphics API 2.0 for Java ME), its use cases, the API and architecture, and supported features.
Table of Contents
Scalable vector graphics (SVG) Tiny 1.2. specification was defined as a subset of full SVG specification targeting for example mobile devices having limited networking and device capabilities (such as memory, display size and resolution, and computational power). SVG has many advantages over raster images in mobile devices:
Mobile devices have a great number of differences for example in display resolutions. SVG provides device independence: same content renders the same quality on any device, independent of display resolution. Therefore same content can be used, within certain limits, both on desktops and mobile devices.
Due to smallish physical display size the content in mobile devices benefits from being zoomable. A vector graphics image can be zoomed without any loss of quality, or need to reload.
Although mobile network and device memories have advanced, efficiency is important for faster operation and reducing costs. SVG provides often smaller file sizes over raster images. Animation compresses approximately ten times better than on animated GIFs.
SVG provides also a way to easily create interactive content with minimal programming compared to traditional mobile software development technologies. In addition content can be animated better ways than in traditional frame based graphics rendering.
Java Micro Edition (Java ME) is used widely as software development technology in mobile devices. JSR 287 defines a specification of a Java ME API for rendering enhanced 2D vector graphics and rich media content based on SVG Tiny 1.2. The primary use cases for this API include entertainment, vector graphics-based mapping solutions, scalable user interfaces, games, enterprise applications, interactive rich media services, and other compelling vector graphics applications aimed at mobile devices. The API is primarily targeted for Java ME's MIDP (Mobile Information Device Profile) and CLDC (Connected Limited Device Configuration) environment, but it is designed to be implemented and usable also on other profiles such as PBP (Personal Basis Profile) and CDC (Connected Device Configuration) and Java SE platforms.
JSR 287 is a successor to JSR 226 (Scalable 2D Vector Graphics API for Java ME), builds on top of it and therefore remains fully backwards compatibility to JSR 226 applications. JSR 287 provides support for rendering rich vector graphics content based on SVG Tiny 1.2 features. The features include basic shapes, paths, animations, event management, audio, video, advanced text support and much more.
In addition to the ability to load and display SVG Tiny content, the API also offers powerful content modification functionality based of W3C DOM Level 3 Core to enable flexible applications with enhanced user experience. A key feature included in this JSR is the ability to serialize or "save" the DOM for content sharing applications. Using SVG to create compelling Java applications is further enabled by providing the ability to register Java handlers to graphical objects in SVG to facilitate callbacks and enhance interactivity.
JSR 287 specification provides also an optional advanced immediate-mode rendering API for vector graphics: a low-level high-performance API designed to be platform agnostic and therefore used with UI APIs of multiple profiles, for example LCDUI or AWT. The design maximizes performance by matching the API with the functions of lower level rendering engines and hardware graphics accelerators such as Khronos OpenVG API.
There are many potential mobile applications for JSR 287. Many of these have already seen daylight with the earlier version of the API (JSR 226).
Greetings, cartoons, MMS
Content creation tools for SVG are becoming more prevalent. These tools allow content creators to easily create animated cartoons. Since the resulting SVG content will be small, compact, standardized, and simple XML text, it is easy to transmit that information over networks as an MMS. Operators could also use SVG for pushing animated SVG messages to the user.
Weather, traffic updates, driving directions, restaurant guides, tourist information
SVG based maps being vector based can be easily zoomed, panned, and rotated without losing quality. SVG is also an XML based language so it is easily searchable for text. SVG supports user events such as click, mouseover, etc. in the content and thus the maps may have clickable objects or hyperlinks. This might be used to provide more information about a location on the map. SVG is a standard format that both small mobile devices and large desktops can view in the same way, the XML representation is efficiently small, the XML text can be binary encoded easily, and the XML can be compressed with standard gzip tools, which makes it a very plausible solution for map creators to use.
2D side-scroller games, game menus
SVG contains graphical elements that can be used to construct any 2D object for gaming. In addition the internal animation engine makes it easy for game developers to use short XML tags to move their game pieces around the screen. Vector based graphics would also allow for much less development time required for a game to support multiple screen resolutions. With many SVG implementations now being built on top of 2D hardware acceleration the animation frame rate for SVG is now very applicable for game development. Even 3D games might utilize SVG in building transparent menus that scale on top of their 3D layer.
Interactive Rich Media content (Graphics, Audio, Video, Text, Raster Images), TV, Set Top Box Program Guides, Menus, On-Demand and Interactive UIs
The rich media properties of SVG 1.2 in cooperation with application level handling of updates allows for advanced content creation. SVG Tiny 1.2 containing all of the different forms of media (images, audio, text, and video) makes it a very powerful interface for rich media applications. The user event handling provided by SVG makes it easy to create an interactive XML based UI that can be modified quickly and efficiently. This lends itself to building dynamic user interfaces that are updated frequently like TV program guides, favorites channel menus, channel scan menus, wait bars, etc.
Simple menus, transition effects, scalable icons, scalable windows, transparent layering.
SVG can take graphical path data along with opacity information and render that information into a buffer for a client to draw their UI with. Things like layering, transparent menus, icon placement, animating positioning of objects, animating the shapes of objects, animating text for marquees, animating opacity for focus highlighting effects, switching from landscape to portrait mode, changing screen resolution, etc., can all be done with SVG. Utilizing SVG for these types of operations can very easily save the client development time and simplify their code.
Simple day-to-day office applications, mobile email services with possible back-end infrastructure
SVG can be used as a single standard format to represent almost any digital document. There are many conversion tools that allow other document formats to be converted into SVG format. Since SVG is an efficient representation of these documents and can be compressed, it makes it a good choice for a common document format for transmission over networks. Many enterprise applications and even desktop sharing utilities could be built with this concept. The other advantage is that SVG, being scalable, can easily display the same document on both a desktop and on a mobile device.
Play SVG content, store SVG content, forward SVG content
Being able to serialize SVG content allows users to create editable, modifiable SVG on the fly. It also gives the developer the ability to take a “snapshot” of the current DOM. That “snapshot” could then be saved to a file, streamed over a network, or used for debugging their application. This use case has features in itself and in all of the other use cases as well. Another example would be giving a developer of an SVG based game the ability to save the state of the game by serializing the DOM and saving it.
JSR 287 API comprises of three main building blocks: SVG document rendering, SVG DOM (Document Object Model) manipulation and immediate mode vector graphics APIs. The specification defines Java APIs for these building blocks and groups them in the following packages:
javax.microedition.m2g: This package contains the high-level document rendering API based on W3C SVG Tiny profile. All the document-based rendering is done using the classes and interfaces defined in this package.
org.w3c.dom: This package is a subset of DOM Level 3 Core APIs. DOM Level 3 Core is the normative specification for this package. The subset is designed to be appropriate for small footprint devices, yet retain compatibility to the full DOM Core implementations.
org.w3c.dom.events: This package contains the necessary event handling interfaces that are a subset of DOM Level 3 Events APIs.
org.w3c.dom.smil: This package contains the necessary interfaces for handling SMIL animation compatible with the W3C Synchronized Multimedia Integration Language (SMIL) recommendation.
org.w3c.dom.svg: This package contains a proper subset of W3C SVG Tiny 1.2 uDOM APIs necessary for interacting and manipulating SVG Tiny 1.2 content.
org.w3c.dom.views: This package contains the DOM Views API defined by JSR 287.
javax.microedition.vectorgraphics: The Vector Graphics API supports high performance immediate mode rendering. This optional package is platform agnostic and can be used with multiple Java profiles. The design maximizes performance by matching its API to the functions of lower level rendering engines and hardware accelerators, such as OpenVG, where available.
The following sections provide an overview of these main parts of the specification: SVG document rendering, SVG DOM manipulation and immediate mode vector graphics APIs.
The high-level document rendering API based on W3C SVG Tiny profile is in javax.microedition.m2g package. All the document-based rendering is done using the classes and interfaces defined in this package. SVG content can be rendered primarily, using two high-level modes, namely the "One-shot" mode and the "Player" mode.
This mode is typically recommended for applications rendering static SVG content. It can also be used to render animations, however, the implementation of the timer needs to be provided by the application. It is particularly important to note that in this mode, embedded media playback such as embedded audio, and video, is prohibited. This is done to prevent runtime synchronization artifacts and system-level dependencies that can lead to unpredictable results.
The following example illustrates rendering of an animated SVG Image using an application/timer loop:
import javax.microedition.midlet.MIDlet;
import javax.microedition.lcdui.Canvas;
import javax.microedition.m2d.*;
class MyAnimation extends MIDlet {
private SVGImage cartoon;
private MyCanvas myCanvas = null;
private Timer myRefreshTimer = new Timer();
private TimerTask myRefreshView = null;
private ScalableGraphics gc;
...
...
/**
* MIDlet paint() method
*/
public void paint(Graphics g) {
long currentTime = System.currentTimeMillis();
cartoon.incrementTime((currentTime - startTime)/1000.0f); //startTime must be initialized in the code.
startTime = currentTime;
gc.bindTarget(g);
gc.render(0, 0, cartoon);
gc.releaseTarget();
// Schedule an update to refresh, when necessary
myRefreshTimer.schedule(myRefreshView, 100);
}
/**
* Inner class for refreshing the view.
*/
private class RefreshView extends TimerTask {
public void run() {
// Get the canvas to repaint itself.
myCanvas.repaint();
}
}
/**
* Inner class for handling the canvas.
*/
private class MyCanvas extends Canvas {
MyAnimation myAnimation;
/**
* Construct a new canvas
*/
MyCanvas(MyAnimation animation) {
myAnimation = animation;
}
/**
* Ask MyAnimation to paint itself
*/
protected void paint(Graphics g) {
myAnimation.paint(g);
}
}
This mode is recommended for applications or developers who wish to rely on the underlying implementations to handle timing and synchronization aspects. This mode is ideal for media playback and synchronization including graphics, animations, video, and audio.
This example shows rendering of SVG content using a "player" type API, also called the SVGAnimator. The SVGAnimator class handles automatic rendering of updates and animations in an SVGImage to a target user interface component:
// Create an SVGAnimator
SVGImage map = ...; // See the SVGImage documentation.
SVGAnimator svgAnimator = SVGAnimator.createAnimator(map);
// Create an SVGEventListener and set it on the animator.
MIDPSVGEventListener listener = new MIDPSVGEventListener(map, animator);
svgAnimator.setSVGEventListener(listener);
//
// SVGEventListener sample implementation. Adds a new
// circle every time a key is pressed.
//
class MIDPSVGEventListener implements SVGEventListener, Runnable {
protected SVGDocument svgDocument;
protected SVGAnimator svgAnimator;
protected Vector addToTree = new Vector();
public MIDPSVGEventListener(SVGImage svgImage, SVGAnimator animator) {
this.svgDocument = svgImage.getDocument();
this.svgAnimator = svgAnimator;
}
public void keyPressed(int keyCode) {
SVGElement circle = svgDocument.createElementNS(svgNS, "circle");
circle.setFloatTrait("cx", ...);
circle.setFloatTrait("cy", ...);
// ....
// We synchronized access to the addToTree vector because
// it is accessed from different threads. Because we do
// no know how fast this runnable is going to be scheduled
// by the animator, it is possible that multiple circles
// be created before the run() method is invoked. This explain
// why we put all the newly created circles in a Vector and why
// the run method inserts the current content of the vector
// into the SVG document.
synchronized (addToTree) {
addToTree.addElement(circle);
}
svgAnimator.invokeLater(this);
}
public run() {
synchronized (addToTree) {
for (int i = 0; i < addToTree.size(); i++) {
svgDocument.getDocumentElement().appendChild(
(SVGElement) addToTree.elementAt(i));
}
addToTree.clear();
}
}
}
The DOM APIs are in org.w3c.dom package and its subpackages. These APIs allow query and manipulation of elements in the associated SVG document.
The DOM package is a subset of DOM Level 3 Core APIs. DOM Level 3 Core is the normative specification for this package. The subset is designed to be appropriate for small footprint mobile devices, yet retain compatibility to the full DOM Core implementations. This is achieved by following:
Only two types of Node are supported: Element and Document and only a subset of methods is supported on each interface.
All other types of nodes can be thought of still being in the tree, but not accessible through these subsetted APIs.
Additional element tree traversal APIs are introduced on SVGElement interface.
It should be noted that the JSR 287 DOM APIs (in the org.w3c.dom, org.w3c.dom.events and org.w3c.dom.svg packages) are binary compatible with the SVG 1.2 Tiny DOM. This means that code compiled against the JSR 287 DOM APIs can run on a conformance implementation of the SVG 1.2 Tiny DOM.
The example in the previous section contained a basic code snippet on SVG DOM manipulation. Here's another example:
SVGSVGElement myEl = (SVGSVGElement).svgImage.getDocument().getDocumentElement(); myEl.setCurrentRotate(0); myEl.setCurrentScale(1); SVGPoint origin = myEl.getCurrentTranslate(); origin.setX(0); origin.setY(0);
The immediate mode rendering API is in javax.microedition.vectorgraphics package.
The Vector Graphics API supports high performance immediate mode rendering. This optional package is platform agnostic and can be used with multiple profiles. The design maximizes performance by matching its API to the functions of lower level rendering engines and hardware accelerators, such as OpenVG, where available. OpenVG is the basis for the terminology describing coordinate systems, transforms, shapes and paths, images, paint, colors, gradients, rendering modes and rendering attributes.
The API is designed to meet the requirements for an immediate mode that can be used in combination with the XML document based Scalable 2D Vector Graphics API 2.0 for Java ME and other graphics APIs. Applications can composite document based information and use the immediate mode API to overlay controls or other highly interactive information.
The API includes support for arbitrary shapes that can be stroked and filled with textures and gradients patterns to create rich looking graphics. All shapes and filling is scalable to enable fine details and the ability to zoom and resize the graphics to the display medium. Text formatting is supported with control of fonts, colors, and text flow. Images can be scaled and rotated to become an integral part of the display. Animated images can be used to provide a highly dynamic user interface.
The API can be used for applications such as games that require rich rendering functions and high performance graphics. In combination with other graphics packages such as OpenGL ES and the Mobile 3D API the API provides highly interactive graphics and overlays. The API is compatible with the graphics rendering targets of the Mobile Information Device Profile (MIDP) and Personal Basis Profile (PBP).
The design of the API is intended to allow application developers the flexibility to subclass from the graphics types. For example, the Shape classes can be subclassed to add application specific information and logic. For example, methods and fields could be added to retain the color of the Shape or attributes added to build the shapes and attributes into the application data structures describing the application state.
Here's an example code snippet on using immediate mode vector graphics:
...
private VectorGraphics vg = new VectorGraphics();
...
private Matrix tmpMtxA = new Matrix();
...
// Create a Path for the word balloon background.
balloonPath = new Path().
setSizeHint(7, 26).
move(20, 10).
cubic(40, 0, 200, 0, 220, 10).
smoothCubic(240, 40, 220, 50).
smoothCubic(200, 60, 170, 90).
cubic(220, 30, 40, 60, 20, 50).
smoothCubic(0, 20, 20, 10).
closePath();
...
// Draw the word balloon background.
tmpMtxA.rotate(viewMtx, 0.02f * sin, 160, 30);
vg.setShapeTransform(tmpMtxA); // Rotate slightly.
vg.setFillPaint(0xaaffffff); // Semi-transparent fill.
vg.setStrokePaint(0xff000000); // Black stroke.
vg.setStroke(balloonStroke); // Solid stroke.
vg.drawShape(balloonPath, 0, 0);
...
Scalable vector graphics provide many advantages over raster images in mobile devices, obviously on top of the list are scalability to different device capabilities and easy creation of animated interactive content. JSR 287 defines a Java ME API on top of SVG Tiny 1.2 to allow Java ME application developers to use SVG for mobile devices. The main building blocks of JSR 287 are SVG document rendering, SVG DOM manipulation and immediate mode vector graphics APIs. JSR 287 is a successor of earlier JSR 226 and adds SVG Tiny 1.2 features and the immediate mode APIs to it. JSR 287 is expected to be widely deployed in mobile devices during 2009.