graphics3d.html

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

 rendering target. The viewport is the area where the view of
 the current camera will appear. Any parts of the viewport that
 lie outside the boundaries of the target clipping rectangle are
 silently clipped off; however, this must simply discard the
 pixels without affecting projection. The viewport upper left
 corner (x, y) is given relative to the origin for a Graphics
 rendering target, or the upper left corner for an Image2D
 target. Refer to the class description for details.</p>

 <p>The viewport mapping transforms vertices from normalized device
 coordinates (x<sub>ndc</sub>, y<sub>ndc</sub>) to window coordinates
 (x<sub>w</sub>, y<sub>w</sub>) as follows:</p>

 <blockquote>
 x<sub>w</sub> = 0.5 x<sub>ndc</sub> w + o<sub>x</sub><br>
 y<sub>w</sub> = -0.5 y<sub>ndc</sub> h + o<sub>y</sub><br>
 </blockquote>

 <p>where w and h are the width and height of the viewport,
 specified in pixels, and (o<sub>x</sub>, o<sub>y</sub>) is the
 center of the viewport, also in pixels. The center of the
 viewport is obtained from the (x, y) coordinates of the top
 left corner as follows:</p>

 <blockquote>
 o<sub>x</sub> = x + 0.5 w<br>
 o<sub>y</sub> = y + 0.5 h<br>
 </blockquote>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>x</CODE> - X coordinate of the viewport upper left corner, in pixels<DD><CODE>y</CODE> - Y coordinate of the viewport upper left corner, in pixels<DD><CODE>width</CODE> - width of the viewport, in pixels<DD><CODE>height</CODE> - height of the viewport, in pixels
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>width</code> or
         <code>height</code> is negative or zero (note that
         <code>x</code> and <code>y</code> may have any value)
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the size of the viewport exceeds the
         implementation defined maximum size in either dimension; the
         maximum size can be queried with <code>getProperties</code></DL>
</DD>
</DL>
<HR>

<A NAME="setDepthRange(float, float)"><!-- --></A><H3>
setDepthRange</H3>
<PRE>
public void <B>setDepthRange</B>(float&nbsp;near,
                          float&nbsp;far)</PRE>
<DL>
<DD><p>Specifies the mapping of depth values from normalized device
 coordinates to window coordinates. Window coordinates are used
 for depth buffering.</p>
 
 <p>Depth values may range from -1 to 1 in normalized device
 coordinates (NDC), and from 0 to 1 in window coordinates. By
 default, the whole [0, 1] range of window coordinates is
 used. This method allows the normalized device coordinates [-1,
 1] to be mapped to a "tighter" interval of window coordinates,
 for example, (0.5, 1].</p>

 <p>Formally, the Z coordinate of a vertex in NDC, z<sub>ndc</sub>,
 is transformed to window coordinates (z<sub>w</sub>) as follows:</p>

 <blockquote>
 z<sub>w</sub> = 0.5 (far - near) (z<sub>ndc</sub> + 1) + near
 </blockquote>

 <p>where <code>near</code> and <code>far</code> are the distances,
 in window coordinates, to the near and far plane of the depth range,
 respectively. Both distances must be in [0, 1]. However, it is not
 necessary for the near plane to be closer than the far plane; inverse
 mappings are also acceptable.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>near</CODE> - distance to the near clipping plane, in window coordinates<DD><CODE>far</CODE> - distance to the far clipping plane, in window coordinates
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>(near &lt; 0) ||
         (near &gt; 1)</code>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>(far &lt; 0) ||
         (far &gt; 1)</code></DL>
</DD>
</DL>
<HR>

<A NAME="clear(javax.microedition.m3g.Background)"><!-- --></A><H3>
clear</H3>
<PRE>
public void <B>clear</B>(<A HREF="../../../javax/microedition/m3g/Background.html">Background</A>&nbsp;background)</PRE>
<DL>
<DD><p>Clears the viewport as specified in the given Background object. If
 the background object is null, the default settings are used. That is,
 the color buffer is cleared to transparent black, and the depth buffer
 to the maximum depth value (1.0).</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>background</CODE> - a Background object defining which buffers to clear
        and how, or null to use the default settings
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the background image in
         <code>background</code> is not in the same format as
         the currently bound rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have a
         rendering target</DL>
</DD>
</DL>
<HR>

<A NAME="render(javax.microedition.m3g.World)"><!-- --></A><H3>
render</H3>
<PRE>
public void <B>render</B>(<A HREF="../../../javax/microedition/m3g/World.html">World</A>&nbsp;world)</PRE>
<DL>
<DD><p>Renders an image of <code>world</code> as viewed by the
 active camera of that World. The node transformation of the
 World is ignored, but its other attributes are respected.</p>

 <p>Contrary to the immediate mode <code>render</code> variants,
 this method automatically clears the color buffer and the depth
 buffer according to the Background settings of the World.</p>

 <p>Prior to rendering, the current camera and lights set in this
 Graphics3D are automatically overwritten with the active camera
 and lights of the World. Upon method return, the lights array
 will contain precisely those Light nodes whose effective rendering
 enable flag is <i>true</i> (see <A HREF="../../../javax/microedition/m3g/Node.html#setRenderingEnable(boolean)"><CODE>Node.setRenderingEnable(boolean)</CODE></A>).
 The Lights are written to the array in undefined order, but such
 that there are no empty slots interleaved within non-empty slots
 and the first Light is at index 0.</p>

 <p>For any node that is rendered, if the transformation from that
 node's local coordinates to the camera space is not invertible,
 the results of lighting and fogging are undefined.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>world</CODE> - the World to render
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>world</code> is null
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have a
         rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if <code>world</code> has no active
         camera, or the active camera is not in that world
<DD><CODE>java.lang.IllegalStateException</CODE> - if the background image of
         <code>world</code> is not in the same format as the
         currently bound rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if any Mesh that is rendered violates
         the constraints defined in Mesh, MorphingMesh, SkinnedMesh,
         VertexBuffer, or IndexBuffer
<DD><CODE>java.lang.ArithmeticException</CODE> - if the transformation from the
         active camera of <code>world</code> to the world
         space is uninvertible</DL>
</DD>
</DL>
<HR>

<A NAME="render(javax.microedition.m3g.Node, javax.microedition.m3g.Transform)"><!-- --></A><H3>
render</H3>
<PRE>
public void <B>render</B>(<A HREF="../../../javax/microedition/m3g/Node.html">Node</A>&nbsp;node,
                   <A HREF="../../../javax/microedition/m3g/Transform.html">Transform</A>&nbsp;transform)</PRE>
<DL>
<DD><p>Renders the given Sprite3D, Mesh, or Group node with the given
 transformation from local coordinates to world coordinates. The
 node transformation of the given node is ignored, but its other
 attributes are respected.</p>
 
 <p>Any ancestors of the given node are ignored, as well as their
 transformations and other attributes. The node's descendants, if
 any, are rendered as usual. However, any Camera and Light nodes
 among the descendants are ignored and the camera and lights of
 this Graphics3D are used instead.</p>
 
 <p>The scope masks of the current Lights and Camera are respected,
 as well as the rendering enable flags of the Lights. The rendering
 enable flag of the Camera is ignored, as always.</p>

 <p>Note that Mesh nodes include MorphingMesh and SkinnedMesh nodes,
 and that Group nodes include World nodes. If a World is passed to
 this method, it is simply treated like any other Group and therefore
 any Background, Camera and Light objects it may have are ignored.</p>

 <p>This method does <i>not</i> clear the color and depth buffers;
 the application must explicitly clear them with the <A HREF="../../../javax/microedition/m3g/Graphics3D.html#clear(javax.microedition.m3g.Background)"><CODE>clear</CODE></A> method and/or draw any background graphics beforehand.</p>

 <p>For any node that is rendered, if the transformation from that
 node's local coordinates to the camera space is not invertible, the
 results of lighting and fogging are undefined.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>node</CODE> - the Sprite3D, Mesh, or Group to render<DD><CODE>transform</CODE> - the transformation from the local coordinate
        system of <code>node</code> to world space, or null to
        indicate the identity matrix
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>node</code> is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>node</code> is not a
         Sprite3D, Mesh, or Group
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a current camera
<DD><CODE>java.lang.IllegalStateException</CODE> - if any Mesh that is rendered violates
         the constraints defined in Mesh, MorphingMesh, SkinnedMesh,
         VertexBuffer, or IndexBuffer</DL>
</DD>
</DL>
<HR>

<A NAME="render(javax.microedition.m3g.VertexBuffer, javax.microedition.m3g.IndexBuffer, javax.microedition.m3g.Appearance, javax.microedition.m3g.Transform, int)"><!-- --></A><H3>
render</H3>
<PRE>
public void <B>render</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)</PRE>
<DL>
<DD><p>Renders the given submesh with the given scope and the given
 transformation from local coordinates to world coordinates.</p>

 <p>The scope masks of the current Lights and Camera are respected,
 as well as the rendering enable flags of the Lights. The rendering
 enable flag of the Camera is ignored, as always.</p>

 <p>If the transformation from local coordinates to the camera
 space is not invertible, the results of lighting and fogging
 are undefined.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>vertices</CODE> - a VertexBuffer defining the vertex attributes<DD><CODE>triangles</CODE> - an IndexBuffer defining the triangle strips<DD><CODE>appearance</CODE> - an Appearance defining the surface properties<DD><CODE>transform</CODE> - the transformation from the local coordinate system of
        <code>vertices</code> to world space, or null to indicate the
        identity matrix<DD><CODE>scope</CODE> - the scope of the submesh; this determines whether the
        submesh is rendered at all, and if it is, which lights are
        used; "-1" makes the scope as wide as possible
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>vertices</code> is null
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>triangles</code> is null
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>appearance</code> is null
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a current camera
<DD><CODE>java.lang.IllegalStateException</CODE> - if <code>vertices</code> or
         <code>triangles</code> violates the constraints defined
         in VertexBuffer or IndexBuffer</DL>
</DD>
</DL>
<HR>

<A NAME="render(javax.microedition.m3g.VertexBuffer, javax.microedition.m3g.IndexBuffer, javax.microedition.m3g.Appearance, javax.microedition.m3g.Transform)"><!-- --></A><H3>
render</H3>
<PRE>
public void <B>render</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)</PRE>
<DL>
<DD><p>Renders the given submesh with the given transformation from
 local coordinates to world coordinates. This method is exactly
 the same as the other submesh rendering method, except that the
 scope is implicitly set to -1 (the widest possible).</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>vertices</CODE> - a VertexBuffer defining the vertex attributes<DD><CODE>triangles</CODE> - an IndexBuffer defining the triangle strips<DD><CODE>appearance</CODE> - an Appearance defining the surface properties<DD><CODE>transform</CODE> - the transformation from the local coordinate system of
        <code>vertices</code> to world space, or null to indicate the
        identity matrix
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>vertices</code> is null
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>triangles</code> is null
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>appearance</code> is null
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a rendering target
<DD><CODE>java.lang.IllegalStateException</CODE> - if this Graphics3D does not have
         a current camera
<DD><CODE>java.lang.IllegalStateException</CODE> - if <code>vertices</code> or
         <code>triangles</code> violates the constraints defined
         in VertexBuffer or IndexBuffer</DL>
</DD>
</DL>