file-format.html

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

<h3>
<a NAME="CompoundDataTypes"></a>3.2 Compound Data Types</h3>
In order to avoid having to repeatedly specify sequences of the same types
many times, some compound data types are defined for convenience. The composition
of these is listed to show both their makeup and the order in which the
simple elements are to be serialized. These are as follows:
<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 WIDTH="90%" class="Table" >
<caption><!-- <caption align=top>&nbsp;</caption> --></caption>

<tr>
<th WIDTH="20%">
<div class="TableHead">Type Name</div>
</th>

<th WIDTH="60%">
<div class="TableHead">Description</div>
</th>

<th WIDTH="20%">
<div class="TableHead">Composition</div>
</th>
</tr>

<tr>
<td>
<div class="TableText">Vector3D</div>
</td>

<td>
<div class="TableText">A 3D vector.</div>
</td>

<td><tt>Float32 x;</tt>
<br><tt>Float32 y;</tt>
<br><tt>Float32 z;</tt></td>
</tr>

<tr>
<td>
<div class="TableText">Matrix</div>
</td>

<td>
<div class="TableText">A 4x4 generalized matrix. The 16 elements of the
matrix are output in the same order as they are retrieved using the API
Transform.get method. In other words, in this order:
<blockquote>
<pre>&nbsp; 0&nbsp; 1&nbsp; 2&nbsp; 3
&nbsp; 4&nbsp; 5&nbsp; 6&nbsp; 7
&nbsp; 8&nbsp; 9&nbsp; 10 11
&nbsp; 12 13 14 15</pre>
</blockquote>
</div>
</td>

<td><tt>Float32 elements[16];</tt></td>
</tr>

<tr>
<td>
<div class="TableText">ColorRGB</div>
</td>

<td>
<div class="TableText">A color, with no alpha information. Each component
is scaled so that 0x00 is 0.0, and 0xFF is 1.0.</div>
</td>

<td><tt>Byte red;</tt>
<br><tt>Byte green;</tt>
<br><tt>Byte blue;</tt></td>
</tr>

<tr>
<td>
<div class="TableText">ColorRGBA</div>
</td>

<td>
<div class="TableText">A color, with alpha information. Each component
is scaled so that 0x00 is 0.0, and 0xFF is 1.0. The alpha value is scaled
so that 0x00 is completely transparent, and 0xFF is completely opaque.</div>
</td>

<td><tt>Byte red;</tt>
<br><tt>Byte green;</tt>
<br><tt>Byte blue;</tt>
<br><tt>Byte alpha;</tt></td>
</tr>

<tr>
<td>
<div class="TableText">ObjectIndex</div>
</td>

<td>
<div class="TableText">The index of a previously encountered object in
the file. Although this is serialized as a single unsigned integer, it
is included in the compound type list because of the additional semantic
information embodied in its type. A value of 0 is reserved to indicate
a null reference; actual object indices start from 1. Object indices must
refer only to null or to an object which has already been created during
the input deserialization of a file - they must be less than or equal to
the index of the object in which they appear. Other values are disallowed
and must be treated as errors.</div>
</td>

<td><tt>UInt32 index;</tt></td>
</tr>

<tr>
<td>
<div class="TableText"><i>Type</i>[]</div>
</td>

<td>
<div class="TableText">A variable-length array of any type is always output
in a counted form, with the count first. Each element is then output in
index order, starting from 0. The last element has index (count-1). If
the array is empty, then only a 0 count is output.</div>
</td>

<td><tt>UInt32 count;</tt>
<br><i>Type</i> <tt>arrayValue[0];</tt>
<br><i>Type</i> <tt>arrayValue[1];</tt>
<br><i>...etc.</i></td>
</tr>

<tr>
<td>
<div class="TableText"><i>Type</i>[<i>count</i>]</div>
</td>

<td>
<div class="TableText">Arrays with an explicit length are either always
have the same constant number of elements, or this count is specified elsewhere,
so only the elements are output. Each element is then output in index order,
starting from 0. The last element has index (length-1). If the array is
empty, then nothing is output.</div>
</td>

<td><i>Type</i> <tt>arrayValue[0];</tt>
<br><i>Type</i> <tt>arrayValue[1];</tt>
<br><i>...etc.</i></td>
</tr>
</table>
</blockquote>

<h2 class="SectionTitle">
<a NAME="FileStructure"></a>4 File Structure</h2>
The file consists of the file identifier, followed by one or more sections.
Thus the overall file structure looks like this:
<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 class="Table" >
<tr>
<td>&nbsp;</td>

<td>File Identifier</td>
</tr>

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

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

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

<td>External Reference Objects</td>
</tr>

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

<td>Scene Objects</td>
</tr>

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

<td>Scene Objects</td>
</tr>

<tr>
<td>...</td>

<td>...</td>
</tr>

<tr>
<td>Section <i>n</i></td>

<td>Scene Objects</td>
</tr>
</table>
</blockquote>
The reason for having different sections is that some of the objects, such
as the mesh objects, should be compressed to reduce file size, whereas
other objects, such as the header object, should not be compressed. The
header object must be kept uncompressed since it should be easy to read
quickly.
<p>The first section, Section 0, must be present, must be uncompressed
and must contain only the header object. This object contains information
about the file as a whole, and is discussed in detail in
<a href="#HeaderObject">Section
10.1</a>.
<p>If there are external references in the file, then these must all appear
in a single section immediately following the header section. This section
may be compressed or uncompressed. External references allow scenes to
be built up from a collection of separate files, and are discussed in detail
in
<a href="#ExternalReference">Section 10.2</a>.
<p>Following these are an unspecified number of sections containing scene
objects.
<p>The file must contain the header section, plus at least one other non-empty
section (containing at least one object). It is possible to have a file
consisting solely of external references, or solely of scene objects.
<p>A file containing no objects at all is not a valid M3G file, and must
be treated as an error.
<h2 class="SectionTitle">
<a NAME="FileIdentifier"></a>5 File Identifier</h2>
The file identifier is a unique set of bytes that will differentiate the
file from other types of files. It consists of 12 bytes, as follows:
<blockquote>
<pre>Byte[12] FileIdentifier = { 0xAB, 0x4A, 0x53, 0x52, 0x31, 0x38, 0x34, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A }</pre>
</blockquote>
This can also be expressed using C-style character definitions as:
<blockquote>
<pre>Byte[12] FileIdentifier = { '&laquo;', 'J', 'S', 'R', '1', '8', '4', '&raquo;', '\r', '\n', '\x1A', '\n' }</pre>
</blockquote>
The rationale behind the choice values in the identifier is based on the
rationale for the identifier in the PNG specification. This identifier
both identifies the file as a M3G file and provides for immediate detection
of common file-transfer problems.
<ul>
<li>
Byte [0] is chosen as a non-ASCII value to reduce the probability that
a text file may be misrecognized as a M3G file.</li>

<li>
Byte [0] also catches bad file transfers that clear bit 7.</li>

<li>
Bytes [1..6] identify the format, and are the ascii values for the string
"JSR184".</li>

<li>
Byte [7] is for aesthetic balance with byte 1 (they are a matching pair
of double-angle quotation marks).</li>

<li>
Bytes [8..9] form a CR-LF sequence which catches bad file transfers that
alter newline sequences.</li>

<li>
Byte [10] is a control-Z character, which stops file display under MS-DOS,
and further reduces the chance that a text file will be falsely recognised.</li>

<li>
Byte [11] is a final line feed, which checks for the inverse of the CR-LF
translation problem.</li>
</ul>
A decoder may further verify that the next byte is 0 (this is the first
byte of the mandatory uncompressed header section). This will catch bad
transfers that drop or alter zero bytes.
<h2 class="SectionTitle">
<a NAME="Section"></a>6 Section</h2>
A section is a data container for one or more objects. The section header
determines if the objects are compressed or not, how much object data there
is, and also contains a checksum.
<p>In this document, we will talk about "sections that are compressed"
and "sections that are uncompressed". In reality, we will mean "sections
where the objects are compressed", and "sections where the objects are
uncompressed".
<p>Each section has the following structure:
<blockquote>
<pre>Byte&nbsp;&nbsp; CompressionScheme
UInt32 TotalSectionLength
UInt32 UncompressedLength
Byte[] Objects
UInt32 Checksum</pre>
</blockquote>
We will now go through the individual parts of the section.
<h3>
<a NAME="CompressionScheme"></a>6.1 CompressionScheme</h3>
This field tells how the <tt>Objects</tt> field in this section is compressed.
It also specifies what checksum algorithm is used. Currently, only the
Adler32 checksum is mandatory. Compression only applies to the <tt>Object</tt>
data, and not to the other fields in the section.
<p><tt>CompressionScheme</tt> must be one of the following values:
<blockquote>&nbsp;
<table BORDER CELLSPACING=0 CELLPADDING=3 class="Table" >
<tr>
<td>0</td>

<td>Uncompressed, Adler32 Checksum</td>
</tr>

<tr>
<td>1</td>

<td>ZLib compression, 32 k buffer size, Adler32 Checksum</td>
</tr>

<tr>
<td>2...255</td>

<td>Reserved</td>
</tr>
</table>
</blockquote>
Example:
<blockquote>
<pre>Byte CompressionScheme = 1;</pre>
</blockquote>
indicates that the <tt>Objects</tt> field in the section is compressed
using zlib with 32 k buffer size.
<p>The values 2...255 are reserved for future releases and are disallowed.
A loader that follows the specification must report an error if they are
found.
<h3>
<a NAME="TotalSectionLength"></a>6.2 TotalSectionLength</h3>
This is the total length of the section in bytes; from the start of this
section to the start of the next section.
<p>Example:
<blockquote>
<pre>UInt32 TotalSectionLength = 2056</pre>
</blockquote>
indicates that this section, including the <tt>CompressionScheme</tt>,
<tt>TotalSectionLength</tt>,
<tt>UncompressedLength</tt>,
<tt>Objects</tt>
and <tt>Checksum</tt> fields, will be 2056 bytes in length.
<h3>
<a NAME="UncompressedLength"></a>6.3 UncompressedLength</h3>
Knowing the size of the decompressed data ahead of time can be used to
make Zlib inflation much easier and less memory hungry. Therefore, the
size of the compressed part of the section (in bytes) before compression
(or after decompression) is serialized as part of the section information.
Since it is only the <tt>Objects</tt> field that can be compressed,
<tt>UncompressedLength</tt>
contains the length of the <tt>Objects</tt> field after decompression.
If no compression is specified for this section, this equals the actual
number of bytes serialized in the <tt>Objects</tt> array.
<p>A value of 0 in this field is legal - the section is simply ignored.
However, it is recommended that any process that creates a file should
check for 0 length sections and eliminate them to reduce file size.
<p>Example:
<blockquote>
<pre>UInt32 UncompressedLength = 4560</pre>
</blockquote>
Means that in this section, after decompression, the <tt>Objects</tt> field
is 4560 bytes in length.
<h3>
<a NAME="Objects"></a>6.4 Objects</h3>
The objects in each section are serialized as an array of bytes, one after
the other. This array of bytes will either be compressed (if CompressionScheme
is 1) or it will be uncompressed. If it is compressed, it is compressed
as a single chunk of data, not as separate objects. Zero bits must be padded
in the end to make the <tt>Objects</tt> field byte aligned.
<p>The structure of each individual object's data is documented in <a href="#SpecialObjectData">Section
10</a> and <a href="#PerClassData">Section 11</a>.
<h3>
<a NAME="Checksum"></a>6.5 Checksum</h3>
To be able to verify that the section was correctly loaded, there is a
32-bit checksum of all the data in the section. The checksum algorithm
is specified by the <tt>CompressionScheme</tt> field. Currently, only the
Adler32 checksum is mandatory. The checksum is calculated using all preceding
bytes in the section, i.e. the
<tt>CompressionScheme</tt>,<tt>TotalSectionLength</tt>,
<tt>UncompressedLength</tt>,
and the actual serialized data in the <tt>Objects</tt> field (i.e. in its
compressed form if compression is specified).
<p>Example: