group.html

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

 in order to compute the size of a sprite (see the Sprite3D class
 description), and that information is not available to this
 method. Developers are advised to use the other <code>pick</code>
 variant if picking of sprites is desired.</p>
 
 <p>The application should ensure that there are no uninvertible
 node transformations in this Group. Depending on how picking is
 implemented, singular transformations may or may not trigger an
 ArithmeticException.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>scope</CODE> - an integer scope specifying which Meshes to test
        for intersection with the pick ray; "-1" makes the scope
        as wide as possible<DD><CODE>ox</CODE> - X coordinate of the ray origin<DD><CODE>oy</CODE> - Y coordinate of the ray origin<DD><CODE>oz</CODE> - Z coordinate of the ray origin<DD><CODE>dx</CODE> - X component of the ray direction<DD><CODE>dy</CODE> - Y component of the ray direction<DD><CODE>dz</CODE> - Z component of the ray direction<DD><CODE>ri</CODE> - a RayIntersection object to fill in with information
        about the intersected Mesh, or null to just find out
        whether the ray intersected something or not
<DT><B>Returns:</B><DD><i>true</i> if the ray intersected a Mesh;
         <i>false</i> otherwise
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>dx = dy = dz = 0</code>
<DD><CODE>java.lang.IllegalStateException</CODE> - if any Mesh that is tested for
         intersection violates the constraints defined in Mesh,
         MorphingMesh, SkinnedMesh, VertexBuffer, or IndexBuffer
<DD><CODE>java.lang.ArithmeticException</CODE> - if the inverse of an uninvertible
         transformation is required by the implementation</DL>
</DD>
</DL>
<HR>

<A NAME="pick(int, float, float, javax.microedition.m3g.Camera, javax.microedition.m3g.RayIntersection)"><!-- --></A><H3>
pick</H3>
<PRE>
public boolean <B>pick</B>(int&nbsp;scope,
                    float&nbsp;x,
                    float&nbsp;y,
                    <A HREF="../../../javax/microedition/m3g/Camera.html">Camera</A>&nbsp;camera,
                    <A HREF="../../../javax/microedition/m3g/RayIntersection.html">RayIntersection</A>&nbsp;ri)</PRE>
<DL>
<DD><p>Picks the first Mesh or scaled Sprite3D in this Group that
 is enabled for picking, is intercepted by the given pick ray,
 and is in the specified <a href="Node.html#Scoping">scope</a>.</p>

 <p>This method behaves identically to the other <code>pick</code>
 variant, except that the pick ray is specified differently and
 that scaled sprites can also be picked. Unscaled sprites can not
 be picked. This is because the size of an unscaled sprite is only
 defined in screen space (that is, after viewport transformation),
 and the viewport parameters are not available to this method. See
 the Sprite3D class description for more information on sprite
 picking.</p>
 
 <p>The pick ray is cast from the given point <b>p</b> = (x, y)
 on the near clipping plane towards the corresponding point on
 the far clipping plane, and then beyond. See the Implementation
 guidelines below for details.</p>

 <p>Note that the origin of the pick ray is <i>not</i> the given
 Camera, but the point on the near clipping plane. Consequently
 the distance to the picked object, returned in RayIntersection,
 is not the distance from the camera, but the distance from the
 point <b>p</b>.</p>
 
 <p>The point <b>p</b> is specified relative to the viewport
 such that (0, 0) is the upper left corner and (1, 1) is the
 lower right corner. However, the (x, y) coordinates are not
 restricted to that range and may take on any values. In other
 words, objects that do not lie within the viewport can also be
 picked.</p>
 
 <p>The given Camera and this Group must be in the same scene
 graph, that is, they must have at least one common ancestor.
 Furthermore, the projection matrix of the Camera must be
 invertible. Depending on how picking is implemented, objects
 within the Group which have uninvertible modelview matrices
 may or may not trigger an ArithmeticException.</p>

 <h3>Implementation guidelines</h3>
 
 <p>The pick ray is cast towards infinity from the given point
 <b>p</b> on the near clipping plane, through a point <b>p</b>'
 on the far clipping plane. The exact procedure of deriving the
 pick ray origin and direction from the given point (x, y) and
 the given projection matrix <b>P</b> is as follows.</p>
 
 <p>In normalized device coordinates (NDC), the viewport spans
 the range [-1, 1] in each dimension (X, Y and Z). Points that
 lie on the near plane have a Z coordinate of -1 in NDC; points
 on the far plane have a Z of 1. The normalized device coordinates
 of <b>p</b> and <b>p</b>' are, therefore:</p>
 
 <blockquote>
 <b>p</b><sub>ndc</sub> = (2x-1, 1-2y, -1, 1)<sup>T</sup><br>
 <b>p</b>'<sub>ndc</sub> = (2x-1, 1-2y, 1, 1)<sup>T</sup>
 </blockquote>

 <p>Note that the Y coordinate is inverted when going from NDC
 to viewport or vice versa, as the viewport upper left corner
 maps to (-1, 1) in NDC (see also the viewport transformation
 equation in <code>Graphics3D.setViewport</code>). Applying the
 inverse projection matrix on the pick points, we obtain their
 positions in camera space:</p>

 <blockquote>
 <b>p</b><sub>c</sub> = <b>P</b><sup>-1</sup> <b>p</b><sub>ndc</sub><br>
 <b>p</b>'<sub>c</sub> = <b>P</b><sup>-1</sup> <b>p</b>'<sub>ndc</sub>
 </blockquote>

 <p>We then scale the resultant homogeneous points such that their
 W components are equal to 1; that might not otherwise be the case
 after the inverse projection. Formally, denoting the W components
 of the near and far points by w and w', the final camera space
 coordinates are obtained as follows:</p>
 
 <blockquote>
 <b>p</b> = <b>p</b><sub>c</sub> / w<br>
 <b>p'</b> = <b>p</b>'<sub>c</sub> / w'
 </blockquote>

 <p>The origin of the pick ray in camera coordinates is then
 <b>p</b> while its direction vector is <b>p</b>' - <b>p</b>.</p>
 
 <p>Finally, the pick ray is transformed from camera space to the
 coordinate system of this Group. That ray is used in the actual
 intersection tests, and is also the one that is returned by the
 <code>getRay</code> method in RayIntersection.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>scope</CODE> - an integer scope specifying which meshes and sprites
        to test for intersection with the pick ray; -1 makes the
        scope as wide as possible<DD><CODE>x</CODE> - X coordinate of the point on the viewport plane through
        which to cast the ray<DD><CODE>y</CODE> - Y coordinate of the point on the viewport plane through
        which to cast the ray<DD><CODE>camera</CODE> - a camera based on which the origin and direction of
        the pick ray are to be computed<DD><CODE>ri</CODE> - a RayIntersection object to fill in with information
        about the intersected Mesh, or null to just find out
        whether the ray intersected something or not
<DT><B>Returns:</B><DD><i>true</i> if the ray intersected a Mesh or Sprite3D;
         <i>false</i> otherwise
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>camera</code> is null
<DD><CODE>java.lang.IllegalStateException</CODE> - if any Mesh that is tested for
         intersection violates the constraints defined in Mesh,
         MorphingMesh, SkinnedMesh, VertexBuffer, or IndexBuffer
<DD><CODE>java.lang.IllegalStateException</CODE> - if there is no scene graph path
         between <code>camera</code> and this Group
<DD><CODE>java.lang.ArithmeticException</CODE> - if the inverse of an uninvertible
         transformation is required by the implementation</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/Group.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<EM><B>Nov 19, 2003</B></EM></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/microedition/m3g/Graphics3D.html"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../javax/microedition/m3g/Image2D.html"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="Group.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;
<SCRIPT>
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;<A HREF="#fields_inherited_from_class_javax.microedition.m3g.Node">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<EM>Copyright &copy 2003 Nokia Corporation. See the <a href="../../../overview-summary.html#Copyright">Copyright Notice</a> for details.</EM>
</BODY>
</HTML>