JSR 287

Rich Media Applications for Mobile with Scalable Vector Graphics


Table of Contents

Introduction to SVG Tiny 1.2 and JSR 287
Use cases for JSR 287 API
Entertainment
Map visualization
2D games
Rich media and navigation applications
Scalable UI
Enterprise applications
Serialization
JSR 287 API and architecture
The SVG document rendering API
"One-shot" mode
"Player" mode
The SVG DOM manipulation API
The immediate mode vector graphics API
Summary
References

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

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.

JSR 226: Scalable 2D Vector Graphics API for J2ME

JSR 287: Scalable 2D Vector Graphics API 2.0 for J2ME

W3C SVG Tiny 1.2 Specification

OpenVG - The Standard for Vector Graphics Acceleration (Informative)

Java and SVG documentation at Forum Nokia.