Mobile 3D Graphics API

This specification defines the Mobile 3D Graphics API (M3G) for J2ME.

See:
Description

Packages

javax.microedition.m3g

Defines an API for rendering three-dimensional (3D) graphics at interactive frame rates, including a scene graph structure and a corresponding file format for efficient management and deployment of 3D content.

This specification defines the Mobile 3D Graphics API (M3G) for J2ME.

Copyright Notice and Disclaimers

Mobile 3D Graphics API Specification ("Specification")
Version: 1.1
Status: Maintenance Release
Specification Lead: Nokia Corporation ("Specification Lead")
Release: 2005-06-22

Copyright 2005 Nokia Corporation.
All rights reserved.

NOTICE; LIMITED LICENSE GRANTS

Specification Lead hereby grants You a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense), under the Specification Lead's applicable intellectual property rights to view, download, use and reproduce the Specification only for the purpose of internal evaluation, which shall be understood to include developing applications intended to run on an implementation of the Specification provided that such applications do not themselves implement any portion(s) of the Specification. The Specification contains proprietary information of the Specification Lead and may only be used in accordance with the license terms set forth herein.

Subject to the reciprocity requirement set forth below Specification Lead also grants You a perpetual, non-exclusive, worldwide, fully paid-up, royalty free, irrevocable limited license (without the right to sublicense) under any applicable copyrights or patent rights it may have in the Specification to create and/or distribute an Independent Implementation of the Specification that: (a) fully implements the Specification without modifying, subsetting or extending the public class or interface declarations whose names begin with "java" or "javax" or their equivalents in any subsequent naming convention adopted by Specification Lead through the Java Community Process, or any recognized successors or replacements thereof; (b) implement all required interfaces and functionality of the Specification; (c) only include as part of such Independent Implementation the packages, classes or methods specified by the Specification; (d) pass the technology compatibility kit ("TCK") for such Specification; and (e) are designed to operate on a Java platform which is certified to pass the complete TCK for such Java platform. For the purpose of this agreement the applicable patent rights shall mean any claims for which there is no technically feasible way of avoiding infringement in the course of implementing the Specification. Other than this limited license, You acquire no right, license, title or interest in or to the Specification or any other intellectual property rights of the Specification Lead.

You need not include limitations (a)-(e) from the previous paragraph or any other particular "pass through" requirements in any license You grant concerning the use of Your Independent Implementation or products derived from it. However, except with respect to implementations of the Specification (and products derived from them) by Your licensee that satisfy limitations (a)-(e) from the previous paragraph, You may neither: (i) grant or otherwise pass through to Your licensees any licenses under Specification Lead's applicable intellectual property rights; nor (ii) authorize Your licensees to make any claims concerning their implementation's compliance with the Specification in question.

The license provisions concerning the grant of licenses hereunder shall be subject to reciprocity requirement so that Specification Lead's grant of licenses shall not be effective as to You if, with respect to the Specification licensed hereunder, You (on behalf of yourself and any party for which You are authorized to act with respect to this Agreement) do not make available, in fact and practice, to Specification Lead and to other licensees of Specification on fair, reasonable and non-discriminatory terms a perpetual, irrevocable, non-exclusive, non-transferable, worldwide license under such Your (and such party's for which You are authorized to act with respect to this Agreement) patent rights which are or would be infringed by all technically feasible implementations of the Specification to develop, distribute and use an Independent Implementation of the Specification within the scope of the licenses granted above by Specification Lead. However, You shall not be required to grant a license:

1. to a licensee not willing to grant a reciprocal license under its patent rights to You and to any other party seeking such a license with respect to the enforcement of such licensee's patent claims where there is no technically feasible alternative that would avoid the infringement of such claims;
2. with respect to any portion of any product and any combinations thereof the sole purpose or function of which is not required in order to be fully compliant with the Specification; or
3. with respect to technology that is not required for developing, distributing and using an Independent Implementation.

Furthermore, You hereby grant a non-exclusive, worldwide, royalty-free, perpetual and irrevocable covenant to Specification Lead that You shall not bring a suit before any court or administrative agency or otherwise assert a claim that the Specification Lead has, in the course of performing its responsibilities as the Specification Lead under JCP process rules, induced any other entity to infringe Your patent rights.

For the purposes of this Agreement: "Independent Implementation" shall mean an implementation of the Specification that neither derives from the reference implementation to the Specification ("Reference Implementation") source code or binary code materials nor, except with an appropriate and separate license from licensor of the Reference Implementation, includes any of Reference Implementation's source code or binary code materials.

This Agreement will terminate immediately without notice from Specification Lead if You fail to comply with any material provision of or act outside the scope of the licenses granted above.

TRADEMARKS

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 Sun or Sun's licensors, is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, J2ME, and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DISCLAIMER OF WARRANTIES

THE SPECIFICATION IS PROVIDED "AS IS". SPECIFICATION LEAD MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD 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.

LIMITATION OF LIABILITY

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SPECIFICATION LEAD OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SPECIFICATION LEAD AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will indemnify, hold harmless, and defend Specification Lead and its licensors from any claims arising or resulting from: (i) Your use of the Specification; (ii) the use or distribution of Your Java application, applet and/or clean room implementation; and/or (iii) any claims that later versions or releases of any Specification furnished to You are incompatible with the Specification provided to You under this license.

RESTRICTED RIGHTS LEGEND

U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

REPORT

You may wish to report any ambiguities, inconsistencies or inaccuracies You may find in connection with Your use of the Specification ("Feedback"). To the extent that You provide Specification Lead with any Feedback, You hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Specification Lead a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.

Overview

Preface

This document contains the specification of the Mobile 3D Graphics API (abbreviated "M3G") for the Java 2 Platform, Micro Edition ("J2ME"). The specification was defined within the Java Community Process ("JCP") under Java Specification Request 184 ("JSR-184"). The specification is subject to the terms of the JCP agreements (i.e. JSPA and/or IEPA).

The Mobile 3D Graphics API is an optional package. An optional package can be adopted to existing J2ME profiles. A profile of J2ME defines device-type-specific sets of APIs for a particular vertical market or industry. The main target platform of this optional API is J2ME/CLDC, used with profiles such as MIDP 1.0 or MIDP 2.0. However, the API can also be implemented on top of J2ME/CDC, or any Java platform in general.

Technical details of the API can be found in the package overview and the individual class descriptions; see especially the Graphics3D class. To see how the API is used in practice, refer to the example MIDlets at the end of the Package overview.

This specification uses definitions based upon those specified in RFC 2119 (available on the IETF web site).

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.

Background

The objective of the Mobile 3D Graphics API Expert Group was to provide an efficient 3D Graphics API suitable for the J2ME platform, in particular CLDC/MIDP. The API is targeted at CLDC class of devices that typically have very little processing power and memory, and no hardware support for 3D graphics or floating point math. The API has been defined such that implementations on that kind of hardware are feasible. However, the API also scales up to higher-end devices featuring a color display, a DSP, a floating point unit, or even specialized 3D graphics hardware.

The M3G specification is based on the requirements, summarized below, that were agreed on by the Expert Group. The rationale for each requirement is presented in the paragraphs following the summary.

• The API must support retained mode access (that is, a scene graph).
• The API must support immediate mode access, with features similar to OpenGL.
• The API must support mixing and matching of immediate and retained mode access.
• The API must not include optional parts (that is, all methods must be implemented).
• The API must have importers for meshes, textures, entire scene graphs, etc.
• The API must be efficiently implementable on top of OpenGL ES.
• The API must use the native float data type of Java, not introduce a custom type.
• The API must be efficiently implementable without floating point hardware.
• The API should be implementable within 150 kB on a real mobile terminal.
• The API must be structured so that garbage collection is minimized.
• The API must be interoperable with related Java APIs, especially with MIDP.

Several applications were identified for the Mobile 3D Graphics API, including games, map visualization, user interfaces, animated messages, product visualization, and screen savers. Each of these have different needs: some require simple content creation, some require high polygon throughput, yet others require high quality still images with special effects.

It is clear that such a wide spectrum of different needs cannot be fulfilled by a scene graph API alone, nor an immediate mode API alone. It is also clear that having two separate APIs would lead to developer confusion and sub-optimal usage of precious memory space. Rather, there must be only one indivisible API, with only one RI and TCK, that covers both types of access in a unified way. A developer should be able to use either one, or both at the same time, depending on the task at hand.

The immediate mode (or low-level) part of the API should be a subset of OpenGL with no added functionality. That is, the low-level features should be compatible with OpenGL ES, which is being standardized by Khronos. For the Reference Implementation, the scene graph (or high-level) part must be built on top of the low-level interface, and shall never bypass it when rendering. This ensures that the scene graph does not include rendering features that cannot be implemented directly with the low-level interface. The low-level implementation may then be changed freely, or even accelerated with dedicated hardware.

In many cases, there is little else to an application than displaying a scene and playing back some animation created in a 3D modeling tool. This should not require much Java programming. Even in more demanding cases, it greatly speeds up development if it is easy to import objects and animations into a midlet. Therefore, the API must provide importer functions for different data types, such as textures, meshes, animations, and scene hierarchies. The data must be encoded in a binary format for compact storage and transmission.

Most mobile terminals do not have hardware support for floating point processing. This should be reflected in the API, so that it can be efficiently implemented using integer arithmetic. However, since programming with fixed point mathematics is difficult and error prone, the API should use floating point values wherever feasible, and plain integers otherwise. Fixed point values must not be used. Also, instead of introducing a custom Float type or packing floating point values into integers, Java's built-in float data type must be used. As a consequence, this API can not be implemented on top of CLDC 1.0.

Like all APIs targeting MIDP, we need to strive for as compact an implementation as possible. It should be possible to implement the API in less than 150 kB of ROM space, including the native graphics engine, Java class files (ROMized), and content importing facilities. To minimize garbage collection, the API should be structured so that using it does not require repetitive creation of objects.

The API must be tightly integrated with MIDP's LCDUI, such that 2D and 3D graphics can be efficiently rendered on the same Canvas or Image, for example. The decision of whether to use double buffering or not should be delegated to the MIDP implementation. The API should also be able to bind with other GUI APIs, such as AWT.

Related Literature

• The Java Language Specification, James Gosling, Bill Joy, and Guy L. Steele, 1996.
• Quaternion Algebra and Calculus, David Eberly, 1999.
• Key Frame Interpolation via Splines and Quaternions, David Eberly, 1999.
• Connected, Limited Device Configuration (JSR-30), Sun Microsystems, Inc.
• Connected, Limited Device Configuration 1.1 (JSR-139), Sun Microsystems, Inc.
• Connected Device Configuration (JSR-36), Sun Microsystems, Inc.
• Mobile Information Device Profile (JSR-37), Sun Microsystems, Inc.
• Mobile Information Device Profile 2.0 (JSR-118), Sun Microsystems, Inc.
• OpenGL 1.3 Specification, Silicon Graphics, Inc.
• PNG file format, World Wide Web Consortium (W3C).

Revision History

Date	Version	Description
22 Jun 2005	1.1	Maintenance Release
19 Nov 2003	1.0	Final Release

Changes from version 1.0 to 1.1

New features:

• The Loader now supports all PNG color types and bit depths.
• The Node alpha factor now affects Sprite3D as well.
• Several get methods added to allow all properties to be queried.
• OVERWRITE hint flag added to Graphics3D.bindTarget.

Removed or relaxed exceptions:

• Object3D.removeAnimationTrack no longer throws NullPointerException.
• Graphics3D.releaseTarget no longer throws IllegalStateException.
• Removed several deferred exception situations in VertexBuffer.
• Largest possible target surface and viewport need no longer be square.
• Group.addChild no longer throws an exception if the Node is already a child of the Group.

New or tightened exceptions:

• Target surfaces larger than maximum viewport are no longer allowed in Graphics3D.

Resolved interoperability issues:

• Default projection matrix is now required to be identity, with projection type GENERIC.
• The Loader must now treat all file names as case sensitive.
• Mutable MIDP Images are treated as RGB, immutable Images as RGBA.
• Emphasized that flipping the sign of a quaternion when interpolating is not allowed.
• Downscaling of sprite and background images is now well specified.
• Clarified the role of the crop rectangle with scaled sprites.

Acknowledgements

The Mobile 3D Graphics API (JSR-184) Expert Group member companies are listed in the table below, as well as the names of those company representatives who contributed to the version 1.0 specification.

Contributors

Member Companies

Tomi Aarnio, Nokia (Editor) Dirk Ambras, Siemens Paul Beardow, Superscape Mark Callow, HI Corporation Frederic Condolo, In-Fusio Sean Ellis, Superscape (Associate Editor) Harri Holopainen, Hybrid Graphics Jyri Huopaniemi, Nokia (Spec Lead) James Irwin, Vodafone Kari Kangas, Nokia Matti Kantola, Nokia Hidekazu Koizumi, Aplix Ville Miettinen, Hybrid Graphics Hannu Napari, Hybrid Graphics Mark Patel, Motorola Kari Pulli, Nokia Kimmo Roimela, Nokia (Associate Editor) Michael Steliaros, Superscape Jacob Ström, Sony Ericsson Mika Tammenkoski, Sumea Mark Tarlton, Motorola Doug Twilleager, Sun Microsystems Brian Young, Research In Motion Lincoln Wallen, MathEngine Simon Wood, Superscape

Aplix ARM Bandai Networks Cingular Wireless Cellon France France Telecom Fuetrek HI Corporation Hybrid Graphics In-Fusio Insignia Solutions Intel Intergrafx MathEngine Motorola Nokia (Spec Lead) Research In Motion Siemens Sony Ericsson Sun Microsystems Superscape Symbian Texas Instruments 3d4w Vodafone Zucotto Wireless

The following companies and individuals contributed to the version 1.1 specification:

Contributors	Member Companies
Tomi Aarnio, Nokia (Spec Lead, Editor) Paul Beardow, Superscape Mark Callow, HI Corporation Sean Ellis, Superscape Chris Grimm, ATI Ville Miettinen, Hybrid Graphics Kari Pulli, Nokia Kimmo Roimela, Nokia (Associate Editor) Keh-Li Sheng, Aplix Michael Steliaros, Superscape Jacob Ström, Sony Ericsson Mark Tarlton, Motorola Simon Wood, Superscape	Aplix ATI HI Corporation Hybrid Graphics Motorola Nokia (Spec Lead) Sony Ericsson Superscape