|
back to j2megame.org | ||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||
Scalable 2D Vector Graphics API for J2ME (JSR-226)
See:
Description
| Packages | |
|---|---|
| javax.microedition.m2g | This package contains the core rendering part of this proposal. |
| org.w3c.dom | This package is subsetted DOM Level 3 Core APIs. |
| org.w3c.dom.events | This package contains the necessary event handling interfaces that are a subset of DOM Events Level 2 APIs. |
| org.w3c.dom.svg | The SVG Tiny 1.1 DOM API defined in this specification is subset of W3C SVG Tiny 1.2 uDOM. |
This document contains the Specification of the JSR-226 Scalable 2D Vector Graphics API for J2ME.
RESEARCH AND EVALUATION LICENSE
NOKIA CORPORATION IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE TERMS CONTAINED IN THIS LICENSE ("LICENSE"). PLEASE READ THE TERMS AND CONDITIONS OF THIS LICENSE CAREFULLY. BY ACCESSING OR USING THE SPECIFICATION YOU WILL BE BOUND BY THE TERMS OF THIS LICENSE.
JSR-226 Scalable 2D Vector Graphics API for J2METM. Specification ("Specification")
Version: 1.1
Status: Maintenance Release (MREL) Specification
Specification Lead: Nokia Corporation
Release: 2006-04-24
Copyright 2003-2006 Nokia Corporation
All rights reserved.
1. NOTICE; LIMITED LICENSE GRANTS
1.1 The Specification Lead hereby grants You a non-exclusive, non-transferable, worldwide, royalty-free, fully paid-up, limited license (without the right to sublicense) solely under intellectual property rights licensable by the Specification Lead to analyze and to use the Specification for research, evaluation, optimization and development purposes. In addition You may make a reasonable number of verbatim copies of this Specification in its entirety for Your private or internal use, as applicable, in accordance with the terms and conditions of this License.
1.2 No rights are granted under this License for internal deployment, the creation and/or distribution of implementations of the Specification for direct or indirect (including strategic) gain or advantage, the modification of the Specification (other than to the extent of Your fair use rights) or the distribution of the Specification or making the Specification available for 3rd parties.
1.3 Except as expressly set forth in this license, You acquire no right, title or interest in or to Specification or any other intellectual property licensable by the Specification Lead and no other rights are granted by implication, estoppel or otherwise. The Specification may only be used in accordance with the license terms set forth herein. This License will terminate immediately without notice from Specification Lead if You fail to comply with any provision of this License.
2 TRADEMARKS
2.1 Nokia is a registered trademark of Nokia Corporation. Nokia Corporation 's product names are either trademarks or registered trademarks of Nokia Corporation. Your access to this Specification should not be construed as granting, by implication, estoppel or otherwise, any license or right to use any marks appearing in the Specification without the prior written consent of Nokia Corporation or Nokia's licensors. No right, title, or interest in or to any trademarks, service marks, or trade names of any third parties, is granted hereunder.
2.2 You shall not be allowed to remove any of the copyright statements or disclaimers or other proprietary notices contained in the Specification and You are obliged to include the copyright statement and the disclaimers, if any, in any copies of the Specification You make.
3. DISCLAIMER OF WARRANTIES
3.1 SUBJECT TO ANY STATUTORY WARRANTIES OR CONDITIONS WHICH CAN NOT BE EXCLUDED, THE SPECIFICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OR CONDITION OF ANY KIND EITHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, AND STATUTORY ARE HEREBY DISCLAIMED. THE ENTIRE RISK ARISING OUT OF OR RELATING TO THE USE OR PERFORMANCE OF THE SPECIFICATION REMAINS WITH YOU.
3.2 THE SPECIFICATION MAY INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SPECIFICATION LEAD MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.
4. LIMITATION OF LIABILITY
4.1 TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL THE SPECIFICATION LEAD OR ITS SUPPLIERS BE LIABLE FOR ANY LOST PROFITS, LOST SAVINGS, LOST REVENUE, LOST DATA, PROCUREMENT OF SUBSTITUE GOODS, OR FOR ANY DIRECT, INDIRECT, INCIDENTIAL, SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, EVEN IF THE SPECIFICATION LEAD OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. IN ADDITION THE SPECIFICATION LEAD AND ITS SUPPLIERS WILL NOT BE LIABLE FOR ANY DAMAGES CLAIMED BY YOU BASED ON ANY THIRD PARTY CLAIM.
4.2 Some jurisdictions do not allow the exclusion of implied warranties, or the limitation for consequential damages, so Section 4.1 may not apply to You in whole, but in such case Section 4.1 will apply to You to the maximum extent permitted by applicable law.
5. EXPORT CONTROL
5.1 You shall follow all export control laws and regulations relating to Specification.
6. RESTRICTED RIGHTS LEGEND
6.1 Note to U.S. Government Users. The Specification is a "Commercial Items", as that term is defined at 48 C.F.R. 2. 101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation", as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software Documentation are being licensed to U.S. Government end users a) only as Commercial Items and b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States.
______________________________________________________________________________________________
W3C SOFTWARE LICENSE NOTICE
Parts of this Specification are derived from the following W3C Specification:
______________________________________________________________________________________________
This document is the specification of JSR 226 Scalable 2D Vector Graphics API. This API is targeted for low-end mobile devices with constraints in memory, screen size, and computational power. The goal of this specification is to define an optional API package for rendering Scalable 2D vector images, including external images in SVG format. The main target use cases of this API are map visualization, scalable icons and other applications which require scalable, animated graphics.
|
Date
|
Version
|
Description
|
|---|---|---|
|
11-Nov-2003
|
EG Initial Draft
|
Based on 2nd EG face-to-face meeting
|
|
09-Dec-2003
|
EG Draft 0.1
|
Revision based on regular EG discussions
|
|
12-Dec-2003
|
EG Draft 0.2
|
Community Review Draft for EG feedback
|
|
16-Dec-2003
|
EG Draft 0.3
|
Community Review Specification
|
|
16-Jan-2004
|
EG Draft 0.4
|
Revised based on further EG CR comments
|
|
10-Feb-2004
|
EG Draft 0.5
|
Early version of Public Review Draft
|
|
23-Feb-2004
|
EG Draft 0.6
|
Proposed Public Draft Specification
|
|
10-Mar-2004
|
EG Draft 0.7
|
Public Draft Specification
|
|
01-May-2004
|
EG Draft 0.8
|
Initial Proposed Final Draft Specification
|
|
07-May-2004
|
EG Draft 0.9
|
Revised Proposed Final Draft Specification, based on feedback from EG
|
|
22-June-2004
|
EG Draft 0.91
|
Internal revision of PFD
|
|
22-July-2004
|
EG Draft 0.92
|
Internal revision of PFD
|
|
22-Sep-2004
|
EG Draft 0.94
|
Internal revision of PFD
|
|
07-Oct-2004
|
EG Draft 0.95
|
Internal revision of PFD
|
|
13-Oct-2004
|
EG Draft 0.96
|
Internal revision of PFD
|
|
20-Oct-2004
|
EG Draft 0.97
|
Internal revision of PFD
|
|
26-Oct-2004
|
EG Draft 0.98
|
Internal revision of PFD
|
|
16-Nov-2004
|
EG Draft 0.99
|
Internal revision of PFD
|
|
22-Nov-2004
|
EG Draft 1.0
|
Internal (final) revision of PFD
|
|
27-Nov-2004
|
Version 1.0
|
Final JSR 226 Specification
|
|
01-Mar-2006
|
Version 1.01
|
Draft JSR 226 Maintenance Release (MREL) Specification
|
|
24-Apr-2006
|
Version 1.1
|
JSR 226 Maintenance Release (MREL) Specification
|
|
Term
|
Definition
|
|---|---|
|
MUST
|
The associated definition is an absolute requirement
of this specification.
|
|
MUST NOT
|
The definition is an absolute prohibition of this
specification.
|
|
SHOULD
|
Indicates a recommended practice. There may exist
valid reasons in particular circumstances to ignore this recommendation,
but the full implications must be understood and carefully weighed before
choosing a different course.
|
|
SHOULD NOT
|
Indicates a non-recommended practice. There may
exist valid reasons in particular circumstances when the particular behavior
is acceptable or even useful, but the full implications should be understood
and the case carefully weighed before implementing any behavior described
with this label.
|
|
MAY
|
Indicates that an item is truly optional.
|
The JSR-226 EG consists of the following representatives/companies.
Dirk Ambras, Siemens AG
Henric Axelsson, Ericsson Mobile Platforms
Tolga K Capin, Nokia Corporation
Peter Chen, iaSolution Inc.
Suresh Chitturi, Nokia Corporation (Editor)
Christophe Gillette, Motorola
David Girle, IBM
Andrew Girow, TinyLine
Vincent Hardy, Sun Microsystems, Inc.
Jyri Huopaniemi, Nokia Corporation
Michael Ingrassia, Nokia Corporation
Thomas Landspurg, In-Fusio SA
Michael Leone, Aplix Corporation
Simon Lewis, Symbian Ltd
Marion Lineberry, Texas Instruments Inc.
Koichi Mori, Nokia Corporation
Annika Palsson, Ericsson Mobile Platforms
Antti Rantalahti, Nokia Corporation
Daniel Rice, Sun Microsystems, Inc.
Andrew Sledd, Zoomon Mobile Solutions AB
Peter Stark, Sony Ericsson Mobile Communications AB
Ronald Stogner, SAS Institute Inc.
Philipp Suter, Esmertec AG
Ivan Wong, Motorola
Kumanan Yogaratnam, Espial Group, Inc.
The primary use cases of this API include:
The JSR-226 specification is designed based on the following requirements.
GEN.1: The API must support SVG Tiny Profile
GEN.2: The API should require less than 30 KB footprint for wrapper (ROM) implementation on top of a native SVG component.
GEN.3: The API must not contain optional parts
GEN.4: Rendering hints may be allowed(text/shape/image quality, antialiasing).
GEN.5: The API must be designed to maximize interoperability on multiple implementations
GEN.6: The API must provide functionality to load and interact with some or all features within an SVG file
ARCH.1: The API must be efficiently implementable alongside CLDC/MIDP.
ARCH.2: The API must be efficiently implementable alongside CDC/PBP/PP/JSR209 and J2SE.
ARCH.3: The API must use CLDC 1.1 as the minimum configuration for floating point support.
ARCH.4: The API must not require more underlying XML features than the SVG Tiny profile supported by the implementation.
FUNC.1: The API must support rendering SVG Tiny content.
FUNC.2: The API must allow layering and transparency/masking of multiple SVG images.
FUNC.3: The API must allow overlaying graphical objects over a raster/vector image.
FUNC.4: The API should support alpha blending of graphical objects and SVG images in arbitrary order.
FUNC.5: The API must allow zooming, panning, and rotation of SVG content.
FUNC.6: The API should support access to a specified future time within an animated SVG image.
FUNC.7: The API may be extendable to support other vector image formats.
FUNC.8: The API must support access to SVG images in file level.
FUNC.9: This API must support a limited form of access to SVG document tree (e.g. accessing an element by its id).
FUNC.10: This API must support creation of new SVG elements, but allow only basic shapes, path, group, image, text, and anchor elements.
FUNC.11: The API must support creation of new text elements.
FUNC.12: The API must support addition of new SVG elements with possible restrictions.
FUNC.13: This API must support element removal, but only elements created by the application can be removed by the application.
FUNC.14: The API must support read access to attributes that are animatable.
FUNC.15: The API must support write access to attributes that are animatable.
FUNC.16: The API should support type-based access to all the animatable attributes.
FUNC.17: The API may support string-based access to generic attributes.
FUNC.18: The API must allow event dispatching on SVG document.
FUNC.19: The API must support event registration and removal.
FUNC.20: The API must allow the application to start/stop a particular animation.
FUNC.21: The API may allow SVG engine to optimize rendering of animations.
FUNC.22: The API must allow synchronized access to the SVG Document/Image.
This document contains the JSR-226 Maintenance Release (MREL) Specification, as agreed by the JSR-226 Expert Group. It is based on the feedback received during the Maintenance Phase i.e. after the publication of JSR 226 1.0 and before the successful 30 days Public Maintenance Review period. For more information on the changes, please refer to the Change Log.
System properties are typically used to query system-level properties such as API version, profile of Mobile SVG, etc. supported by the underlying implementations by using the method System.getProperty(String key). The following system properties are required to be supported by JSR 226 implementations to ensure interoperability among JSR 226 applications.
|
Key
|
Description
|
|---|---|
|
microedition.m2g.version
|
The String returned designates the version of the Mobile Scalable 2D Vector Graphics API specification that is implemented.
It is "1.0" for this version of the specification.
|
|
microedition.m2g.svg.baseProfile
|
The String returned indicates the baseProfile of SVG that is supported by the underlying implementation. It is "tiny"
for this version of the specification.
|
|
microedition.m2g.svg.version
|
The String returned indicates the version of SVG that is supported by the underlying implementation. For example, if the
underlying SVG engine is compliant to W3C SVGT 1.1 specification the returned string would be "1.1" and for SVGT 1.2 it would be
"1.2" and so on. For more information on the version and the supported feature set please refer to W3C SVG pages
http://www.w3.org/Graphics/SVG.
|
This example illustrates rendering a simple static SVG Image. Before any rendering, the application must bind a rendering target to the ScalableGraphics context.
import javax.microedition.m2d.*;
class MapApplication extends Canvas {
private SVGImage map;
private ScalableGraphics gc;
public MapApplication() {
// Load map file
map = SVGImage.createImage(...);
gc = ScalableGraphics.createInstance();
}
public void paint(Graphics g) {
gc.bindTarget(g); //Bind the ScalableGraphics context to MIDP Graphics object.
gc.render(0, 0, map); //Render the SVG Image.
gc.releaseTarget(); //Release the target
}
}
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);
}
}
The following code sample illustrates how event handling can be supported by this JSR.
This 2 main elements involved in event mechanism are as follows:
...
...
//Load an SVG Image.
SVGImage mySvg = (SVGImage) ScalableImage.createImage(...);
Document cityMap = mySvg.getDocument();
SVGElement buttonControl = (SVGElement)cityMap.getElementbyID("buttonControl");
SVGElement highwayLayer = (SVGElement)cityMap.getElementbyID("highwayLayer");
//Create a new instance of MyLayerManager class that implements the EventListener.
MyLayerManager myLayerManager = new MyLayerManager();
//Registration of event listener with the buttonControl SVGElement for "DOMActivate" event.
buttonControl.addEventListener( "DOMActivate", myLayerManager, false);
...
...
//Removal of event listener, when it is not necessary anymore
buttonControl.removeEventListener("DOMActivate", myLayerManager, false);
...
...
//MyLayerManager implements EventListener interface to handle JSR events. In this example,
//the highway layer in SVG content is turned "off" by setting the "display" property on
//highwaylayer SVGElement to "none".
class MyLayerManager implements EventListener {
public void handleEvent(Event evt) {
SVGElement targetElement = (SVGElement)evt.getCurrentTarget();
if( ("DOMActivate".equals(evt.getType())) && ("buttonControl".equals(targetElement.getId())) )
targetElement.setTrait( "display", "none" );
}
}
class MyApplication extends Canvas {
...
...
//Listen to user events from MIDP canvas
void keyPressed(int keyCode){
int gameAction = getGameAction(keyCode);
//Logic to map the key code to the JSR-226 events is done here.
switch(gameAction) {
case FIRE:
//Create a "DOMActivate" Event and dispatch
mySvg.activate();
break;
}
}
//Similarly, create another JSR-226 Event (click) and dispatch it to the SVG document.
void pointerPressed(int x, int y){
mySvg.dispatchMouseEvent("click", x, y);
}
}
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 (UI) 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();
}
}
}
JSR226 does not define any security mechanism. Rather, implementations of JSR226 API are subject to the security mechanisms provided by the underlying profile and configuration, e.g. OMA DRM, network security such as HTTPS, SSL, etc.
A few methods in this API are defined such that a SecurityException will be thrown when called without the appropriate security permissions from the caller. An implementation must guarantee that:
The user of the JSR226 API should be aware that SVG Tiny implementations are representing floats using fixed points and therefore the users must limit their input ranges to be within the range of -32,767.9999 to +32,767.9999 (or the scientific notation equivalent). This limitation applies to the values of the traits, but more importantly to any calculation performed internally by the SVG engine.
In addition, note that CSS units are only supported on the width and height attributes of the root SVG element, and for all the other traits only default (user) units are applied. For example, coordinates are expressed in the user space coordinate system and angles are always expressed in degrees. For more information, please visit SVG Mobile specification.
|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||