Mobile 3D Graphics API (M3G)

 
 
Mobile 3D Graphics API (M3G) is an optional package which can be used to existing J2ME MIDP 1.0 or MIDP 2.0. profiles. The specification was defined under JSR-184. The target platform of this optional API is J2ME/CLDC 1.1.

More information about M3G can be found at: http://developers.sun.com/techtopics/mobility/apis/articles/3dgraphics/

Version 2.2 of the J2ME Wireless Toolkit provides support for mobile 3D graphics by implementing JSR 184.
The latest M3G API version can be downloaded from: http://www.forum.nokia.com/main/resources/technologies/java/







Classes in M3G package.



M3G classes overview

ClassDescription
AnimationController Controls the position, speed, and weight of an animation sequence. For example, it can be used to control the blinking and movement of a light in an animation application.
AnimationTrack Associates a KeyframeSequence with an AnimationController and an animatable property, which is a scalar or vector variable that the animation system can update directly.
Appearance A set of component objects that define the rendering attributes of a Mesh or a Spring3D.

Appearance app = new Appearance();
app.setTexture(0, tex);
app.setMaterial( setMatColours() );


Background Defines how to clear the viewport. In retained mode, or when rendering a World, the Background object associated with the World is used. In immediate mode, a Background object is given a parameter to clear. If a Background object is not present, the default values specified in the constructor are used.
Camera A scene graph node that defines the position of the viewer in the scene and the projection from 3D to 2D. The camera always faces towards the negative end of the Z axis (0, 0, -1).

Camera camera = new Camera();
float aspectRatio = ((float) getWidth()) / ((float) getHeight());
float fovy = 45.0f; //degree, not rad
float near = 0.1f;
float far = 50.0f
camera.setPerspective(fovy, aspectRatio, near, far);


CompositingMode An Appearance component that encapsulates per-pixel compositing attributes.
Fog An Appearance component that encapsulates attributes for fogging.
Graphics3D A singleton 3D graphics context that can be bound to a rendering target. All rendering is done through the render() methods in this class.

Graphics3D g3d = Graphics3D.getInstance();

public void paint(Graphics g) {
   // bind the canvas graphic to our Graphics3D object
   g3d.bindTarget(g, true, Graphics3D.DITHER |
   Graphics3D.TRUE_COLOR);
   // position the camera
   g3d.setCamera(camera, camTrans);    

   g3d.render(vertBuf, idxBuf, app, modelTrans);
   // Flush
   g3d.releaseTarget();
}


Group A scene graph node that stores an unordered set of nodes as its children.
Image2D A two-dimensional image that can be used as a texture, background, or sprite image. There are two types: mutable images can be updated at any time; immutable images are fixed at construction time and cannot be changed later.
IndexBuffer Defines how to connect vertices to form a geometric object.
KeyframeSequence Encapsulates animation data as a sequence of time-stamped, vector-valued keyframes, each of which represents the value of an animated quantity at a specified instant. Can be associated with multiple animation targets.
Light A scene graph node that represents different kinds of light sources, which are used to determine the color of each object, according to its Material attributes.

Light light = new Light();
light.setColor(0xffffff); // white light
light.setIntensity(1.25f); // over bright


Loader Downloads and deserializes graph nodes and node components, as well as entire scene graphs. Downloading ready-made pieces of 3D content from an M3G file is generally the most convenient way for an application to create and populate a 3D scene.
Material An Appearance component encapsulating material attributes for lighting computations. Other attributes for lighting are defined in Light, PolygonMode, and VertexBuffer.

Material mat = new Material();
mat.setColor(Material.AMBIENT, 0x00765D4D);
mat.setColor(Material.EMISSIVE, 0x00000000);
mat.setColor(Material.DIFFUSE, 0xFF876A56);
mat.setColor(Material.SPECULAR, 0x004D4D4D);
mat.setShininess(60.0f);


Mesh A scene graph node that represents a 3D object defined as a polygonal surface. It represents a conventional rigid body mesh, and its subclasses MorphingMesh and SkinnedMesh extend it with capabilities to transform vertices independently of each other.
MorphingMesh A scene graph node that represents a vertex-morphing polygon mesh.
Node An abstract class for all scene graph nodes. There are five different kinds:
Camera defines the projection from 3D to 2D as well as the position of the viewer in the scene.
Mesh defines a 3D object consisting of triangles with associated material properties.
Sprite3D defines a screen-aligned 2D image with a position in 3D space.
Light defines the position, direction, colors, and other attributes of a light source.
Group serves as a root for scene graph branches.
Object3D An abstract base class for all objects that can be part of a 3D world. These include the world itself, other scene graph nodes, animations, textures, and so on. Everything in the API is an Object3D except Graphics3D, Loader, RayIntersection, and Transform.
PolygonMode An Appearance component encapsulating polygon-level attributes, including settings related to back/front face culling, polygon winding, lighting computations, perspective correction, and shading.
RayIntersection Stores a reference to an intersected Mesh or Sprite3D, and information about the intersection point. Strictly a run-time object, a RayIntersection is filled in by the pick() methods in the Group class, and cannot be loaded from a file by a Loader.
SkinnedMesh A scene graph node that represents a skeletally animated polygon mesh.
Sprite3D A scene graph node that represents a 2D image with a 3D position. This is a fast but functionally restricted alternative to textured geometry. It is rendered as a screen-aligned rectangular array of pixels with a constant depth.
Texture2D An Appearance component encapsulating a 2D texture image and a set of attributes specifying how the image is to be applied on sub-meshes. The attributes include wrapping, filtering, blending, and texture coordinate transformation.

Texture2D tex = new Texture2D(image2D);
tex.setFiltering(Texture2D.FILTER_NEAREST, Texture2D.FILTER_NEAREST);
tex.setWrapping(Texture2D.WRAP_CLAMP, Texture2D.WRAP_CLAMP);
tex.setWrapping(Texture2D.WRAP_REPEAT, Texture2D.WRAP_REPEAT);
tex.setBlending(Texture2D.FUNC_MODULATE);


Transform A generic 4x4 floating-point matrix representing a transformation.

Transform camTrans = new Transform();
camTrans.postTranslate(X_CAMERA, Y_CAMERA, Z_CAMERA);


Transformable An abstract base class for Node and Texture2D, defining common methods for manipulating node and texture transformations.
TriangleStripArray Defines an array of triangle strips. In a triangle strip, the first three vertex indices defines the first triangle. Each subsequent index together with the two previous indices defines a new triangle. For example, the strip S = (2, 0, 1, 4) defines two triangles: (2, 0, 1) and (0, 1, 4).

TriangleStripArray

Number of triangles = Number of vertices - 2

VertexArray An array of integer vectors representing vertex positions, normals, colors, or texture coordinates.

short[] verts = {0,0,0,
                 10,0,0,
                 5,10,0,
                 15,10,0};
VertexArray va = new VertexArray(verts.length/3, 3, 2);
va.set(0, verts.length/3, verts);


VertexBuffer Holds references to VertexArrays that contain the positions, colors, normals, and texture coordinates for a set of vertices.
World A special Group node that is a top-level container for scene graphs. A scene graph is constructed from a hierarchy of nodes. In a complete scene graph, all nodes are ultimately connected to each other by a common root, which is a World node.