object3d.html

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

 object, and fills in the objects to the given array. </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/Object3D.html#getUserID()">getUserID</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gets the user ID of this object.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;java.lang.Object</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/m3g/Object3D.html#getUserObject()">getUserObject</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Retrieves the user object that is currently associated with
 this Object3D. </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/Object3D.html#removeAnimationTrack(javax.microedition.m3g.AnimationTrack)">removeAnimationTrack</A></B>(<A HREF="../../../javax/microedition/m3g/AnimationTrack.html">AnimationTrack</A>&nbsp;animationTrack)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Removes the given AnimationTrack from this Object3D, potentially
 changing the order and indices of the remaining tracks. </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/Object3D.html#setUserID(int)">setUserID</A></B>(int&nbsp;userID)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Sets the user ID for this object.</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/Object3D.html#setUserObject(java.lang.Object)">setUserObject</A></B>(java.lang.Object&nbsp;userObject)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Associates an arbitrary, application specific Object with
 this Object3D. </TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class java.lang.Object</B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE>equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>

<!-- ============ FIELD DETAIL =========== -->


<!-- ========= CONSTRUCTOR DETAIL ======== -->


<!-- ============ METHOD DETAIL ========== -->

<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="animate(int)"><!-- --></A><H3>
animate</H3>
<PRE>
public final int <B>animate</B>(int&nbsp;time)</PRE>
<DL>
<DD><p>Updates all animated properties in this Object3D and all Object3Ds
 that are reachable from this Object3D. Objects that are not reachable
 are not affected. See the class description for the definition of
 reachability.</p>

 <p>Animated properties are set to their interpolated values pertaining
 to the time given as a parameter. The pre-existing values of the target
 properties are <i>overwritten</i> with the animated values, discarding
 the pre-existing values. The original values are <i>not</i> restored
 even if the animation is terminated.</p>

 <p>The unit of time used in animation is defined by the application
 and does not have to correspond to real time in any way. Importantly,
 the animation system does not need to know what the time unit is.
 Milliseconds are often used by convention, but any other unit is
 equally valid.</p>
     
 <p>If a property is targeted by an AnimationTrack, but the
 AnimationTrack is not associated with an active
 AnimationController, the property is not updated.</p>

 <p>Typically, the application would call this method once per frame,
 with strictly increasing values of <code>time</code>. For example, if
 the application wishes to draw 20 frames per second, the value of
 <code>time</code> should be increased by 50 between successive calls,
 assuming a time unit of one millisecond.</p>

 <p>Even though strictly increasing values of <code>time</code> are
 often used, this is not a requirement. The application can pass in
 any time value. To put it another way, the animation system supports
 random access. This allows the application to, for example, rewind or
 restart the animations easily.</p>

 <p>In order to allow the application to throttle the frame rate
 depending on the characteristics of the animation, this method
 returns a <i>validity interval</i>. This is the amount of time
 for which the active animations on this object are guaranteed
 to make no changes to the reachable animated objects. For an
 object with no references to other animatable objects, this is
 determined solely from its own animation information. Otherwise,
 it is the minimum of this, and the returned validity interval of
 all reachable animated objects.</p>
 
 <p>For example, consider a single object with an active
 animation that starts to change an object's properties only at
 t=1000. If we call animate() at t=500, the validity interval
 returned should ideally be 500. The application can, in the
 absence of external events, then choose not to render another
 frame for 500 time units. This estimate of validity must be
 conservative, so it is acceptable (but not friendly) for an
 implementation to always return 0 from this method.</p>
 
 <p>If no animations are active on this object, the fact that a
 conservative estimate is required permits any interval to be
 returned, but it is strongly recommended that the value in this
 case should correspond to the maximum positive integer.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>time</CODE> - world time to update the animations to
<DT><B>Returns:</B><DD>validity interval; the number of time units until this method
         needs to be called again for this or any reachable Object3D
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalStateException</CODE> - if any active animation violates
         the constraints defined in KeyframeSequence<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/m3g/KeyframeSequence.html"><CODE>KeyframeSequence</CODE></A>, 
<A HREF="../../../javax/microedition/m3g/AnimationController.html"><CODE>AnimationController</CODE></A>, 
<A HREF="../../../javax/microedition/m3g/AnimationTrack.html"><CODE>AnimationTrack</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="duplicate()"><!-- --></A><H3>
duplicate</H3>
<PRE>
public final <A HREF="../../../javax/microedition/m3g/Object3D.html">Object3D</A> <B>duplicate</B>()</PRE>
<DL>
<DD><p>Creates a duplicate of this Object3D.</p>
 
 <p>Duplication has no effect on this object or any other
 existing object; it merely creates one or more new objects.</p>

 <p>As a general rule, a duplicate object will have exactly the
 same properties as the original object, including attribute
 values, references to other objects, and any other contained
 data. However, if this object is a Node, duplication is done
 as follows:</p>

 <ol>

 <p><li>This Node is always copied. The parent of the duplicate
 Node is set to null.</li></p>

 <p><li>Any descendants of this Node are themselves duplicated;
 this includes the skeleton group of a SkinnedMesh. Any other
 referenced objects are <i>not</i> duplicated.</li></p>

 <p><li>If any Node in the duplicate set of Nodes refers to any
 Node in the original set, then that reference is updated to the
 corresponding Node in the duplicate set. All other references
 are left as they are, even if this results in a scene graph
 branch that is in an illegal state.</li></p>

 </ol>

 <p>Note that the duplicate object will also have the same user
 ID as the original. The application is responsible for
 assigning the IDs in the first place, so setting the ID of the
 duplicate object to some unique value, if so desired, is also
 the application's responsibility.</p>

 <p>Duplication is not supported for user defined classes. That
 is, if the application extends any class defined in this API,
 any instances of that class will be treated by this method
 as instances of the base class. For example, duplicating an
 instance of MonsterMesh (derived from Mesh) will produce
 just a Mesh instance, not a MonsterMesh instance.</p>

 <p>This method is similar to the <tt>clone</tt> method that
 is available on the higher end Java platforms, such as J2SE
 and J2ME/CDC. This method is likely to be deprecated once
 the proper <tt>java.lang.Object.clone</tt> method becomes
 available also on CLDC.</p>
<P>
<DD><DL>

<DT><B>Returns:</B><DD>a new Object3D that is a duplicate of this object</DL>
</DD>
</DL>
<HR>

<A NAME="find(int)"><!-- --></A><H3>
find</H3>
<PRE>
public <A HREF="../../../javax/microedition/m3g/Object3D.html">Object3D</A> <B>find</B>(int&nbsp;userID)</PRE>
<DL>
<DD><p>Retrieves an object that has the given user ID and is reachable
 from this object. If there are multiple objects with the same ID,
 the implementation may return any one of them. See the class
 description for the definition of reachability.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>userID</CODE> - the user ID to search for
<DT><B>Returns:</B><DD>the first object encountered that has the given user ID,
         or null if no matching objects were found</DL>
</DD>
</DL>
<HR>

<A NAME="getReferences(javax.microedition.m3g.Object3D[])"><!-- --></A><H3>
getReferences</H3>
<PRE>
public int <B>getReferences</B>(<A HREF="../../../javax/microedition/m3g/Object3D.html">Object3D</A>[]&nbsp;references)</PRE>
<DL>
<DD><p>Returns the number of direct Object3D references in this
 object, and fills in the objects to the given array. If the
 array is null, only the number of references is returned.
 Duplicate references are explicitly not eliminated, that is,
 the same object may appear multiple times in the array.</p>

 <p>The parent reference of a Node does not count as a direct
 reference, and is hence not returned. The same applies for
 hidden references, such as alignment targets, that can not
 be queried by the application.</p>

 <p>This method is provided to facilitate scene graph traversal,
 which is otherwise a non-trivial operation; tracking the links
 from one object to another requires different code for each
 type of object. Typical usage of this method is to first call
 it with a null array, then use the number of references