graphics3d.html

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

<h3>Implementation guidelines</h3>

<p>See the <a href="package-summary.html#Conventions">package
description</a> for general implementation requirements, definitions
of coordinate systems, and other background information.</p>

<h4>Depth buffer</h4>

<p>The format and bit depth of the depth buffer are specific to each
implementation and are not known to the application. However, the depth
buffer resolution must be at least 8 bits. The contents of the depth
buffer are never exposed through the API, so implementations may choose
not to use a conventional depth buffer at all. However, a conforming
implementation is required to behave <i>as if</i> it were using an
ordinary depth buffer.</p>

<h4>Color buffer</h4>

<p>The resolution of each color channel (R, G, B and A) in the color
buffer must be at least 1 bit. Not all color channels are necessarily
present; for example, the alpha channel is missing from Canvas and
Image targets in MIDP. On a device with a black and white display,
there may be only one channel, representing the luminance. In such
a situation, the conversion of RGB colors into luminance can be done
at any point in the pipeline, provided that the conversion is done
according to the general rules set forth in the package description.</p>

<p>The <code>clear</code> and <code>render(World)</code> methods impose
the restriction that the background image must be in the same format as
the bound rendering target. It is worth highlighting that when bound
to a MIDP Graphics object, the effective format can only be RGB (never
RGBA) due to restrictions in the MIDP specification. It is also true
that the MIDP Graphics object appears to be an RGB target even when the
physical display is in fact monochrome. This reduces the complexity of
application development considerably, since an RGB format image is
valid for any binding to a MIDP target. Other target platforms may
or may not be similarly specified.</p>

<h4>Back buffer</h4>

<p>It is intentionally unspecified whether a separate back buffer should
be allocated for colors or not. Instead, we leave the implementation to
decide which mode of operation is the most efficient, or which produces
the best quality, according to the screen dimensions and speed versus
quality preferences given by the application.</p>

<p>The decision whether to allocate any back buffer memory should be made
at the latest when a new rendering target is first bound to the Graphics3D
object. A previously bound rendering target is considered to be "new" when
the rendering quality hints or the dimensions of the clipping rectangle
have changed. In the case of a Graphics target, the actual rendering target
is considered to be the Canvas, Image or other surface that the Graphics
is attached to. The motivation for this rule is to guarantee that repeated
rebinding of a rendering target - or several different rendering targets -
will not incur the performance penalty of reallocating back buffer memory.</p>

<p>As an example of when a back buffer may be desired, consider a case
where the application specifies <code>setDitheringEnable(true)</code> and
subsequently binds a Canvas target. If the MIDP native color format is of
low precision (such as RGB444), the implementation may wish to render at a
higher color precision to a back buffer, then dither down to the MIDP native
color format.</p>
<P>

<P>
<DL>
<DT><b>Example:</b><DD><div class="example_title">A code fragment illustrating the usage of Graphics3D.

</div><pre class="example"> <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_class">World</span> myWorld;
    <span class="example_type">int</span> currentTime = 0;
    
    <span class="example_modifier">public</span> <span class="example_class">MyCanvas</span>() <span class="example_proclamation">throws</span> <span class="example_class">IOException</span> {
   
        <span class="example_comment">// Load an entire World. Proper exception handling is omitted</span>
        <span class="example_comment">// for clarity; see the class description of Loader for a more</span>
        <span class="example_comment">// elaborate example.</span>
    
        <span class="example_class">Object</span>3D[] objects = <span class="example_class">Loader</span>.load(<span class="example_string">"http://www.example.com/myscene.m3g"</span>);
        myWorld = (<span class="example_class">World</span>) objects[0];
    }
    
    <span class="example_comment">// The paint method is called by MIDP after the application has issued</span>
    <span class="example_comment">// a repaint request. We draw a new frame on this Canvas by binding the</span>
    <span class="example_comment">// current Graphics object as the target, then rendering, and finally</span>
    <span class="example_comment">// releasing the target.</span>
    
    <span class="example_modifier">protected</span> <span class="example_type">void</span> paint(<span class="example_class">Graphics</span> g) {
 
        <span class="example_comment">// Get the singleton Graphics3D instance that is associated</span>
        <span class="example_comment">// with this midlet.</span>
        
        <span class="example_class">Graphics</span>3D g3d = <span class="example_class">Graphics</span>3D.getInstance();
        
        <span class="example_comment">// Bind the 3D graphics context to the given MIDP Graphics</span>
        <span class="example_comment">// object. The viewport will cover the whole of this Canvas.</span>
 
        g3d.bindTarget(g);
 
        <span class="example_comment">// Apply animations, render the scene and release the Graphics.</span>
      
        myWorld.animate(currentTime);
        g3d.render(myWorld);    <span class="example_comment">// render a view from the active camera</span>
        g3d.releaseTarget();    <span class="example_comment">// flush the rendered image</span>
        currentTime += 50;      <span class="example_comment">// assume we can handle 20 frames per second</span>
    }
}</pre></DD></DD></DL>
<HR>

<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->


<!-- =========== FIELD SUMMARY =========== -->

<A NAME="field_summary"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Field Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#ANTIALIAS">ANTIALIAS</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;A parameter to <code>bindTarget</code>, specifying that
 antialiasing should be turned on. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#DITHER">DITHER</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;A parameter to <code>bindTarget</code>, specifying that
 dithering should be turned on. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#TRUE_COLOR">TRUE_COLOR</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;A parameter to <code>bindTarget</code>, specifying that true
 color rendering should be turned on. </TD>
</TR>
</TABLE>
&nbsp;
<!-- ======== CONSTRUCTOR SUMMARY ======== -->


<!-- ========== METHOD SUMMARY =========== -->

<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Method Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#addLight(javax.microedition.m3g.Light, javax.microedition.m3g.Transform)">addLight</A></B>(<A HREF="../../../javax/microedition/m3g/Light.html">Light</A>&nbsp;light,
         <A HREF="../../../javax/microedition/m3g/Transform.html">Transform</A>&nbsp;transform)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Binds a Light to use in subsequent immediate mode rendering.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#bindTarget(java.lang.Object)">bindTarget</A></B>(java.lang.Object&nbsp;target)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Binds the given Graphics or mutable Image2D as the rendering target
 of this Graphics3D. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#bindTarget(java.lang.Object, boolean, int)">bindTarget</A></B>(java.lang.Object&nbsp;target,
           boolean&nbsp;depthBuffer,
           int&nbsp;hints)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Binds the given Graphics or mutable Image2D as the rendering target
 of this Graphics3D. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#clear(javax.microedition.m3g.Background)">clear</A></B>(<A HREF="../../../javax/microedition/m3g/Background.html">Background</A>&nbsp;background)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clears the viewport as specified in the given Background object. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/m3g/Graphics3D.html">Graphics3D</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#getInstance()">getInstance</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the singleton Graphics3D instance that is associated with
 this application. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;java.util.Hashtable</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#getProperties()">getProperties</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Retrieves implementation specific properties. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#releaseTarget()">releaseTarget</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Flushes the rendered 3D image to the currently bound target and
 then releases the target. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#render(javax.microedition.m3g.Node, javax.microedition.m3g.Transform)">render</A></B>(<A HREF="../../../javax/microedition/m3g/Node.html">Node</A>&nbsp;node,
       <A HREF="../../../javax/microedition/m3g/Transform.html">Transform</A>&nbsp;transform)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Renders the given Sprite3D, Mesh, or Group node with the given
 transformation from local coordinates to world coordinates. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#render(javax.microedition.m3g.VertexBuffer, javax.microedition.m3g.IndexBuffer, javax.microedition.m3g.Appearance, javax.microedition.m3g.Transform)">render</A></B>(<A HREF="../../../javax/microedition/m3g/VertexBuffer.html">VertexBuffer</A>&nbsp;vertices,
       <A HREF="../../../javax/microedition/m3g/IndexBuffer.html">IndexBuffer</A>&nbsp;triangles,
       <A HREF="../../../javax/microedition/m3g/Appearance.html">Appearance</A>&nbsp;appearance,
       <A HREF="../../../javax/microedition/m3g/Transform.html">Transform</A>&nbsp;transform)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Renders the given submesh with the given transformation from
 local coordinates to world coordinates. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#render(javax.microedition.m3g.VertexBuffer, javax.microedition.m3g.IndexBuffer, javax.microedition.m3g.Appearance, javax.microedition.m3g.Transform, int)">render</A></B>(<A HREF="../../../javax/microedition/m3g/VertexBuffer.html">VertexBuffer</A>&nbsp;vertices,
       <A HREF="../../../javax/microedition/m3g/IndexBuffer.html">IndexBuffer</A>&nbsp;triangles,
       <A HREF="../../../javax/microedition/m3g/Appearance.html">Appearance</A>&nbsp;appearance,
       <A HREF="../../../javax/microedition/m3g/Transform.html">Transform</A>&nbsp;transform,
       int&nbsp;scope)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Renders the given submesh with the given scope and the given
 transformation from local coordinates to world coordinates.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#render(javax.microedition.m3g.World)">render</A></B>(<A HREF="../../../javax/microedition/m3g/World.html">World</A>&nbsp;world)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Renders an image of <code>world</code> as viewed by the
 active camera of that World. </TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Graphics3D.html#resetLights()">resetLights</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clears the array of current Lights.</TD>