file-format.html

J2ME Mobile3D API,高性能手机3D开发的api

<blockquote>
<pre>UInt32 Checksum = 0xffe806a3</pre>
</blockquote>
On limited devices, we might not be able to afford to load an entire section
before interpreting it. Thus the loader may start interpreting the objects
before knowing that the section as a whole is correct. However, the checksums
are still useful in that we at least know afterwards that there was an
otherwise undetected error if the checksums differed.
<p>Even on a system that can afford to load an entire section before loading
it, it is possible to have errors in the file. The content creation program
can have a defect, the transmission of the file could be error-prone, or
the file could have been altered as part of a deliberate attack on the
device. Thus it is important that the loader tries to detect errors also
in files that have correct checksums.
<p>The loader implementation may decide not to compute (and/or check) the
checksum. Thus, a file with erroneous checksums is not guaranteed to be
rejected. However, a file with erroneous checksums is not a M3G compliant
file and must not pass a strict verification test.
<h2 class="SectionTitle">
<a NAME="ObjectStructure"></a>7 Object Structure</h2>
The object data stored in each section is first decompressed and then interpreted
as a sequence of objects. This separates the act of decompression from
the interpretation of the data. All data documented in this section is
assumed already to be in its uncompressed form.
<p>Each object in the file represents one object in the scene graph tree,
and is stored in a chunk. The structure of an object chunk is as follows:
<blockquote>
<pre>Byte&nbsp;&nbsp; ObjectType
UInt32 Length
Byte[] Data</pre>
</blockquote>

<h3><a NAME="ObjectType"></a>7.1 ObjectType</h3>

This field describes what type of object has been serialized. For
instance, we could have a Camera node, a Mesh node or a Texture2D
object. <a href="#ObjectTypeValues">Section 12</a> includes a table
that shows the correspondence between ObjectType values and the actual
object types. The ObjectType field must hold a valid value as defined
in Section 12. The reserved object types (values 23..254) must be
treated as errors.

<p>The values 0 and 0xFF are special: 0 represents the header object, and
0xFF represents an external reference.

<p>Example:
<blockquote>
<pre>Byte ObjectType = 14</pre>
</blockquote>
This means that the current object is a <tt>Mesh</tt> object (see
<a href="#ObjectTypeValues">Section
12</a>).
<h3>
<a NAME="ObjectLength"></a>7.2 Length</h3>
This contains the length of the Data array, in bytes. Note that a value
of 0 in this field may be legal; some objects require no additional data
over and above their mere presence.
<p>Example:
<blockquote>
<pre>UInt32 Length = 2032</pre>
</blockquote>
indicates that the <tt>Data</tt> field of this object spans 2032 bytes
in the (decompressed) file.

<h3><a NAME="ObjectData"></a>7.3 Data</h3>

This is data that is specific for the object. It is up to the loader
to interpret this data according to the object type and populate the
object accordingly. Detailed information on the data for each object
type is documented in <a href="#SpecialObjectData">Section 10</a> and
<a href="#PerClassData">Section 11</a>.

<p>For instance, if the object just contained a single color, the Data
would be a 3 byte long array, where the first byte represents the red
component, the second byte the green component, and the third byte the
blue component.

<p>Attempts to read off the end of an object's data are disallowed and
must be signalled as errors. An example of this would be an object with
a reported length of 32 bytes, but which internally specifies an array
with 65537 members.

<p>Conversely, the deserialization code for each object may also check
that each byte of the data belongs to a valid interpretation.
Additional bytes after the end of an object's valid data are
disallowed. This condition may be difficult to determine on the target
platform, but any file which contains "extra" data in object chunks is
not a M3G compliant file and must not pass a strict verification test.

<h2 class="SectionTitle">
<a NAME="ObjectOrdering"></a>8 Object Ordering</h2>

All the objects in the scene graph are serialized in leaf-first order,
or reference based order as it is also called. Before serializing a
specific object, all other objects referenced by that object must
already have been serialized. Objects may refer to themselves if this
is allowed by the scene data structures.

<p>By definition, the root of the tree will be sent last.

<p>For output, it is possible to use a "leaves first" strategy - start
by serializing all the objects that do not reference other objects,
and then all the objects that refer to the objects already sent, and
so it continues until all objects are sent.

<p>Alternatively, a "depth first" strategy can be used, where each
object recursively applies the following procedure, to build up a
table of references in the correct order. (It is assumed that the
table is initially empty.)

<blockquote>
<pre>BuildReferenceTable:

for each reference in this object,
&nbsp;&nbsp;&nbsp; call BuildReferenceTable on the referred object

if this object is not already in the reference table,
&nbsp;&nbsp;&nbsp; append this object to the reference table.</pre>
</blockquote>

Each object can then be serialized from the reference table in order.

<p>For example, assume that we have the following tree structure:
<center> <p><img SRC="./javax/microedition/m3g/doc-files/FileFormat-8-1.png"
ALT="Tree with node A as root, B under A, C and D under B, E under A again, and F under E" height=199 width=433></center>

<p>One valid ordering of the objects is C D F B E A. This is the
ordering that occurs if the "leaves first" method is used. Note that
other leaf-first orderings are also valid, for instance F D C E B A.

<p>The "depth-first" method produces valid orderings where interior
nodes in the graph may be sent before all the leaves have been
sent. An ordering produced by the depth-first method discussed above
might be C D B F E A.

<p>The only important thing is that any objects referenced by a
particular object are sent before the object itself.

<p>With this flexibility, the ordering of references can be forced by
the file creator if this is advantageous. For example, if we wish
textures to be sent in a separate section that is uncompressed. Thus,
if we have the following tree:

<center> <p><img SRC="./javax/microedition/m3g/doc-files/FileFormat-8-2.png"
ALT="Tree with node A as root, B under A, T1 and D under B, E under A again, and T2 under E" height=199 width=433></center>

<p>where T1 and T2 are textures, we can send the scene graph using,
for instance:

<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 class="Table" >
<tr>
<td>Identifier</td>

<td>&nbsp;</td>

<td>File Identifier (see <a href="#FileIdentifier">Section 5</a>)</td>
</tr>

<tr>
<td>Section 0</td>

<td>Uncompressed</td>

<td>File Header Object</td>
</tr>

<tr>
<td>Section 1</td>

<td>Uncompressed</td>

<td>T1 T2</td>
</tr>

<tr>
<td>Section 2</td>

<td>Compressed</td>

<td>D B E A</td>
</tr>
</table>
</blockquote>
Other orderings are also possible, for instance:
<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 class="Table" >
<tr>
<td>Identifier</td>

<td>&nbsp;</td>

<td>File Identifier (see <a href="#FileIdentifier">Section 5</a>)</td>
</tr>

<tr>
<td>Section 0</td>

<td>Uncompressed</td>

<td>File Header Object</td>
</tr>

<tr>
<td>Section 1</td>

<td>Uncompressed</td>

<td>T1 T2</td>
</tr>

<tr>
<td>Section 2</td>

<td>Compressed</td>

<td>D E B A</td>
</tr>
</table>
</blockquote>
or even (with a naive file creator):
<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 class="Table" >
<tr>
<td>Identifier</td>

<td>&nbsp;</td>

<td>File Identifier (see <a href="#FileIdentifier">Section 5</a>)</td>
</tr>

<tr>
<td>Section 0</td>

<td>Uncompressed</td>

<td>File Header Object</td>
</tr>

<tr>
<td>Section 1</td>

<td>Uncompressed</td>

<td>T1</td>
</tr>

<tr>
<td>Section 2</td>

<td>Compressed</td>

<td>D</td>
</tr>

<tr>
<td>Section 3</td>

<td>Uncompressed</td>

<td>T2</td>
</tr>

<tr>
<td>Section 4</td>

<td>Compressed</td>

<td>B E A</td>
</tr>
</table>
</blockquote>

Because multiple root-level objects are allowed in the file format,
there is no obvious end point in the data. In order that the loader
can determine that the file has ended, the total length of the file is
stored in the header. Reading from the file is ended when the total
number of bytes is reached. At this point, any objects not yet linked
into the scene graph are treated as root-level objects and returned to
the application.

<h3>
<a NAME="ObjectReferences"></a>8.1 Object References</h3>

Each object serialized, including the header object, is given an
index, in order, starting from 1. The 0 index is used to indicate a
null reference. This index is unrelated to the user ID for an object.

<p>A reference to an object is serialized as an integer containing its
index within the file. The serialization order constraint can be
expressed as follows:

<p>For an object with index <b>i</b>, a reference index <b>r</b>
within it is only valid if <b>r</b> &lt;= <b>i</b>. Invalid reference
indices must be treated as an error.

<p>An object reference must refer to an object of a valid type for the
reference involved. For example, the reference from an Appearance
object to a Material object must actually refer to a Material object.
If the referred object type is incorrect, this must be treated as an
error.

<h3>
<a NAME="SharedObjects"></a>8.2 Shared Objects</h3>

Shared objects are handled the same way as normal objects. We only
need to make sure that a shared object is sent before both of the
objects that reference it.

<p>For instance, for the following tree of references, where X is a
shared object

<center> <p><img SRC="./javax/microedition/m3g/doc-files/FileFormat-8-3.png"
ALT="Tree with node A as root, B under A, X and D under B, E under A again, and X shared under E" height=199 width=237></center>

<p>A possible ordering would be D X B E A. Both the leaves-first and
the depth-first algorithms described above will generate valid
orderings.

<h3><a NAME="SubtreeLoading"></a>8.3 Subtree Loading</h3>

With reference based order, it will be more difficult to load an arbitrary
subtree from a file than with, e.g., root-first order. However, it is still
possible, using two passes of the file. Assume that the subtree is defined
as "object number X and all its children". In the first pass, only the
node references are decoded, and an empty tree of the complete scene graph
is created. From this graph, we find node X and make a list of all its
descendants in the subtree. During the second pass, we simply load all
the objects in the list. The last object that was loaded will be the root
of the subtree.

<p>In the case where rewinding the stream is not possible, it is also
possible to do subtree loading in just one pass. This is achieved by
loading everything up until the root node of the desired subtree, and
then letting the garbage collection remove everything that is not
referred to by the subtree. However, such an implementation would
consume more memory than the two-pass implementation above. In the
worst case, this is no different from loading the entire scene. For
example, if the file contains a 3D map of the whole world and all you
want is a specific house, you may still need to load the entire world
and then delete everything but the house, if the house is the last
object in the file.

<h2 class="SectionTitle">
<a NAME="ErrorHandling"></a>9 Error Handling</h2>

There are several points at which an error may be detected. These include,
but are not limited to:

<ul>
<li>Memory exhaustion</li>
<li>Missing or malformed file identifier</li>
<li>Invalid section type</li>
<li>Invalid file, section, or object length</li>
<li>Invalid section checksum</li>
<li>Invalid object type</li>
<li>Extra or missing object data</li>
<li>Invalid object reference</li>
<li>Invalid enumeration value</li>
<li>Invalid boolean value</li>
<li>Invalid floating point value</li>
<li>Values out of range for property</li>
<li>Attempt to read past end of stream</li>
<li>Aborted download</li>
<li>Error in external reference</li>
</ul>

In particular, if values read from the loaded file would cause an
<i>immediate</i> exception when passed to the API (e.g. all the
attenuation parameters on a light are 0.0, or an image is too large
for the implementation to handle), then this must be treated as an
error.

<p>If combinations of values are read that may cause a <i>deferred</i>
exception, (e.g. a material and light are both present, but there are no
normals specified), then this must <i>not</i> be treated as an error by
the Loader. The application must be given the opportunity to take action