javax.microedition.m3d
Class Loader

java.lang.Object
  |
  +--javax.microedition.m3d.Loader

public class Loader

extends java.lang.Object

A synchronous loader (deserializer) for entire scene graphs, individual branches, and attribute objects. This class cannot be instantiated, and there are only two members in it, the static load methods. Loading is initiated by passing a named resource or a byte array to the load method. The named resource can be, for example, a file in the JAR package or a URI. Any external references in the resource or byte array are followed recursively. In the case of a named resource, the references may be absolute or relative, but in the case of a byte array, only absolute references are allowed. Both load methods will only return when all objects have been loaded, including the referenced objects. Displaying content while downloading (progressive loading) is therefore not supported.

The Loader can deserialize instances of any class derived from Object3D. These classes include scene graph nodes such as World, Group, Camera and Light; attribute classes such as Material, Appearance and Texture2D; animation classes such as AnimationTrack and AnimationController; and so on.

The load methods return an array of Object3D's. If the application does not know the types of these objects beforehand, it can query them using the run-time type information built into Java. Note that only the "root level" objects in the file are returned directly; the rest of the objects (often the majority) can be found by following references recursively. For example, if the only object in the returned array is a World, its children can be obtained with the getChild method. Another way to find a non-listed object is with the userID field and the find method, both in Object3D.

The data to be loaded must be a valid JSR-184 file, or a PNG image file, in which case an Image2D object will be output. Some implementations may support other formats as well. If the data is not in a supported format, or is otherwise invalid, an exception will be thrown.

Example:

A code fragment illustrating the use of Loader and find.

 Object3D[] roots=null;

try {
    // Load a World and an individual Mesh over http.

    roots = Loader.load("http://www.example.com/myscene.m3d");
} catch(IOException e) {
    // couldn't open the connection, or invalid data in the file
}

// Assume that the stand-alone Mesh is the first root object in the file,
// followed by the World object. The ordering is determined at the
// authoring stage.

Mesh myMesh = (Mesh) roots[0];      // an individual mesh for immediate mode
World myWorld = (World) roots[1];   // contains our entire scene graph

// Turn on perspective correction for the Mesh.

Appearance a = myMesh.getAppearance(0);  // get the appearance of the mesh
GeometryMode g = a.getGeometryMode();    // get its geometry attributes
g.setPerspectiveCorrectionEnable(true);  // enable perspective correction

// Find a specific Camera node in the World, and sets it as the currently
// active camera in the world. We've previously assigned the userID "10"
// to that camera node.

Camera myCamera = (Camera) myWorld.find(10);
myWorld.setActiveCamera(myCamera);

// Load an individual PNG file.

Image2D textureImage;

try {
     textureImage = (Image2D)Loader.load("/texture.png")[0];
} catch(IOException e) {
     // couldn't load the PNG file
}

Method Summary

static Object3D[]	load(byte[] data, int offset) Deserializes Object3D instances from the given byte array, starting at the given offset.
static Object3D[]	load(java.lang.String name) Deserializes Object3D instances from the named resource.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

load

public static Object3D[] load(java.lang.String name)
                       throws java.io.IOException

Deserializes Object3D instances from the named resource. The name parameter is a resource name as defined by Class.getResourceAsStream(name) in MIDP, or a URI. The types of data that can be loaded with this method are defined in the class description.

Parameters:

name - name of the resource to load from

Returns:

an array of newly created Object3D instances

Throws:

java.io.IOException - if any references in name cannot be resolved or loaded

java.io.IOException - if the data in name, or in any resource referenced from it, is not in accordance with the JSR-184 file format specification

java.lang.SecurityException - if the application does not have the security permission to open a connection to load the data

load

public static Object3D[] load(byte[] data,
                              int offset)
                       throws java.io.IOException

Deserializes Object3D instances from the given byte array, starting at the given offset. The types of data that can be loaded with this method are defined in the class description. The byte array must not contain any relative references (such as "/pics/texture.png"), but complete URIs are allowed.

Parameters:

data - byte array containing the serialized objects to load

offset - index at which to start reading the data array

Returns:

an array of newly created Object3D instances

Throws:

java.io.IOException - if any references in data cannot be resolved or loaded

java.io.IOException - if the data in data, or in any resource referenced from it, is not in accordance with the JSR-184 file format specification

java.lang.SecurityException - if the application does not have the security permission to open a connection to load the data