transform.html

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

xx(1-c)+c    xy(1-c)-zs   xz(1-c)+ys   0
yx(1-c)+zs   yy(1-c)+c    yz(1-c)-xs   0
xz(1-c)-ys   yz(1-c)+xs   zz(1-c)+c    0
     0            0            0       1</pre>
 </blockquote>

 <p>where c = cos(angle) and s = sin(angle). If the axis (x y z)
 is not unit-length, it will be normalized automatically before
 constructing the matrix.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>angle</CODE> - angle of rotation about the axis, in degrees<DD><CODE>ax</CODE> - X component of the rotation axis<DD><CODE>ay</CODE> - Y component of the rotation axis<DD><CODE>az</CODE> - Z component of the rotation axis
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the rotation axis <code>(ax ay
         az)</code> is zero and <code>angle</code> is nonzero</DL>
</DD>
</DL>
<HR>

<A NAME="postRotateQuat(float, float, float, float)"><!-- --></A><H3>
postRotateQuat</H3>
<PRE>
public void <B>postRotateQuat</B>(float&nbsp;qx,
                           float&nbsp;qy,
                           float&nbsp;qz,
                           float&nbsp;qw)</PRE>
<DL>
<DD><p>Multiplies this transformation from the right by the given
 rotation matrix, specified in quaternion form. The contents of
 this transformation are replaced with the result. Denoting this
 transformation by <b>M</b> and the rotation matrix by <b>R</b>,
 the new value for this transformation is computed as follows:</p>

 <blockquote>
 <b>M</b>' = <b>M</b> <b>R</b>
 </blockquote>

 <p>The rotation matrix <b>R</b> is constructed from the given
 quaternion (x y z w) as follows:</p>
 
 <blockquote><pre>
1-(2yy+2zz)   2xy-2zw      2xz+2yw      0
  2xy+2zw   1-(2xx+2zz)    2yz-2xw      0
  2xz-2yw     2yz+2xw    1-(2xx+2yy)    0
     0           0            0         1</pre>
 </blockquote>
 
 <p>The input quaternion is normalized to a 4-dimensional unit vector
 prior to constructing the rotation matrix. A quaternion with a vector
 part of all zeros is therefore normalized to (0 0 0 1), which
 represents a rotation by 2*pi, that is, no rotation at all. The
 only illegal input condition occurs when all components of the
 quaternion are zero.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>qx</CODE> - X component of the quaternion's vector part<DD><CODE>qy</CODE> - Y component of the quaternion's vector part<DD><CODE>qz</CODE> - Z component of the quaternion's vector part<DD><CODE>qw</CODE> - scalar component of the quaternion
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if all quaternion components are zero</DL>
</DD>
</DL>
<HR>

<A NAME="postTranslate(float, float, float)"><!-- --></A><H3>
postTranslate</H3>
<PRE>
public void <B>postTranslate</B>(float&nbsp;tx,
                          float&nbsp;ty,
                          float&nbsp;tz)</PRE>
<DL>
<DD><p>Multiplies this transformation from the right by the given
 translation matrix. The contents of this transformation are
 replaced with the result. Denoting this transformation by <b>M</b>
 and the translation matrix by <b>T</b>, the new value for this
 transformation is computed as follows:</p>

 <blockquote>
 <b>M</b>' = <b>M</b> <b>T</b>
 </blockquote>

 <p>The translation matrix <b>T</b> is constructed from the
 given translation vector (tx ty tz) as follows:</p>

 <blockquote><pre>
1   0   0   tx
0   1   0   ty
0   0   1   tz
0   0   0   1</pre>
 </blockquote>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>tx</CODE> - X component of the translation vector<DD><CODE>ty</CODE> - Y component of the translation vector<DD><CODE>tz</CODE> - Z component of the translation vector</DL>
</DD>
</DL>
<HR>

<A NAME="transform(javax.microedition.m3g.VertexArray, float[], boolean)"><!-- --></A><H3>
transform</H3>
<PRE>
public void <B>transform</B>(<A HREF="../../../javax/microedition/m3g/VertexArray.html">VertexArray</A>&nbsp;in,
                      float[]&nbsp;out,
                      boolean&nbsp;W)</PRE>
<DL>
<DD><p>Multiplies the elements of the given VertexArray with this
 matrix, storing the transformed values in a float array.</p>

 <p>The input VertexArray may have any number of elements (E), two
 or three components per element (C), and any component size (8 or
 16 bit). The float array is filled in with E elements, each having
 four components. The multiplication is always done with a full 4x4
 matrix and all four components of the result are returned.</p>

 <p>The implied value of the missing fourth component (W) of each
 input element depends on the boolean parameter. If the parameter
 is set to <i>true</i>, the W components of all vectors are set to
 1.0 prior to multiplication. If the parameter is <i>false</i>, the
 W components are set to 0.0. If the elements of the input array
 have only two components, the missing third component is always
 set to zero.</p>

 <p>This method does not take into account the scale and bias that
 may be associated with vertex positions and texture coordinates.
 (This is simply because the scale and bias values are defined in
 VertexBuffer, not VertexArray.) If the application wishes to use
 this method for transforming the vertex positions in a specific
 VertexBuffer, for example, the scale and bias can be applied to
 this Transform directly. See the code fragment below for how to
 do that.</p>

 <p>Note that this is a simple matrix-by-vector multiplication; no
 division by W or other operations are implied. The interpretation
 of the input and output values is up to each application.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>in</CODE> - a VertexArray of 2D or 3D vectors to multiply with this
        matrix<DD><CODE>out</CODE> - a 4D float array to populate with the transformed vectors<DD><CODE>W</CODE> - <i>true</i> to set the W component of each input vector
        implicitly to 1.0; <i>false</i> to set them to 0.0
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>in</code> is null
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>out</code> is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>in.numComponents == 4</code>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>out.length &lt; 4*E</code>,
         where E is the number of elements in the input VertexArray<DT><b>Example:</b><DD><div class="example_title">A method for transforming a vertex coordinate array.
 
 </div><pre class="example"> <span class="example_type">void</span> transformPoints(<span class="example_class">Transform</span> t, <span class="example_class">VertexBuffer</span> vb, <span class="example_type">float</span>[] out)
 {
     <span class="example_comment">// Make a copy of the given Transform so that we can restore</span>
     <span class="example_comment">// its original contents at the end.</span>
  
     <span class="example_class">Transform</span> tmp = <span class="example_reserved">new</span> <span class="example_class">Transform</span>(t);
     
     <span class="example_comment">// Retrieve the vertex coordinate array and its associated</span>
     <span class="example_comment">// scale and bias. In real applications, the float array</span>
     <span class="example_comment">// and the temporary Transform object should both be class</span>
     <span class="example_comment">// variables to avoid garbage collection.</span>
  
     <span class="example_type">float</span>[] scaleBias = <span class="example_reserved">new</span> <span class="example_type">float</span>[4];
     <span class="example_class">VertexArray</span> points = vb.getPositions(scaleBias);
     
     <span class="example_comment">// Note the order of constructing the transformation matrix.</span>
     <span class="example_comment">// The coordinates must be scaled first, then biased:</span>
     <span class="example_comment">//   v' = T S v</span>
  
     t.postTranslate(scaleBias[1], scaleBias[2], scaleBias[3]);
     t.postScale(scaleBias[0], scaleBias[0], scaleBias[0]);
     t.transform(points, out, <span class="example_literal">true</span>);
  
     <span class="example_comment">// Restore the original Transform.</span>
     
     t.set(tmp);
 }</pre></DD></DD></DL>
</DD>
</DL>
<HR>

<A NAME="transform(float[])"><!-- --></A><H3>
transform</H3>
<PRE>
public void <B>transform</B>(float[]&nbsp;vectors)</PRE>
<DL>
<DD><p>Multiplies the given array of 4D vectors with this matrix. The
 transformation is done in place, that is, the original vectors are
 overwritten with the transformed vectors.</p>

 <p>The vectors are given as a flat array of (x y z w) quadruplets.
 The length of the array divided by 4 gives the number of vectors
 to transform.</p>

 <p>Note that this is a simple matrix-by-vector multiplication; no
 division by W or other operations are implied. The interpretation
 of the input and output values is up to each application.</p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>vectors</CODE> - the vectors to transform, in (xyzw xyzw xyzw ...) order
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>points</code> is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if <code>points.length % 4 != 0</code></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/Transform.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/Texture2D.html"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../javax/microedition/m3g/Transformable.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="Transform.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;FIELD&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>