org.web3d.vrml.export
Class BinaryExporter

java.lang.Object
  org.web3d.vrml.export.Exporter
      org.web3d.vrml.export.BinaryExporter

All Implemented Interfaces:

java.util.Comparator, ContentHandler, ProtoHandler, RouteHandler, ScriptHandler, StringContentHandler

public class BinaryExporter

extends Exporter

implements java.util.Comparator

An experimental binary format writer. Format: table describing compression method per fieldType # of table entries(8) fieldType(8), compression method(8) table describing compression method for individial nodes # of table entries(16) nodeNumber(16), compression method(8) scenegraph structure PROTO definitions Nodes NodeNumber(8 or 16) DEF #(16) or 0(8) for no DEF name. 1st bit(0 = no def) Fields fieldNumber(8) 0=end of node (Internal Xj3D index + 1) field encoding by type Compression method numbers: Seperate set of assigned numbers for fieldType and node Consortium assigned numbers are 0-127, the rest are locally defineable FieldType Compression methods implemented All field types 0 Straight IEEE Encoding MFInt32 1 Squash Range MFFloat 1 Convert to Int, squash range Goals: Enable experimentation with compression methods. Avoid having experimenters change this file Enable app writers to choose different compression methods. Design: Have a properties file saying what class implements the compression method fieldType, method, class nodeNumber, method, class Each compressor class must implement either the FieldCompressor or NodeCompressor interface ---------------------------------- Proposed New Structure Header Binary spec version Profile length(8) data Component number of components(8) length(8) data Number of Bits used for Node Number(max 16) Number of Bits used for DEF lookup(max 32) Number of Bits used for field name Node Dictionary Table num entries(32) values(UTF8) DEF Dictionary Table num entries(32) values(UTF8) Field Table num entries(32) -- Number of field table entries num fields for this node values(UTF8) Table describing compression method per fieldType # of table entries(8) fieldType(8), number of methods(8) Cannot exceed 8 entries compression method(8) -- Indexed into X3D Binary Spec Table describing compression method for individial nodes # of table entries(16) nodeNumber(16), compression method(8) Proto Definitions, assign NodeNum to each Prototype. Retain nested structures. Structure TBD Import/Export Statements Structure TBD Main File Sequence of OP Codes and Data OpCode(2 bits, 00 = Node, 01=USE, 10 = Comment, 11 = ROUTE Node NodeNum(variable) Def lookup(variable) --> Byte Alignment(OP+NodeNum+DEF divisible by 8) Field Name Id(variable) -->Look for end of fields marker Field Method used(3 bits) --> Byte Alignment(FieldNameID+FieldMethod) Field Method Params --> Byte Aligned Field Data --> Byte Aligned USE Def lookup(variable) --> Byte Aligned(OP+DEF) Comment length(14) --> Byte Aligned(OP+length) data ROUTE fromNode(Def Lookup, variable) fromField(FieldNameID,variable) toNode(Def Lookup, variable) toField(FieldNameID, variable) --> Byte Alignment(OP+fromNode+fromField+toNode+toField) NodeNum 0 is reserved as end of fields marker. NodeNum 1 is reserved for Script nodes. They will have their own format. FieldNum 0 is reserved for end of fields marker

Version:

$Revision: 1.17 $

Author:

Alan Hudson

Field Summary

protected java.util.HashMap	externProtoMap The mapping of externproto names (key) to node instances (value)
static int	FIELD_METHOD_BITS The number of Bits used for the FieldMethod
protected static VRMLFieldReader	fieldParser Field Parser
static int	NODEOP_DYNAMIC
static int	NODEOP_ENDFIELDS
static int	OP_BITS The number of Bits used for the OPCode
static int	OP_COMMENT
static int	OP_NODE
static int	OP_ROUTE
static int	OP_USE
protected java.util.HashMap	protoMap The mapping of proto names (key) to node instances (value)

Fields inherited from class org.web3d.vrml.export.Exporter

majorVersion, minorVersion

Constructor Summary

BinaryExporter(java.io.OutputStream os, int major, int minor, StatisticsCollector stats)
Create a new exporter for binary file formats.

Method Summary

int	compare(java.lang.Object a, java.lang.Object b)
void	componentDecl(java.lang.String componentName) A component declaration has been found in the code.
void	endDocument() Declaration of the end of the document.
void	endExternProtoDecl() Notification of the end of an EXTERNPROTO declaration.
void	endField() Notification of the end of a field declaration.
void	endNode() Notification of the end of a node declaration.
void	endProtoBody() Notification of the end of an ordinary proto body.
void	endProtoDecl() Notification of the end of an ordinary proto declaration statement.
void	endScriptDecl() Notification of the end of a script declaration.
boolean	equals(java.lang.Object a)
void	exportDecl(java.lang.String defName, java.lang.String exported) An EXPORT declaration has been found in the document.
void	externProtoURI(java.lang.String[] values) Notification of the URI list for an EXTERNPROTO.
void	fieldValue(java.lang.String value) The value of a normal field.
void	fieldValue(java.lang.String[] values) The value of an MFField where the underlying parser knows about how the values are broken up.
void	importDecl(java.lang.String inline, java.lang.String exported, java.lang.String imported) An IMPORT declaration has been found in the document.
void	metaDecl(java.lang.String key, java.lang.String value) A META declaration has been found in the code.
int	numBits(int val) Determine the number of bits needed to store this value.
void	printStats()
void	profileDecl(java.lang.String profileName) A profile declaration has been found in the code.
void	protoFieldDecl(int access, java.lang.String type, java.lang.String name, java.lang.Object value) Notification of a proto's field declaration.
void	protoIsDecl(java.lang.String fieldName) Notification of a field value uses an IS statement.
void	registerFieldCompressor(int fieldType, int method, FieldCompressor compressor) Register a class for a field/compression method.
void	registerNodeCompressor(int nodeNumber, int method, NodeCompressor compressor) Register a class for a node/compression method.
void	routeDecl(java.lang.String srcNode, java.lang.String srcField, java.lang.String destNode, java.lang.String destField) Notification of a ROUTE declaration in the file.
void	scriptFieldDecl(int access, java.lang.String type, java.lang.String name, java.lang.Object value) Notification of a script's field declaration.
void	setDocumentLocator(Locator loc) Set the document locator that can be used by the implementing code to find out information about the current line information.
void	startDocument(java.lang.String uri, java.lang.String url, java.lang.String encoding, java.lang.String type, java.lang.String version, java.lang.String comment) Declaration of the start of the document.
void	startExternProtoDecl(java.lang.String name) Notification of the start of an EXTERNPROTO declaration of the given name.
void	startField(java.lang.String name) Notification of a field declaration.
void	startNode(java.lang.String name, java.lang.String defName) Notification of the start of a node.
void	startProtoBody() Notification of the start of an ordinary proto body.
void	startProtoDecl(java.lang.String name) Notification of the start of an ordinary (inline) proto declaration.
void	startScriptDecl() Notification of the start of a script declaration.
void	useDecl(java.lang.String defName) The field value is a USE for the given node name.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OP_BITS

public static final int OP_BITS

The number of Bits used for the OPCode

See Also:

Constant Field Values

FIELD_METHOD_BITS

public static final int FIELD_METHOD_BITS

The number of Bits used for the FieldMethod

See Also:

Constant Field Values

OP_NODE

public static final int OP_NODE

See Also:

Constant Field Values

OP_USE

public static final int OP_USE

See Also:

Constant Field Values

OP_COMMENT

public static final int OP_COMMENT

See Also:

Constant Field Values

OP_ROUTE

public static final int OP_ROUTE

See Also:

Constant Field Values

NODEOP_ENDFIELDS

public static final int NODEOP_ENDFIELDS

See Also:

Constant Field Values

NODEOP_DYNAMIC

public static final int NODEOP_DYNAMIC

See Also:

Constant Field Values

fieldParser

protected static VRMLFieldReader fieldParser

Field Parser

protoMap

protected java.util.HashMap protoMap

The mapping of proto names (key) to node instances (value)

externProtoMap

protected java.util.HashMap externProtoMap

The mapping of externproto names (key) to node instances (value)

Constructor Detail

BinaryExporter

public BinaryExporter(java.io.OutputStream os,
                      int major,
                      int minor,
                      StatisticsCollector stats)

Create a new exporter for binary file formats.

Parameters:

major - The major version number of this scene

minor - The minor version number of this scene

stats - The first pass stats.

Method Detail

registerFieldCompressor

public void registerFieldCompressor(int fieldType,
                                    int method,
                                    FieldCompressor compressor)

Register a class for a field/compression method.

Parameters:

fieldType - For what field type, defined in FieldConstants.

method - For what compression method.

compressor - What class implements the FieldCompressor interface.

registerNodeCompressor

public void registerNodeCompressor(int nodeNumber,
                                   int method,
                                   NodeCompressor compressor)

Register a class for a node/compression method.

Parameters:

nodeNumber - For what field type, defined in FieldConstants.

method - For what compression method.

compressor - What class implements the FieldCompressor interface.

setDocumentLocator

public void setDocumentLocator(Locator loc)

Set the document locator that can be used by the implementing code to find out information about the current line information. This method is called by the parser to your code to give you a locator to work with. If this has not been set by the time startDocument() has been called, you can assume that you will not have one available.

Specified by:

setDocumentLocator in interface ContentHandler

Parameters:

loc - The locator instance to use

startDocument

public void startDocument(java.lang.String uri,
                          java.lang.String url,
                          java.lang.String encoding,
                          java.lang.String type,
                          java.lang.String version,
                          java.lang.String comment)
                   throws SAVException,
                          VRMLException

Declaration of the start of the document. The parameters are all of the values that are declared on the header line of the file after the # start. The type string contains the representation of the first few characters of the file after the #. This allows us to work out if it is VRML97 or the later X3D spec.

Version numbers change from VRML97 to X3D and aren't logical. In the first, it is #VRML V2.0 and the second is #X3D V1.0 even though this second header represents a later spec.

Specified by:

startDocument in interface ContentHandler

Parameters:

uri - The URI of the file.

url - The base URL of the file for resolving relative URIs contained in the file

encoding - The encoding of this document - utf8 or binary

type - The bytes of the first part of the file header

version - The VRML version of this document

comment - Any trailing text on this line. If there is none, this is null.

Throws:

SAVException - This call is taken at the wrong time in the structure of the document

VRMLException - The content provided is invalid for this part of the document or can't be parsed

profileDecl

public void profileDecl(java.lang.String profileName)
                 throws SAVException,
                        VRMLException

A profile declaration has been found in the code. IAW the X3D specification, this method will only ever be called once in the lifetime of the parser for this document. The name is the name of the profile for the document to use.

Specified by:

profileDecl in interface ContentHandler

Parameters:

profileName - The name of the profile to use

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

componentDecl

public void componentDecl(java.lang.String componentName)
                   throws SAVException,
                          VRMLException

A component declaration has been found in the code. There may be zero or more component declarations in the file, appearing just after the profile declaration. The textual information after the COMPONENT keyword is left unparsed and presented through this call. It is up to the user application to parse the component information.

Specified by:

componentDecl in interface ContentHandler

Parameters:

componentName - The name of the component to use

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

metaDecl

public void metaDecl(java.lang.String key,
                     java.lang.String value)
              throws SAVException,
                     VRMLException

A META declaration has been found in the code. There may be zero or more meta declarations in the file, appearing just after the component declaration. Each meta declaration has a key and value strings. No information is to be implied from this. It is for extra data only.

Specified by:

metaDecl in interface ContentHandler

Parameters:

key - The value of the key string

value - The value of the value string

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

importDecl

public void importDecl(java.lang.String inline,
                       java.lang.String exported,
                       java.lang.String imported)
                throws SAVException,
                       VRMLException

An IMPORT declaration has been found in the document. All three parameters will always be provided, regardless of whether the AS keyword has been used or not. The parser implementation will automatically set the local import name as needed.

Specified by:

importDecl in interface ContentHandler

Parameters:

inline - The name of the inline DEF nodes

exported - The exported name from the inlined file

imported - The local name to use for the exported name

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

exportDecl

public void exportDecl(java.lang.String defName,
                       java.lang.String exported)
                throws SAVException,
                       VRMLException

An EXPORT declaration has been found in the document. Both paramters will always be provided regardless of whether the AS keyword has been used. The parser implementation will automatically set the exported name as needed.

Specified by:

exportDecl in interface ContentHandler

Parameters:

defName - The DEF name of the nodes to be exported

exported - The name to be exported as

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endDocument

public void endDocument()
                 throws SAVException,
                        VRMLException

Declaration of the end of the document. There will be no further parsing and hence events after this.

Specified by:

endDocument in interface ContentHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

startNode

public void startNode(java.lang.String name,
                      java.lang.String defName)
               throws SAVException,
                      VRMLException

Notification of the start of a node. This is the opening statement of a node and it's DEF name. USE declarations are handled in a separate method.

Specified by:

startNode in interface ContentHandler

Parameters:

name - The name of the node that we are about to parse

defName - The string associated with the DEF name. Null if not given for this node.

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endNode

public void endNode()
             throws SAVException,
                    VRMLException

Notification of the end of a node declaration.

Specified by:

endNode in interface ContentHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

startField

public void startField(java.lang.String name)
                throws SAVException,
                       VRMLException

Notification of a field declaration. This notification is only called if it is a standard node. If the node is a script or PROTO declaration then the ScriptHandler or ProtoHandler methods are used.

Specified by:

startField in interface ContentHandler

Parameters:

name - The name of the field declared

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

fieldValue

public void fieldValue(java.lang.String value)
                throws SAVException,
                       VRMLException

The value of a normal field. This is a string that represents the entire value of the field. MFStrings will have to be parsed. This is a terminating call for startField as well. The next call will either be another startField() or endNode().

If this field is an SFNode with a USE declaration you will have the useDecl(String) method called rather than this method. If the SFNode is empty the value returned here will be "NULL".

There are times where we have an MFField that is declared in the file to be empty. To signify this case, this method will be called with a parameter value of null. A lot of the time this is because we can't really determine if the incoming node is an MFNode or not.

Specified by:

fieldValue in interface StringContentHandler

Parameters:

value - The value of this field

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

fieldValue

public void fieldValue(java.lang.String[] values)
                throws SAVException,
                       VRMLException

The value of an MFField where the underlying parser knows about how the values are broken up. The parser is not required to support this callback, but implementors of this interface should understand it. The most likely time we will have this method called is for MFString or URL lists. If called, it is guaranteed to split the strings along the SF node type boundaries.

Specified by:

fieldValue in interface StringContentHandler

Parameters:

values - The list of string representing the values

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

useDecl

public void useDecl(java.lang.String defName)
             throws SAVException,
                    VRMLException

The field value is a USE for the given node name. This is a terminating call for startField as well. The next call will either be another startField() or endNode().

Specified by:

useDecl in interface ContentHandler

Parameters:

defName - The name of the DEF string to use

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endField

public void endField()
              throws SAVException,
                     VRMLException

Notification of the end of a field declaration. This is called only at the end of an MFNode declaration. All other fields are terminated by either useDecl(String) or fieldValue(String). This will only ever be called if there have been nodes declared. If no nodes have been declared (ie "[]") then you will get a fieldValue(). call with the parameter value of null.

Specified by:

endField in interface ContentHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

routeDecl

public void routeDecl(java.lang.String srcNode,
                      java.lang.String srcField,
                      java.lang.String destNode,
                      java.lang.String destField)
               throws SAVException,
                      VRMLException

Notification of a ROUTE declaration in the file. The context of this route should be assumed from the surrounding calls to start and end of proto and node bodies.

Specified by:

routeDecl in interface RouteHandler

Parameters:

srcNode - The name of the DEF of the source node

srcField - The name of the field to route values from

destNode - The name of the DEF of the destination node

destField - The name of the field to route values to

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException

startScriptDecl

public void startScriptDecl()
                     throws SAVException,
                            VRMLException

Notification of the start of a script declaration. All calls between now and the corresponding endScriptDecl() call belong to this script node. This method will be called after the ContentHandler startNode() method call. All DEF information is contained in that method call and this just signifies the start of script processing so that we know to treat the field parsing callbacks a little differently.

Specified by:

startScriptDecl in interface ScriptHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endScriptDecl

public void endScriptDecl()
                   throws SAVException,
                          VRMLException

Notification of the end of a script declaration. This is guaranteed to be called before the ContentHandler endNode() callback.

Specified by:

endScriptDecl in interface ScriptHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

scriptFieldDecl

public void scriptFieldDecl(int access,
                            java.lang.String type,
                            java.lang.String name,
                            java.lang.Object value)
                     throws SAVException,
                            VRMLException

Notification of a script's field declaration. This is used for all fields except url, mustEvaluate and directOutput fields. These fields use the normal field callbacks of ContentHandler.

If the current parsing is in a proto and the field "value" is defined with an IS statement then the value returned here is null. There will be a subsequent call to the ProtoHandlers protoIsDecl() method with the name of the field included.

Specified by:

scriptFieldDecl in interface ScriptHandler

Parameters:

access - The access type (eg exposedField, field etc)

type - The field type (eg SFInt32, MFVec3d etc)

name - The name of the field

value - The default value of the field as either String or String[]. Null if not allowed.

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

startProtoDecl

public void startProtoDecl(java.lang.String name)
                    throws SAVException,
                           VRMLException

Notification of the start of an ordinary (inline) proto declaration. The proto has the given node name.

Specified by:

startProtoDecl in interface ProtoHandler

Parameters:

name - The name of the proto

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endProtoDecl

public void endProtoDecl()
                  throws SAVException,
                         VRMLException

Notification of the end of an ordinary proto declaration statement. This is called just after the closing bracket of the declaration and before the opening of the body statement. If the next thing called is not a startProtoBody() Then that method should toss an exception.

Specified by:

endProtoDecl in interface ProtoHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

protoFieldDecl

public void protoFieldDecl(int access,
                           java.lang.String type,
                           java.lang.String name,
                           java.lang.Object value)
                    throws SAVException,
                           VRMLException

Notification of a proto's field declaration. This is used for both external and ordinary protos. Externprotos don't allow the declaration of a value for the field. In this case, the parameter value will be null.

Specified by:

protoFieldDecl in interface ProtoHandler

Parameters:

access - The access type (eg exposedField, field etc)

type - The field type (eg SFInt32, MFVec3d etc)

name - The name of the field

value - The default value of the field as either String or String[]. Null if not allowed.

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

protoIsDecl

public void protoIsDecl(java.lang.String fieldName)
                 throws SAVException,
                        VRMLException

Notification of a field value uses an IS statement.

Specified by:

protoIsDecl in interface ProtoHandler

Parameters:

fieldName - The name of the field that is being IS'd

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

startProtoBody

public void startProtoBody()
                    throws SAVException,
                           VRMLException

Notification of the start of an ordinary proto body. All nodes contained between here and the corresponding endProtoBody() statement form the body and not the normal scenegraph information.

Specified by:

startProtoBody in interface ProtoHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endProtoBody

public void endProtoBody()
                  throws SAVException,
                         VRMLException

Notification of the end of an ordinary proto body. Parsing now returns to ordinary node declarations.

Specified by:

endProtoBody in interface ProtoHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

startExternProtoDecl

public void startExternProtoDecl(java.lang.String name)
                          throws SAVException,
                                 VRMLException

Notification of the start of an EXTERNPROTO declaration of the given name. Between here and the matching endExternProtoDecl() call you should only receive protoFieldDecl(int, java.lang.String, java.lang.String, java.lang.Object) calls.

Specified by:

startExternProtoDecl in interface ProtoHandler

Parameters:

name - The node name of the extern proto

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

endExternProtoDecl

public void endExternProtoDecl()
                        throws SAVException,
                               VRMLException

Notification of the end of an EXTERNPROTO declaration. This is called just after the closing bracket of the declaration and before the opening of the body statement. If the next thing called is not a externProtoURI(java.lang.String[]) Then that method should toss an exception.

Specified by:

endExternProtoDecl in interface ProtoHandler

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

externProtoURI

public void externProtoURI(java.lang.String[] values)
                    throws SAVException,
                           VRMLException

Notification of the URI list for an EXTERNPROTO. This is a complete list as an array of URI strings. The calling application is required to interpet the incoming string. Even if the externproto has no URIs registered, this method shall be called. If there are none available, this will be called with a zero length list of values.

Specified by:

externProtoURI in interface ProtoHandler

Parameters:

values - A list of strings representing all of the URI values

Throws:

SAVException - This call is taken at the wrong time in the structure of the document.

VRMLException - This call is taken at the wrong time in the structure of the document.

compare

public int compare(java.lang.Object a,
                   java.lang.Object b)

Specified by:

compare in interface java.util.Comparator

equals

public boolean equals(java.lang.Object a)

Specified by:

equals in interface java.util.Comparator

printStats

public void printStats()

numBits

public int numBits(int val)

Determine the number of bits needed to store this value.

Parameters:

val - The maximum value

Returns:

The number of bits to store 0-val.