📄 file-format.html
字号:
after loading, in order to avoid these exceptions.
<p>If any kind of error is detected during loading, the required
action is for the Loader to abort this download, and that of any
pending external references, clear up any temporary data structures,
and throw an exception. If this file is being used as an external
reference, then this is also treated as an error in the file that is
attempting to load it. (This definition is, of course, recursive.)
<p>The practical upshot of this is that any error detected in any of
the files that may make up a world being loaded must result in a safe
abort of the loading process and the throwing of a single exception to
the main application.
<p>It is up to the application what action, if any, is taken in the
event of a loading error. Options range from an apologetic alert to
the user ("Download failed!"), up through sophisticated error recovery
schemes involving alternate file locations, or even different content
in extreme cases.
<h2 class="SectionTitle">
<a NAME="SpecialObjectData"></a>10 Special Object Data</h2>
The data for the "special" object types is documented here.
<h3><a NAME="Header"></a>10.1 Header Object</h3>
Object Type: 00
<br>Superclass data: <i>none</i>
<br>Followed by:
<blockquote>
<pre>Byte[2] VersionNumber
Boolean hasExternalReferences
UInt32 TotalFileSize
UInt32 ApproximateContentSize
String AuthoringField</pre>
</blockquote>
There must be exactly one Header object in a file, and it must be the
only object in the first section of the file, which in turn must be
uncompressed. Due to its position in the file, it will always be
assigned object index 1.
<p><tt>VersionNumber</tt> is a unique version number identifying variants
of the file fomat. Only one variant is currently specified: version number
1.0. This must be indicated by <tt>VersionNumber = {1, 0}</tt>. The first
number is major revision number, followed by minor revision.
<p><tt>hasExternalReferences</tt> is a boolean that describes whether
this file is self-contained or includes URIs for other files, such as
textures or geometries. If this is <tt>false</tt>, the file is
self-contained. If it is <tt>true</tt>, then it indicates that the
immediately following section of the file will contain the external
reference objects needed to specify these external links. See <a
href="#ExternalReference">Section 10.2</a> for more details.
<p><tt>TotalFileSize</tt> is the total size of the file, from the
start to the end. It will be used in the loading, so it must be
correct. (That is, it is not a hint.) For example, a file of size 6783
would define this field as <tt>TotalFileSize = 6783</tt>.
<p><tt>ApproximateContentSize</tt> contains the total number of bytes
required to dowload the entire scene, including external links such as
textures and geometry. This is provided as a hint, so that the user
can know how much data he/she will pay for before loading the entire
scene. The <tt>ApproximateContentSize</tt> field is also necessary in
order to produce a good progress bar during the loading of the scene.
<p>It should be noted that this information is only a hint. For
instance, the file sizes of the objects that this file is linked to
might have changed. Due to this, it is called "approximate" content
size. Note that <tt>ApproximateContentSize</tt> should be equal to
<tt>TotalFileSize</tt> if <tt>ExternalFiles</tt> is false.
<p>For example, a file of 6083 bytes, with an external reference to
another file of 10700 bytes would set <tt>ApproximateContentSize =
16783</tt>.
<p><tt>AuthoringField</tt> consists of a single nul-terminated UTF-8
string. The content of the string is not defined, and may include any
information that the authoring environment wishes to place into
it. Its most common purpose is mainly to make it possible to put a
copyright note on the file, for example: <tt>AuthoringField =
"Blast4Fun (C) 2003 Extreme Games Inc."</tt>
<p>Note that if the string just contains numbers and letters from the
English alphabet, the UTF-8 encoding will be the same as ASCII
encoding.
<h3>
<a NAME="ExternalReference"></a>10.2 External Reference</h3>
ObjectType: 0xFF (255)
<br>Superclass data: <i>none</i>
<br>Followed by:
<blockquote>
<pre>String URI</pre>
</blockquote>
Instead of storing an object in-place, it is possible to have an
external reference, in the form of a URI. This is stored in the object
data as a single, nul-terminated UTF-8 string.
<p>Relative URIs are relative to the file in which they are found, as
usual. For example, a URI of "http://www.gamesforfun.com/objs/redcar.m3g",
indicates another file in the M3G file format, at an absolute address, and
"bluecartexture.png" indicates a PNG file in the same location as the
current file.
<p>If an external reference cannot be loaded, this will result in an
error, causing the parent file to be "unloadable".
<p>Loops of external references (e.g. file A references file B which in
turn references file A again) are illegal and will result in a loading
error.
<p>The loader must only indicate that the loading of a file is complete
when all external references within it have also been successfully loaded
and the references type checked.
<p>External references may appear only within their own section within
the file. If present, this appears immediately after the file header
section. It may be compressed or uncompressed.
<p>In order to facilitate type checking of external references, loading
of the externally referenced file must complete before reading any objects
which could refer to it. This is one of the main reasons for ensuring that
external references are in their own section, which occurs before sections
containing objects of other types. For example, if the external reference
is referred to as if it were an Appearance object, then the check that
it is indeed an Appearance can occur only after loading the referred file.
<p>External reference loading must support both M3G and PNG file types
in order to satisfy the specification. An external reference to any
other type of file must be treated as an error. To stress the point,
even if a particular format (e.g., JPEG) is otherwise supported by
the Loader, it must still reject any M3G files that reference JPEG
images.
<p>For M3G format files, the external reference must be able to load
another M3G format file containing a single root-level object. If more
than one root-level object is defined, then the first root-level
object will be used, and the other objects and their descendants
discarded.
<p>For PNG format files, the external reference must be able to
reference a valid PNG file, in which case the object created is a
single instance of Image2D. PNG loaders are not required to support
48-bit pixel formats.
<p>In all cases, once loading completes, the single root-level object
loaded from the file effectively replaces the external reference
object in the object index table. References to that index will then
nominate the root-level object.
<h2 class="SectionTitle">
<a NAME="PerClassData"></a>11 Per-Class Data</h2>
The data for each class in the API is now presented in alphabetical
order. Where a class is a subclass, the superclass's data is always
output first, and this information is taken to be part of the data for
the class as a whole.
<p>Classes without a serialized form (e.g. Graphics3D) are shown here
for completeness, but are indicated as "not a serializable class".
<p>Detailed information about each field is not given - it should be
assumed that the data have the same meanings as those assigned in the
API. Where data is serialized in a form which is different from the
way it is specified in the API, this alternate form is documented
here.
<p>Any values which would be invalid as arguments to the corresponding
methods in the API are also invalid in the file and must be reported as
errors. For example, a negative value in the light attenuation fields is
disallowed by the API and is therefore also disallowed in the file format.
<h3><a NAME="AnimationController"></a>11.1 AnimationController</h3>
ObjectType: 01
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>Float32 speed;
Float32 weight;
Int32 activeIntervalStart;
Int32 activeIntervalEnd;
Float32 referenceSequenceTime;
Int32 referenceWorldTime;</pre>
</blockquote>
<h3>
<a NAME="AnimationTrack"></a>11.2 AnimationTrack</h3>
ObjectType: 02
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>ObjectIndex keyframeSequence;
ObjectIndex animationController;
UInt32 propertyID;</pre>
</blockquote>
The <tt>propertyID</tt> field must hold a valid <a href="javax/microedition/m3g/AnimationTrack.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<h3>
<a NAME="Appearance"></a>11.3 Appearance</h3>
ObjectType: 03
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>Byte layer;
ObjectIndex compositingMode;
ObjectIndex fog;
ObjectIndex polygonMode;
ObjectIndex material;
ObjectIndex[] textures;</pre>
</blockquote>
These are simply references to each of the objects aggregated together
to form an appearance.
<p>There are as many texture objects in the textures array as there are
active texture units for this appearance. The texture units are loaded
sequentially from unit 0. If the implementation supports more texture units
than are specified, these are left in their default, inactive state, with
a null texture.
<p>If more textures are specified than are supported by the implementation,
then this must be treated as an error, as it would be in the API. The application
can then decide on an appropriate course of action to handle this case.
<h3>
<a NAME="Background"></a>11.4 Background</h3>
ObjectType: 04
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>ColorRGBA backgroundColor;
ObjectIndex backgroundImage;
Byte backgroundImageModeX;
Byte backgroundImageModeY;
Int32 cropX;
Int32 cropY;
Int32 cropWidth;
Int32 cropHeight;
Boolean depthClearEnabled;
Boolean colorClearEnabled;</pre>
</blockquote>
The <tt>backgroundImageModeX</tt> and <tt>backgroundImageModeY</tt> fields
must each hold a valid <a href="javax/microedition/m3g/Background.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<h3>
<a NAME="Camera"></a>11.5 Camera</h3>
ObjectType: 05
<br>Superclass data: <a href="#Node">Node</a>
<br>Followed by:
<blockquote>
<pre>Byte projectionType;
<i>IF projectionType==GENERIC, THEN
</i> Matrix projectionMatrix;
<i>ELSE
</i> Float32 fovy;
Float32 AspectRatio;
Float32 near;
Float32 far;
<i>END</i></pre>
</blockquote>
The <tt>projectionType</tt> field must hold a valid <a href="javax/microedition/m3g/Camera.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<h3>
<a NAME="CompositingMode"></a>11.6 CompositingMode</h3>
ObjectType: 06
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>Boolean depthTestEnabled;
Boolean depthWriteEnabled;
Boolean colorWriteEnabled;
Boolean alphaWriteEnabled;
Byte blending;
Byte alphaThreshold;
Float32 depthOffsetFactor;
Float32 depthOffsetUnits;</pre>
</blockquote>
The <tt>blending</tt> field must hold a valid <a href="javax/microedition/m3g/CompositingMode.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<p>The <tt>alphaThreshold</tt> field is stored as a byte to save space.
It is mapped so that 0x00 is equivalent to 0.0 (completely transparent),
and 0xFF is equivalent to 1.0 (completely opaque).
<h3>
<a NAME="Fog"></a>11.7 Fog</h3>
ObjectType: 07
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>ColorRGB color;
Byte mode;
<i>IF mode==EXPONENTIAL, THEN
</i> Float32 density;
<i>ELSE IF mode==LINEAR, THEN
</i> Float32 near;
Float32 far;
<i>END</i>
</pre>
</blockquote>
The <tt>mode</tt> field must hold a valid <a href="javax/microedition/m3g/Fog.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<h3>
<a NAME="Graphics3D"></a>11.8 Graphics3D</h3>
<i>Not a serializable class.</i>
<h3>
<a NAME="Group"></a>11.9 Group</h3>
ObjectType: 09
<br>Superclass data: <a href="#Node">Node</a>
<br>Followed by:
<blockquote>
<pre>ObjectIndex[] children;</pre>
</blockquote>
<h3>
<a NAME="Image2D"></a>11.10 Image2D</h3>
ObjectType: 10
<br>Superclass data: <a href="#Object3D">Object3D</a>
<br>Followed by:
<blockquote>
<pre>Byte format;
Boolean isMutable;
UInt32 width;
UInt32 height;
<i>IF isMutable==false, THEN
</i> Byte[] palette;
Byte[] pixels;</pre>
<i>END</i></blockquote>
The <tt>format</tt> field must hold a valid <a href="javax/microedition/m3g/Image2D.html#field_summary">enumerated
value</a>, as specified in the class definition. Other values must be treated
as errors.
<p>For a palettised format, the <tt>pixels</tt> array contains a single
palette index per pixel, and the <tt>palette</tt> array will contain up
to 256 entries, each consisting of a pixel specifier appropriate to the
format chosen.
<p>For a non-palettised format, the <tt>palette</tt> array will be empty,
and the <tt>pixels</tt> array contains a pixel specifier appropriate to
the format chosen.
<p>In a pixel specifier, each byte is scaled such that 0 represents the
value 0.0 and 255 represents the value 1.0. The different formats require
different data to be serialized, as follows:
<ul>
<li>
ALPHA: a single byte per pixel, representing pixel opacity.</li>
<li>
LUMINANCE: a single byte per pixel, representing pixel luminance.</li>
<li>
LUMINANCE_ALPHA: two bytes per pixel. The first represents luminance, the
second alpha.</li>
<li>
RGB: three bytes per pixel, representing red, green and blue respectively.</li>
<li>
RGBA: four bytes per pixel, representing red, green, blue and alpha respectively.</li>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -