package-summary.html

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

for scene graph objects and individually rendered objects alike. The developer
therefore does not need to choose between the immediate mode and the scene
graph, but rather can mix and match both within the same application.</p>

<p>Besides the API itself, a corresponding <a
href="../../../file-format.html">file format</a> for efficient
storage and transfer of all necessary data is also defined.  This data
includes meshes, textures, scene hierarchies, material properties,
animation keyframes, and so on. Data is written into a file by content
creation tools on a PC, and loaded into the API through the Loader
class.</p>

<p>The <a href="#ExampleMidlets">example applications</a> at the end
of this page provide a good means to get a quick overview of this
API. Of the individual classes, <A HREF="../../../javax/microedition/m3g/Graphics3D.html"><CODE>Graphics3D</CODE></A> is perhaps the most important,
because all rendering is done there. The <A HREF="../../../javax/microedition/m3g/World.html"><CODE>World</CODE></A> class is crucial because it serves as
the root of the scene graph structure.  <A HREF="../../../javax/microedition/m3g/Object3D.html"><CODE>Object3D</CODE></A> is the base class of all objects that
can be rendered or loaded from a file, and also the place where
animations are applied. We also recommend you to read the short
section about documentation conventions below.</p>

<h2><a NAME="Conventions"></a>Documentation Conventions</h2>

<p>The following general conventions are observed in the documentation of
this API.</p>

<ul>

<p><li><b>Deferred exceptions.</b> Most exceptions are thrown immediately upon
method invocation, when erroneous input is detected. However, the application
is in some cases allowed to bring an object, or an aggregate of objects,
into an invalid state. There are four operations that may throw an exception
as a result of their input or host object being in an invalid state: the
<tt>render</tt> methods in Graphics3D, the <tt>pick</tt> methods in Group,
the <tt>align</tt> method in Node, and the <tt>animate</tt> method in
Object3D.</li></p>

<p><li><b>Matrix notation.</b> Matrices are denoted as upper case bold letters,
and vectors as lower case bold letters. For example, <b>M</b> denotes a
matrix and <b>v</b> a vector. Matrices have 4x4 and vectors 4 elements,
unless stated otherwise. Vectors are always column vectors, and are
consequently on the right hand side when multiplied with a matrix:
<b>v'</b> = <b>M</b> <b>v</b>.</li></p>

<p><li><b>Numeric intervals.</b> Closed intervals are denoted with
square brackets and open intervals with round brackets. For example,
[0, 10) denotes the values from zero to ten, including zero but not
including ten. Depending on the context, a numeric interval may
consist of real numbers or integers.</li></p>

<p><li><b>OpenGL references.</b> All references to OpenGL in this
specification are to version 1.3. See Related Literature on the
overview page.</li></p>

<p><li><b>Coordinate systems.</b> All 2D coordinate systems follow the
MIDP convention where the origin is in the upper left corner and
integer coordinates are at pixel boundaries. By default, the 3D
coordinate systems are right-handed, and all rotations obey the
right-hand rule: looking along the positive axis of rotation, positive
angles are clockwise. The camera coordinate system follows the OpenGL
convention where the view direction coincides with the negative
z-axis, the positive x-axis points right and positive y-axis points
up. However, the application is free to set up left-handed 3D
coordinate systems by use of transformation matrices.</li></p>

<p><li><b>Diagram notation.</b> The following common notation is used
in diagrams that involve scene graph nodes and node
components.</li></p>

</ul>

<center><img SRC="./doc-files/Package-key.png" ></center>

<h2>Package Discovery</h2>

<p>Because of its optional nature, this API may not always be available on
every platform. Each profile and platform may have their own methods for
J2ME package discovery as there is no universal method existing at this
time. An additional method for package discovery of the Mobile 3D Graphics
API is by using a system properties query. To discover this package, call
<tt>System.getProperty</tt> with a key of <tt>microedition.m3g.version</tt>.
If the API is present, the value returned is the version of the API
(currently "1.0"). If the API is not present then the key is also not
present and <tt>null</tt> will be returned.</p>

<h2><a NAME="Requirements"></a>General implementation requirements</h2>

<h3><a NAME="NumericRange"></a>Dynamic range and accuracy</h3>

<p>The floating point format used for input and output is the standard IEEE
float, having an 8-bit exponent and a 24-bit mantissa normalized to [1.0,
2.0). To facilitate efficient operation without floating point hardware,
implementations are allowed to substitute more constrained representations
internally. The internal representation must satisfy the following
requirements:</p>

<ul>

<p><li><b>The input range must be at least [2<sup>-64</sup>,
2<sup>63</sup>].</b> Any floating-point value in this range is legal
as input to a method that accepts floating point numbers. If the input
value is not within that range, or is not a floating-point number
(NaN), the result is undefined.</li></p>

<p><li><b>Elementary operations must have a range of at least
[2<sup>-64</sup>, 2<sup>63</sup>].</b> If the operands and the result
of an elementary arithmetic operation are within this range, the
operation must not overflow or underflow.  If the operands and/or the
result are not within that range, the result is undefined.</li></p>

<p><li><b>The precision must be at least 16 significant bits.</b> Provided
that both the operands and the result of an elementary arithmetic operation
are within the range specified above, the result must be accurate to at
least 16 significant bits.</li></p>

</ul>

<p>These requirements apply to all arithmetic operations in this API, except
triangle rasterization and per-fragment operations, such as depth buffering,
blending, and interpolation of colors and texture coordinates. In particular,
the requirements apply to node transformations in the scene graph; vertex
coordinate, texture coordinate and normal vector transformations; picking;
keyframe interpolation; mesh morphing; skinning; and all methods in the
Transform class.</p>

<p>Blending, interpolation, comparisons and other operations on color, alpha
and (screen-space) depth values must have at least the same precision as the
corresponding channel in the frame buffer. The minimum frame buffer resolution
is 1 bit for alpha and each color component, and 8 bits for depth. Of course,
if some of the channels do not exist, the corresponding values need not be
computed.</p>

<a name="blending"></a>

<p>All color and alpha blending operations are done component-wise and
saturated to 1.0. In addition to the general precision requirements,
blending operations must also satisfy the following for all values of
<i>alpha</i> and <i>s</i> between [0, 1]:</p>

<blockquote>
alpha * s + (1 - alpha) * s = s
</blockquote>

<h3><a NAME="getters">Correspondence of getters and setters</a></h3>

<p>When querying the value of some property in the API, the returned
value does not need to be exactly the same that was set with the
corresponding <code>set</code> method. Instead, it may be any value
that <i>produces an equivalent result</i>. The returned values are
also not required to be in any "canonical" or "normalized" form.  In
the case of node orientation, for example, there are a number of
different axis-angle combinations that specify the same orientation,
and any one of them may be returned.</p>

<p>The returned value may also be an approximation of the original
value, as long as the accuracy constraints for the particular type of
data are satisfied.</p>

<h3><a NAME="references">References to Objects</a></h3>

<p>Unless otherwise stated, Object3Ds are held by reference, not by
copying their data. Changes to the original object therefore have
immediate effect in the data structure as a whole. For example,
changes to an Image2D attached to the Background take effect without
having to call the <code>Background.setImage</code> method again.</p>

<p>Where exceptions exist, these will be clearly documented as copying
the values from the supplied Object3D.</p>

<h3>Thread safety</h3>

<p>Implementations must not crash or throw an exception as a result of
being accessed from multiple threads at the same time. However, the
results of the requested operation in that case may be
unpredictable.</p>

<p>No method in this API is allowed to block waiting for a resource,
such as a rendering target, to be released. This is to guarantee that
no deadlock situations will occur. Also, any resources required by a
method must be released upon return. No method is allowed to leave its
host object or other resources locked.</p>

<h3><a NAME="PixelFormats"></a>Pixel format conversion</h3>

<p>Several different pixel formats are supported in rendering targets,
textures, sprites, and background images. Depending on the case, a
mismatch between the source and destination pixel formats may require
a format conversion to be done. The general rules that are obeyed
throughout the API are as follows:</p>

<ul>
<li>Luminance to RGB: The luminance value (L) is replicated to each of R, G
and B.</li>

<li>RGB to Luminance: Unspecified, but must take all components into
account. For example, (R+G+B) / 3.</li>

<li>Any missing luminance, color or alpha components are set to 1.0, unless
explicitly stated otherwise.</li>
</ul>

<p>More specific rules related to pixel formats are specified on a
case-by-case basis in classes dealing with images and the frame
buffer. These include Graphics3D, Image2D, Texture2D, CompositingMode
and Background.</p>

<h2><a NAME="ExampleMidlets"></a>Example applications</h2>

<p>Two example MIDlets using the API are presented below. The first
MIDlet is a pure immediate mode application that displays a rotating,
texture-mapped cube. It shows how to initialize a 3D graphics context,
bind it to a MIDP Canvas, and render some simple content with it. It
also illustrates how to create a Mesh object "manually", that is, how
to set up the coordinates, triangle connectivity, texture maps, and
materials. In practice, this is usually not done programmatically, but
with a 3D modeling tool. Loading a ready-made Mesh object with all the
necessary attributes is a simple matter of calling the <tt>load</tt>
method in Loader.</p>

<p>The other example MIDlet is a retained mode application that plays
back a ready-made animation that it downloads over http.</p>
<P>

<P>
<DL>
<DT><b>Examples:</b><DD><div class="example_title">(1) Immediate mode example MIDlet: Class MyCanvas.

</div><pre class="example"> <span class="example_proclamation">import</span> javax.microedition.lcdui.*;
<span class="example_proclamation">import</span> javax.microedition.m3g.*;
 
<span class="example_modifier">public</span> <span class="example_proclamation">class</span> <span class="example_class">MyCanvas</span> <span class="example_proclamation">extends</span> <span class="example_class">Canvas</span> {
 
    <span class="example_modifier">private</span> <span class="example_class">Graphics</span>3D      iG3D;
    <span class="example_modifier">private</span> <span class="example_class">Camera</span>          iCamera;
    <span class="example_modifier">private</span> <span class="example_class">Light</span>           iLight;
    <span class="example_modifier">private</span> <span class="example_type">float</span>           iAngle = 0.0f;
    <span class="example_modifier">private</span> <span class="example_class">Transform</span>       iTransform = <span class="example_reserved">new</span> <span class="example_class">Transform</span>();
    <span class="example_modifier">private</span> <span class="example_class">Background</span>      iBackground = <span class="example_reserved">new</span> <span class="example_class">Background</span>();
    <span class="example_modifier">private</span> <span class="example_class">VertexBuffer</span>    iVb;    <span class="example_comment">// positions, normals, colors, texcoords</span>
    <span class="example_modifier">private</span> <span class="example_class">IndexBuffer</span>     iIb;    <span class="example_comment">// indices to iVB, forming triangle strips</span>
    <span class="example_modifier">private</span> <span class="example_class">Appearance</span>      iAppearance; <span class="example_comment">// material, texture, compositing, ...</span>
    <span class="example_modifier">private</span> <span class="example_class">Material</span>        iMaterial = <span class="example_reserved">new</span> <span class="example_class">Material</span>();