com.jmex.model.converters
Class X3dToJme

java.lang.Object
  extended by com.jmex.model.converters.FormatConverter
      extended by com.jmex.model.converters.X3dToJme

public class X3dToJme
extends FormatConverter

A Loader class to load models from XML-encoded X3D files (see this link for the specification) into jME.

This Loader is designed to be able to load the geometry and lights contained in an X3D file and set the necessary properties to properly set up a model for jME. It uses as many of the features of X3D as possible.

X3D is based on the ISO standard VRML97 (see the ISO specification), which was originally created as a language for describing interactive 3D scenes. The goal of X3D was to split up the VRML functionality into several Components (e.g. a Core Component, the Grouping Component, the Geometry3D Component, the Texturing Component, and so on). The Components are grouped into Profiles, which can be used to tell the X3D browser which set of Components to load (e.g. the Interchange Profile, which is used for basic geometry, the Immersive Profile, which supports more geometry features and additionally interaction functionality, and so on).
However, this loader is NOT designed to support certain Profiles or Components. Instead it tries to load all the features that can be realized in jME.

The loader currently supports the following functions and X3D Elements:


The fields DEF and USE are actually supported too, but there is one limitation with the USE of Objects with bump maps: The BumpMapColorController attached to bumpmapped objects is not cloned by CloneImportExport. When you try to re-USE a bumpmapped Appearance for a different object, you can add a BumpMapColorController yourself to fix this issue. This also applies to the method convert(InputStream, OutputStream): As this method uses a binary exporter to write the parsed scene to the output stream, the BumpMapColorController gets lost here too, so you have to set it again in order to display the bump maps properly.

Version:
2008-03-11
Author:
Michael Sattler, Stephen Larson (LineSet, some bugfixes)

Field Summary
 
Fields inherited from class com.jmex.model.converters.FormatConverter
properties
 
Constructor Summary
X3dToJme()
          Creates the X3DLoader.
 
Method Summary
 void convert(java.io.InputStream in, java.io.OutputStream jmeOut)
          Converts the .x3d file read from the specified InputStream to the .jme format and writes it to the specified OutputStream.
 Spatial loadScene(java.io.InputStream x3dIn, java.util.Map<java.lang.String,java.io.InputStream> texData, LightState lightState)
          Loads a scene (model) from the X3D file contained in the specified input stream.
Please note: This loader is NOT thread-safe!
 void setDTDResolver(org.xml.sax.EntityResolver resolver)
          Passes an EntityResolver to the DocumentBuilder used to parse the X3D files' XML structure.
 
Methods inherited from class com.jmex.model.converters.FormatConverter
attemptFileConvert, clearProperty, getProperty, setProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

X3dToJme

public X3dToJme()
         throws java.lang.InstantiationException
Creates the X3DLoader.

Throws:
java.lang.InstantiationException - In case the XML DocumentBuilder cannot be instantiated
Method Detail

setDTDResolver

public void setDTDResolver(org.xml.sax.EntityResolver resolver)
Passes an EntityResolver to the DocumentBuilder used to parse the X3D files' XML structure. Using a resolver can save a lot of time when parsing X3D files, because usually an HTTP connection to the Web3D.org server is opened to get the DTD files for X3D. If you specify a resolver, you can provide the DTDs on the local file system, for example.
For details on how an EntityResolver works, please refer to the J2SE API documentation.
The utility class X3DResolver can be used to provide a mapping of the file names to InputStreams containing the files; see the documentation there.
The DTDs usually needed for X3D parsing are:

Parameters:
resolver - An EntityResolver to resolve the DTD references for X3D

convert

public void convert(java.io.InputStream in,
                    java.io.OutputStream jmeOut)
             throws java.io.IOException
Converts the .x3d file read from the specified InputStream to the .jme format and writes it to the specified OutputStream. If the model contains any textures, please specify the folder containing the textures with setProperty("textures", new URL(folder)). If you use this method instead of loadScene(InputStream, Map, LightState), any lights in the scene will always be attached to a LightState at the root of this scene, thus only lighting the X3D scene itself and not the scene containing it. Additionally, any BumpMapColorControllers created while loading the model will get lost in the exporting process, so if the model contains any bump maps, the controller has to be set manually when the exported model is being re-imported.

Specified by:
convert in class FormatConverter
Parameters:
in - The InputStream to read the .x3d file from
jmeOut - The OutputStream to write the .jme model to
Throws:
java.io.IOException - If an error occurs

loadScene

public Spatial loadScene(java.io.InputStream x3dIn,
                         java.util.Map<java.lang.String,java.io.InputStream> texData,
                         LightState lightState)
                  throws java.lang.Exception
Loads a scene (model) from the X3D file contained in the specified input stream.
Please note: This loader is NOT thread-safe!

Parameters:
x3dIn - An InputStream holding the X3D file
texData - A Map mapping the paths of texture files to InputStreams holding the file content
lightState - The LightState to attach scene lights to. If null is passed, a new LightState is created and attached to the model root, which causes the lights in the X3D scene to light only the X3D scene itself
Returns:
The model, if it was successfully loaded, otherwise null
Throws:
An - Exception, in case any error occurs
java.lang.Exception