Developers guidelines June 2010 3D graphics with Java™ Platform, Micro Edition for Sony Ericsson phones
Developers guidelines | 3D graphics with Java ME Preface Purpose of this document This document describes 3D support for Java™ Platform, Micro Edtion (Java ME™), found in Sony Ericsson phones. The document also describes how to develop Java 3D applications based on the Mascot Capsule® Micro3D Version 3 and the Mobile 3D Graphics API for J2ME (JSR-184). Readers who will benefit from this document include: • • • • • Software developers Corporate buyers IT professionals.
Developers guidelines | 3D graphics with Java ME Sony Ericsson Developer World At www.sonyericsson.com/developer, developers find the latest technical documentation and development tools such as phone White papers, Developers guidelines for different technologies, Getting started tutorials, SDKs (Software Development Kits) and tool plugins.
Developers guidelines | 3D graphics with Java ME Generic names Series Sony Ericsson phones J300 J300i, J300c, J300a K300 K300i, K300c, K300a K500 K500i, K506c, K508i, K508c K700 K700i, K700c S700 S700i, S700c, S710a Z500 Z500a JP-4 phones: V800 V800, Vodafone 802SE Z800 Z800i JP-5 phones: K600 K600i, K608i K750 K750i, K750c, D750i V600 V600i W700 W700i, W700c W800 W800i, W800c Z520 Z520i, Z520c, Z520a Z525 Z525a JP-6 phones: K310 K310i, K310c, K310a K320 K320i, K320c K51
Developers guidelines | 3D graphics with Java ME Generic names Series Sony Ericsson phones JP-7 phones: K530 K530i K550 K550i, K550c K610 K610i, K610c, K618i K770 K770i K790 K790i, K790c, K790a K800 K800i, K800c K810 K810i, K818c S500 S500i, S500c T650 T650i, T658c W350 W350i, W350c W380 W380i, W380c W580 W580i, W580c W610 W610i, W610c W660 W660i W710 W710i, W710c W830 W830i, W830c W850 W850i, W850c W880 W880i, W888c Z555 Z555i, Z555c Z610 Z610i Z710 Z710i, Z710c
Developers guidelines | 3D graphics with Java ME Generic names Series Sony Ericsson phones JP-8 (8.0-8.2) phones: G502 G502, G502c K630 K630i K660 K660i K850 K850i, K858c V640 V640i W890 W890i W910 W910i, W908c Z750 Z750i Z770 Z770i JP-8.
Developers guidelines | 3D graphics with Java ME Generic names Series Sony Ericsson phones JP-8.4 phones: C510 C510, C510c, C510a C901 C901, C901a, C901 GreenHeart™ C903 C903, C903a C905 C905, C905c, C905a G705 G705, G705u Jalou™ Jalou™ F100i, BeJoo™ F100i Naite™ Naite™ J105i, Naite™ J105a T707 T707, T707a T715 T715, T715a W508 W508, W508c, W508a, W518a W705 W705, W705u W715 W715 W995 W995, W995a JP-8.
Developers guidelines | 3D graphics with Java ME Trademarks and acknowledgements GreenHeart, Aino, BeJoo, Jalou, Naite, Pureness, Satio, Sony Ericsson Aspen, Sony Ericsson Cedar, Sony Ericsson Elm, Sony Ericsson Hazel, Sony Ericsson Zylo, Sony Ericsson Vivaz, Xperia and Yari are trademarks or registered trademarks of Sony Ericsson Mobile Communications AB. Windows and Windows Mobile are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries.
Developers guidelines | 3D graphics with Java ME 2005-08-08 Version R5B S600 series phones changed to W550 2005-09-30 Version R6A Sixth version 2005-10-24 Version R7A Seventh version. Information about W900 series added 2005-10-27 Version R7B Minor editorial changes 2006-01-04 Version R8A Eighth version. Information about W810 series added 2006-02-13 Version R9A Ninth version. Information about K610 series added 2006-02-28 Version R10A Tenth version.
Developers guidelines | 3D graphics with Java ME 2008-09-09 Version R25A 25th version. Information about G705 series added 2008-10-17 Version R25B 25th revised version. New document layout 2008-11-11 Version R26A 26th version. Information about W705 series added 2009-01-09 Version R27A 27th version. Information about C510 and W508 series, and Entry Java Platform EJP-1.0 added 2009-02-15 Version R28A 28th version.
Developers guidelines | 3D graphics with Java ME Contents Overview ....................................................................................................................12 Sony Ericsson Java platforms .................................................................................12 The 3D engines .......................................................................................................17 Java ME integration .......................................................................
Developers guidelines | 3D graphics with Java ME Overview There is a growing need for mobile devices to process and display 3D content. Such 3D content might be part of a game, such as its scenery and characters. Or it might be a program that uses 3D graphics to display information in a unique way. Sony Ericsson phones offer built-in 3D graphics support to handle such content. This section provides a brief overview of the 3D technology in Sony Ericsson phones.
Developers guidelines | 3D graphics with Java ME Java Platform Features Phones Optional features (JSR-82, JSR256, VSCL 2.0) and comments JP-8.3 • Additional JSR-211 C702, C902, T700, W595, W760, content handlers W902, W980, Z780 • PIMChangeListener API • JSR-256 extensions • Improved security handling JP-8.0 - JP-8.2 JSR-211 G502, K630, K660, K850, V640, W890, W910, Z750, Z770 JSR-179 JSR-82: All JP-8.3 phones JSR-256: All JP-8.
Developers guidelines | 3D graphics with Java ME Java Platform Features Phones Optional features (JSR-82, JSR256, VSCL 2.0) and comments JP-2 Nokia UI API 1.1 Z1010 JSR-135 JSR-120 JTWI (JSR-185) MIDP 2.0 CLDC 1.1 EJP = Sony Ericsson Entry Java platform. Entry Java Platform Features Phones Optional features and comments EJP-1.0 JSR-75 (PDA optional F305 packages Mascot Capsule Ver. 3 JSR-184 (Mobile 3D Graphics API 1.1) Nokia UI API 1.1 JSR-135 (MMAPI 1.2) JSR-120 (WMA 1.1) JSR-185 (JTWI 1.
Developers guidelines | 3D graphics with Java ME JP-WM_SEMC = Sony Ericsson Java platform for Windows Mobile. Java Platform Features Phones Optional features and comments JP-WM_SEMC-2.0 JSR-75 (PDA optional Aspen, X2 packages) JSR-120 (WMA 1.1) FC, ContactList, TodoList, EventList SMS Push JSR-135 (MMAPI 1.2) JSR-118 (MIDP 2.1) NokiaUI API 1.1 JSR-184 (Mobile 3D Graphics API 1.1) Mascot Capsule V4 JSR-185 (JTWI 1.0) JSR-139 (CLDC 1.1) JSR-172 (WSA 1.0) JSR-177 (SATSA 1.
Developers guidelines | 3D graphics with Java ME SJP = Sony Ericsson Symbian OS Java platform. Java Platform Features Phones Comments SJP-5.0 JSR-75 (PDA optional Satio™, Vivaz™, Vivaz™ pro packages) S60 platform specification JSR-82 S60 platform specification. Bluetooth and OBEX API JSR-120 (WMA 1.1) S60 platform specification JSR-205 (WMA 2.0) S60 platform specification JSR-135 (MMAPI) S60 platform specification. JSR-118 (MIDP 2.1) S60 platform specification Nokia UI API 1.
Developers guidelines | 3D graphics with Java ME The 3D engines The following 3D engines are supported on the Sony Ericsson phones in this document: • Mascot Capsule Engine Version 3, hereafter referred as “Micro3D Ver.3” Not supported on Sony Ericsson Windows Mobile Java platform and Sony Ericsson Symbian OS Java platform • The mobile standards Mobile 3D Graphics API for the Java ME platform, hereafter referred as “JSR-184”.
Developers guidelines | 3D graphics with Java ME directly accessing it via its native Micro3D Ver.3 API or alternatively through the JVM via JSR-184 API. The 3D engine executes in parallel with the mobile phone JVM, as shown in the figure below, to render the 3D image. No special operations are required to display 3D content with Mascot Capsule Micro3D Ver.3. Simply add calls to its 3D APIs within the Java application.
Developers guidelines | 3D graphics with Java ME JSR-184 – Mobile 3D Graphics API for the Java ME platform JSR-184 is the standard API for 3D in phones. It can be expected to be included in all phones that support 3D. The engine uses floating point arithmetic in the calculations for highest precision. JSR-184 version 1.1 is supported in Sony Ericsson phones on Java platform JP-8.0 or higher, Sony Ericsson Java platform for Windows Mobile and Sony Ericsson Symbian Java Platform.
Developers guidelines | 3D graphics with Java ME All Sony Ericsson JP-8 phones fully support OpenGL and EGL version 1.0. Only RGB565 configurations are currently supported. From JP-8.5 also the OpenGL ES extension pack is supported. Sony Ericsson Symbian OS Java platform 5.0 or higher, except early released Satio™ phones, support OpenGL ES 1.0. To define the attributes for an RGB565 configuration: int configAttributes[] = { EGL11.EGL_RED_SIZE, 5, EGL11.EGL_GREEN_SIZE, 6, EGL11.EGL_BLUE_SIZE, 5, EGL11.
Developers guidelines | 3D graphics with Java ME The Developers guidelines for Sony Ericsson phones provide developers with phonespecific Java technical specifications including phone memory, heap size, canvas size, supported APIs, platform and network capabilities, and so on. Both the SDK and the Developers guidelines are available at Sony Ericsson Developer World.
Developers guidelines | 3D graphics with Java ME Mascot Capsule Micro3D Version 3 This section will describe the Mascot Capsule Micro3D Version 3 in detail. This popular version uses proprietary 3D Java APIs. Graphics commands Micro3D Ver.3 graphics API operates in an immediate mode, where graphics command are issued into graphics pipeline and the rendering engine executes it. These commands implement the following functions: • 3D objects descriptions.
Developers guidelines | 3D graphics with Java ME 3D object information. Various attributes, such as the object shading type, can be associated with an instance of this class. Other associations specify operations such as rotation, scaling, or motion. Command lists can also be attached to each instance of Figure. Besides simplifying the design of a 3D model, object import also provides two other significant advantages to the developer. First, it reduces the computational overhead of updating a 3D scene.
Developers guidelines | 3D graphics with Java ME Effect3D Contains the rendering effect data that is associated with a particulat 3D object. Such effects include transparency, shading type and lighting Figure Stores the geometric information of a 3D object. Also stores pose information. This data is read from a JAR resource FigureLayout Container for all rendering information of a 3D object, such as its position, size and orientation Graphics3D Implements all rendering functions.
Developers guidelines | 3D graphics with Java ME Mobile 3D Graphics API for the Java ME platform (JSR 184) This section describes in detail the Mobile 3D Graphics API for the Java ME platform (called JSR-184). For more information about this standardised API, see http://www.jcp.org/en/jsr/detail?id=184. Graphics commands JSR-184 supports retained and immediate modes of scene rendering. The advantage of JSR-184 retained mode is that it allows less 3D-savvy developers to readily build complex 3D models.
Developers guidelines | 3D graphics with Java ME application, where it is read by the Loader class. The Loader generates instances of 3D objects as it reads the resource. Entire scene graphs with animation, lighting, and camera views can be imported and displayed. Because the format of the .m3g file is an open standard, it enables 3D content to be generated on high-end platforms, then readily imported or shared among a wide variety of mobile platforms that implement JSR-184.
Developers guidelines | 3D graphics with Java ME Background Used to specify a color or image that clears or fills the given viewport (a drawing area). Camera The node in a scene graph that establishes the point of view of the scene. Used to render the scene graph from 3D to 2D. It also establishes what elements of the scene graph are visible (clipping). CompositingMode An Appearance component that contains the attributes used in pixel compositing operations.
Developers guidelines | 3D graphics with Java ME PolygonMode An Appearance component that contains polygon-level attributes. These attributes include back/front face culling, lighting computations, perspective corrections, shading, and winding. RayIntersection An object that contains rays added to it by the Group pick() method. RayIntersection stores references to the meshes or sprites that intersect each ray, and information about the intersection point.
Developers guidelines | 3D graphics with Java ME Getting started The Java ME platform execution environment integrates both the JSR-184 and Micro3D Ver.3. This implies that familiar Java development tools are used to write a 3D application. However, the generation of the files that Mascot Capsule imports to assemble and render 3D models is a more involved process, described below.
Developers guidelines | 3D graphics with Java ME All of the plugins, tools, and the documentation necessary to manage the export/ translation process are available from Mascot Capsule Web site at http://www.mascotcapsule.com/toolkit/sony_ericsson/. These tools are provided by HI Corporation and all feedback and trouble reports shall be submitted to this website. Note: It is important that the version number of the 3D modeling program used and the export plugin version number match.
Developers guidelines | 3D graphics with Java ME Java ME platform application set up for Micro3D Ver.3 This section describes how to properly initialise the Micro3D graphics environment within a mobile application and display 3D graphics with it. Briefly, the proper sequence of events to configure and use the Micro3D Ver.3 graphics engine is as follows: 1. Load the 3D model data. 2. Initialise any attributes for the 3D objects of the model. 3. Set up the camera. 4. Set up the light and any effects. 5.
Developers guidelines | 3D graphics with Java ME // Associate the action table with this object figure.setPosture ( action, 0, 1 ); The arguments to the setPosture() method associate the action table action with figure. The animation starts with the first frame of the model and the first action command from the table. Set up the camera By positioning the viewing camera, the point of view of the scene has been set up.
Developers guidelines | 3D graphics with Java ME Effect3D effect; effect.setLight( light ); Note that other attributes could be added to the instance of effect, such as shading types and whether color transparency is enabled or not. Initialise the graphics environment, render the model, and display it With the Figure and many of its attributes prepared, it should be rendered and displayed. The Graphics3D class is used for this, since it contains all of the rendering methods.
Developers guidelines | 3D graphics with Java ME Mobile 3D Graphics API (JSR-184) The same 3D modelling tools used for Micro3D Ver.3 can be used to create data used in Mobile 3D Graphics Version 4. (m3g) HI Corporation offers a number of plug-ins that can be used from within these authoring tools to export the model and animation data to intermediate files.
Developers guidelines | 3D graphics with Java ME References Useful links • Sony Ericsson Developer World (http://www.sonyericsson.com/developer) • Mascot Capsule Toolkit for Sony Ericsson phones (http://www.mascotcapsule.com/toolkit/sony_ericsson) • Mascot Capsule Micro3D V4 - m3g Tools and Plug-ins (http://www.mascotcapsule.com/M3G/download/e_index.html) • Mobile 3D Graphics API for the Java ME platform (JSR-184) (http://www.jcp.
Developers guidelines | 3D graphics with Java ME A: To simulate the speed of the actual phone, the "Graphics Latency" preference can be tuned in the Sony Ericsson WTK2 Preferences under the Performance tab. However, beware that input will lag behind as well. Q: My exported 3D Max 7 models are very large, how can I reduce size? A: Textures usually consume the most space and a good starting point is to try to reduce the number of textures being used.
Developers guidelines | 3D graphics with Java ME A: Create a new project in Ktoolbar. Select Project->Settings menu, on API Selection tab choose "Custom" platform. Check the appropriate checkbox "Mascot Capsule Ver.3 API". Now you will be able to build your project with support of Mascot Capsule V3 API. Q: What tools are available to create models? A: All Micro3D conversion tools are available at Mascot Capsule website http://www.mascotcapsule.com/toolkit/sony_ericsson.
Developers guidelines | 3D graphics with Java ME Q: How can I do ToonShading A: ToonShading, or CelShading, cannot be performed by the hardware, since the current hardware on all 3D-enabled phones does not support direct manipulation of the graphics pipeline (shading). However, one can mathematically create CelShaded models in software. It is done by manually plotting pixels to the graphic buffer after all models have been rendered. This technique is very slow unless done right.
Developers guidelines | 3D graphics with Java ME Q: How can I make a racing game MIDlet using Mascot Capsule version 3, when the maximum value for the far-clipping plane is 32767? For accurate sine and cosine as well as for vector analysis I normally have to scale the scene so that 4096 represents the 1.0. If I do so, I only have 7 units for my viewing frustum, difficult for a racing game.
Developers guidelines | 3D graphics with Java ME A: It is possible to do back face culling and it can be set directly to the figure data by using the PAC tool. The PAC tool can be downloaded from http://www.mascotcapsule.com/toolkit/sony_ericsson Q: Why doesn't the model display in the viewer? A: The UV values of bac data are all whole numbers. If decimals appear in the UV coordinate values of the 3D tool, deviations will occur when exporting to the bac file.
Developers guidelines | 3D graphics with Java ME A: The 3D Max M3G plugin does not perform any optimisation in regard to calculating triangle stripes in contrast to the Mascot Capsule exporter plugin and therefore produces potentially larger file sizes. We recommend using the HiCorp exporter plugin. Q: Are there any methods applicable to 3D collision detection? A: No, There is no API defined for collision detection. However, the RayIntersection class computes a ray intersection in the 3D world.
Developers guidelines | 3D graphics with Java ME vertexBuffer.setTexCoords(1, TEXTURE_ARRAY, (1.0f/255.0f), null); appearance.setTexture(0, texture); // add the texture to the appearance. apperance.setTexture(1, texture2); // add the second texture to the appearance Q: I have specified three different colors for a triangle (one for each vertex) but it only shows one color.
Developers guidelines | 3D graphics with Java ME Q: I have created a triangle, but when I rotate the plane it disappears after rotating 90 degrees and remains invisible until it has rotated 270 degrees. The backside of the triangle is black ? A: This is a method called back culling and it is used to gain performance by showing only the front side of each polygon. You can specify the culling in the PolygonMode class: PolygonMode polygonMode = new PolygonMode(); polygonMode.setCulling(PolygonMode.
Developers guidelines | 3D graphics with Java ME int INDICES[] = {2, 4, 6, 0, 4, 3, 3, 5, 7, 1, 2, 5, 0, 2, 4, 6, 6, 1, 1, // 3, // 5, // 7, // 0, // 7};// Front Face Left Face Back Face Right Face Top Face Bottom Face int[] LENGTHS = new int[] {4, 4, 4, 4, 4, 4}; POSITIONS_ARRAY = new VertexArray(8, 3, 2); POSITIONS_ARRAY.
Developers guidelines | 3D graphics with Java ME Q: Is my understanding correct in that to render polygons on the phone, I must confirm correct operation on PVMicro.exe? A: Any 3D content that does not display in the PVMicro.exe viewer will not display on a phone. Q: What are UV settings? A: Content that runs on Mascot Capsule Engine must have texture-mapped UV coordinates for all polygon vertices.
