upstream-doc/man2/gluLookAt.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="gluLookAt">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluLookAt</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluLookAt</refname>
  17         <refpurpose>define a viewing transformation</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluLookAt</function></funcdef>
  23                 <paramdef>GLdouble <parameter>eyeX</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>eyeY</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>eyeZ</parameter></paramdef>
  26                 <paramdef>GLdouble <parameter>centerX</parameter></paramdef>
  27                 <paramdef>GLdouble <parameter>centerY</parameter></paramdef>
  28                 <paramdef>GLdouble <parameter>centerZ</parameter></paramdef>
  29                 <paramdef>GLdouble <parameter>upX</parameter></paramdef>
  30                 <paramdef>GLdouble <parameter>upY</parameter></paramdef>
  31                 <paramdef>GLdouble <parameter>upZ</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <refsect1 id="parameters"><title>Parameters</title>
  37         <variablelist>
  38         <varlistentry>
  39             <term><parameter>eyeX</parameter></term>
  40             <term><parameter>eyeY</parameter></term>
  41             <term><parameter>eyeZ</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies the position of the eye point.
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>centerX</parameter></term>
  50             <term><parameter>centerY</parameter></term>
  51             <term><parameter>centerZ</parameter></term>
  52             <listitem>
  53                 <para>
  54                     Specifies the position of the reference point.
  55                 </para>
  56             </listitem>
  57         </varlistentry>
  58         <varlistentry>
  59             <term><parameter>upX</parameter></term>
  60             <term><parameter>upY</parameter></term>
  61             <term><parameter>upZ</parameter></term>
  62             <listitem>
  63                 <para>
  64                     Specifies the direction of the <emphasis>up</emphasis> vector.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         </variablelist>
  69     </refsect1>
  70     <refsect1 id="description"><title>Description</title>
  71         <para>
  72             <function>gluLookAt</function> creates a viewing matrix derived from an eye point, a reference
  73             point indicating the center of the scene, and an <emphasis>UP</emphasis> vector.
  74         </para>
  75         <para>
  76             The matrix
  77             maps the reference point to the negative <emphasis>z</emphasis> axis and the
  78             eye point to the origin.
  79             When a typical projection matrix is used,
  80             the center of the scene therefore maps to the center of the viewport.
  81             Similarly, the direction described by the <emphasis>UP</emphasis>
  82             vector projected onto the viewing plane is mapped to the positive <emphasis>y</emphasis>
  83             axis so that it points upward in the viewport.
  84             The <emphasis>UP</emphasis> vector must not be parallel to the line of sight from the
  85             eye point to the reference point.
  86         </para>
  87         <para>
  88             Let
  89         </para>
  90         <para>
  91             <informalequation><mml:math>
  92                 <!-- eqn: F  =  left (   matrix {    ccol { centerX - eyeX above          centerY - eyeY above    centerZ - eyeZ } }    right ):-->
  93                 <mml:mrow>
  94                     <mml:mi mathvariant="italic">F</mml:mi>
  95                     <mml:mo>=</mml:mo>
  96                     <mml:mfenced open="(" close=")">
  97                         <mml:mtable>
  98                             <mml:mtr>
  99                                 <mml:mtd>
 100                                     <mml:mrow>
 101                                         <mml:mi mathvariant="italic">centerX</mml:mi>
 102                                         <mml:mo>-</mml:mo>
 103                                         <mml:mi mathvariant="italic">eyeX</mml:mi>
 104                                     </mml:mrow>
 105                                 </mml:mtd>
 106                             </mml:mtr>
 107                             <mml:mtr>
 108                                 <mml:mtd>
 109                                     <mml:mrow>
 110                                         <mml:mi mathvariant="italic">centerY</mml:mi>
 111                                         <mml:mo>-</mml:mo>
 112                                         <mml:mi mathvariant="italic">eyeY</mml:mi>
 113                                     </mml:mrow>
 114                                 </mml:mtd>
 115                             </mml:mtr>
 116                             <mml:mtr>
 117                                 <mml:mtd>
 118                                     <mml:mrow>
 119                                         <mml:mi mathvariant="italic">centerZ</mml:mi>
 120                                         <mml:mo>-</mml:mo>
 121                                         <mml:mi mathvariant="italic">eyeZ</mml:mi>
 122                                     </mml:mrow>
 123                                 </mml:mtd>
 124                             </mml:mtr>
 125                         </mml:mtable>
 126                     </mml:mfenced>
 127                 </mml:mrow>
 128             </mml:math></informalequation>
 129         </para>
 130         <para>
 131         </para>
 132         <para>
 133             Let <emphasis>UP</emphasis> be the vector
 134             <inlineequation><mml:math>
 135                 <!-- eqn: (upX, upY, upZ):-->
 136                 <mml:mfenced open="(" close=")">
 137                     <mml:mi mathvariant="italic">upX</mml:mi>
 138                     <mml:mi mathvariant="italic">upY</mml:mi>
 139                     <mml:mi mathvariant="italic">upZ</mml:mi>
 140                 </mml:mfenced>
 141             </mml:math></inlineequation>.
 142         </para>
 143         <para>
 144             Then normalize as follows:
 145             <informalequation><mml:math>
 146                 <!-- eqn: f  =  F over {|| F ||}:-->
 147                 <mml:mrow>
 148                     <mml:mi mathvariant="italic">f</mml:mi>
 149                     <mml:mo>=</mml:mo>
 150                     <mml:mfrac>
 151                         <mml:mi mathvariant="italic">F</mml:mi>
 152                         <mml:mfenced open="" close="">
 153                             <mml:mfenced open="&DoubleVerticalBar;" close="&DoubleVerticalBar;">
 154                                 <mml:mi mathvariant="italic">F</mml:mi>
 155                             </mml:mfenced>
 156                         </mml:mfenced>
 157                     </mml:mfrac>
 158                 </mml:mrow>
 159             </mml:math></informalequation>
 160         </para>
 161         <para>
 162             <informalequation><mml:math>
 163                 <!-- eqn: UP sup prime  =  UP over {|| UP ||}:-->
 164                 <mml:mrow>
 165                     <mml:msup><mml:mi mathvariant="italic">UP</mml:mi>
 166                     <mml:mo>&Prime;</mml:mo>
 167                     </mml:msup>
 168                     <mml:mo>=</mml:mo>
 169                     <mml:mfrac>
 170                         <mml:mi mathvariant="italic">UP</mml:mi>
 171                         <mml:mfenced open="" close="">
 172                             <mml:mfenced open="&DoubleVerticalBar;" close="&DoubleVerticalBar;">
 173                                 <mml:mi mathvariant="italic">UP</mml:mi>
 174                             </mml:mfenced>
 175                         </mml:mfenced>
 176                     </mml:mfrac>
 177                 </mml:mrow>
 178             </mml:math></informalequation>
 179         </para>
 180         <para>
 181         </para>
 182         <para>
 183             Finally, let
 184             <inlineequation><mml:math>
 185                 <!-- eqn: s  =  f  times  UP sup prime:-->
 186                 <mml:mrow>
 187                     <mml:mi mathvariant="italic">s</mml:mi>
 188                     <mml:mo>=</mml:mo>
 189                     <mml:mrow>
 190                         <mml:mi mathvariant="italic">f</mml:mi>
 191                         <mml:mo>&times;</mml:mo>
 192                         <mml:msup><mml:mi mathvariant="italic">UP</mml:mi>
 193                         <mml:mo>&Prime;</mml:mo>
 194                         </mml:msup>
 195                     </mml:mrow>
 196                 </mml:mrow>
 197             </mml:math></inlineequation>,
 198             and
 199             <inlineequation><mml:math>
 200                 <!-- eqn: u  =  s  times  f:-->
 201                 <mml:mrow>
 202                     <mml:mi mathvariant="italic">u</mml:mi>
 203                     <mml:mo>=</mml:mo>
 204                     <mml:mrow>
 205                         <mml:mi mathvariant="italic">s</mml:mi>
 206                         <mml:mo>&times;</mml:mo>
 207                         <mml:mi mathvariant="italic">f</mml:mi>
 208                     </mml:mrow>
 209                 </mml:mrow>
 210             </mml:math></inlineequation>.
 211         </para>
 212         <para>
 213         </para>
 214         <para>
 215             M is then constructed as follows:
 216             <informalequation><mml:math>
 217                 <!-- eqn: M  =  left (  matrix {    ccol {  s[0] above  u[0] above -f[0] above 0 }    ccol {  s[1] above  u[1] above -f[1] above 0 }    ccol {  s[2] above  u[2] above -f[2] above 0 }    ccol { 0 above 0 above 0  above 1 } }   right ):-->
 218                 <mml:mrow>
 219                     <mml:mi mathvariant="italic">M</mml:mi>
 220                     <mml:mo>=</mml:mo>
 221                     <mml:mfenced open="(" close=")">
 222                         <mml:mtable>
 223                             <mml:mtr>
 224                                 <mml:mtd>
 225                                     <mml:mrow>
 226                                         <mml:mi mathvariant="italic">s</mml:mi>
 227                                         <mml:mo>&af;</mml:mo>
 228                                         <mml:mfenced open="[" close="]">
 229                                             <mml:mn>0</mml:mn>
 230                                         </mml:mfenced>
 231                                     </mml:mrow>
 232                                 </mml:mtd>
 233                                 <mml:mtd>
 234                                     <mml:mrow>
 235                                         <mml:mi mathvariant="italic">s</mml:mi>
 236                                         <mml:mo>&af;</mml:mo>
 237                                         <mml:mfenced open="[" close="]">
 238                                             <mml:mn>1</mml:mn>
 239                                         </mml:mfenced>
 240                                     </mml:mrow>
 241                                 </mml:mtd>
 242                                 <mml:mtd>
 243                                     <mml:mrow>
 244                                         <mml:mi mathvariant="italic">s</mml:mi>
 245                                         <mml:mo>&af;</mml:mo>
 246                                         <mml:mfenced open="[" close="]">
 247                                             <mml:mn>2</mml:mn>
 248                                         </mml:mfenced>
 249                                     </mml:mrow>
 250                                 </mml:mtd>
 251                                 <mml:mtd>
 252                                     <mml:mn>0</mml:mn>
 253                                 </mml:mtd>
 254                             </mml:mtr>
 255                             <mml:mtr>
 256                                 <mml:mtd>
 257                                     <mml:mrow>
 258                                         <mml:mi mathvariant="italic">u</mml:mi>
 259                                         <mml:mo>&af;</mml:mo>
 260                                         <mml:mfenced open="[" close="]">
 261                                             <mml:mn>0</mml:mn>
 262                                         </mml:mfenced>
 263                                     </mml:mrow>
 264                                 </mml:mtd>
 265                                 <mml:mtd>
 266                                     <mml:mrow>
 267                                         <mml:mi mathvariant="italic">u</mml:mi>
 268                                         <mml:mo>&af;</mml:mo>
 269                                         <mml:mfenced open="[" close="]">
 270                                             <mml:mn>1</mml:mn>
 271                                         </mml:mfenced>
 272                                     </mml:mrow>
 273                                 </mml:mtd>
 274                                 <mml:mtd>
 275                                     <mml:mrow>
 276                                         <mml:mi mathvariant="italic">u</mml:mi>
 277                                         <mml:mo>&af;</mml:mo>
 278                                         <mml:mfenced open="[" close="]">
 279                                             <mml:mn>2</mml:mn>
 280                                         </mml:mfenced>
 281                                     </mml:mrow>
 282                                 </mml:mtd>
 283                                 <mml:mtd>
 284                                     <mml:mn>0</mml:mn>
 285                                 </mml:mtd>
 286                             </mml:mtr>
 287                             <mml:mtr>
 288                                 <mml:mtd>
 289                                     <mml:mrow>
 290                                         <mml:mo>-</mml:mo>
 291                                         <mml:mrow>
 292                                             <mml:mi mathvariant="italic">f</mml:mi>
 293                                             <mml:mo>&af;</mml:mo>
 294                                             <mml:mfenced open="[" close="]">
 295                                                 <mml:mn>0</mml:mn>
 296                                             </mml:mfenced>
 297                                         </mml:mrow>
 298                                     </mml:mrow>
 299                                 </mml:mtd>
 300                                 <mml:mtd>
 301                                     <mml:mrow>
 302                                         <mml:mo>-</mml:mo>
 303                                         <mml:mrow>
 304                                             <mml:mi mathvariant="italic">f</mml:mi>
 305                                             <mml:mo>&af;</mml:mo>
 306                                             <mml:mfenced open="[" close="]">
 307                                                 <mml:mn>1</mml:mn>
 308                                             </mml:mfenced>
 309                                         </mml:mrow>
 310                                     </mml:mrow>
 311                                 </mml:mtd>
 312                                 <mml:mtd>
 313                                     <mml:mrow>
 314                                         <mml:mo>-</mml:mo>
 315                                         <mml:mrow>
 316                                             <mml:mi mathvariant="italic">f</mml:mi>
 317                                             <mml:mo>&af;</mml:mo>
 318                                             <mml:mfenced open="[" close="]">
 319                                                 <mml:mn>2</mml:mn>
 320                                             </mml:mfenced>
 321                                         </mml:mrow>
 322                                     </mml:mrow>
 323                                 </mml:mtd>
 324                                 <mml:mtd>
 325                                     <mml:mn>0</mml:mn>
 326                                 </mml:mtd>
 327                             </mml:mtr>
 328                             <mml:mtr>
 329                                 <mml:mtd>
 330                                     <mml:mn>0</mml:mn>
 331                                 </mml:mtd>
 332                                 <mml:mtd>
 333                                     <mml:mn>0</mml:mn>
 334                                 </mml:mtd>
 335                                 <mml:mtd>
 336                                     <mml:mn>0</mml:mn>
 337                                 </mml:mtd>
 338                                 <mml:mtd>
 339                                     <mml:mn>1</mml:mn>
 340                                 </mml:mtd>
 341                             </mml:mtr>
 342                         </mml:mtable>
 343                     </mml:mfenced>
 344                 </mml:mrow>
 345             </mml:math></informalequation>
 346         </para>
 347         <para>
 348             and <function>gluLookAt</function> is equivalent to
 349             <programlisting>
 350 glMultMatrixf(M);
 351 glTranslated(-eyex, -eyey, -eyez);
 352             </programlisting>
 353         </para>
 354     </refsect1>
 355     <refsect1 id="seealso"><title>See Also</title>
 356         <para>
 357             <citerefentry><refentrytitle>gluPerspective</refentrytitle></citerefentry>,
 358             <citerefentry><refentrytitle>glFrustum</refentrytitle></citerefentry>
 359         </para>
 360     </refsect1>
 361     <refsect1 id="Copyright"><title>Copyright</title>
 362         <para>
 363             Copyright <trademark class="copyright"></trademark> 1991-2006
 364             Silicon Graphics, Inc. This document is licensed under the SGI
 365             Free Software B License. For details, see
 366             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 367         </para>
 368     </refsect1>
 369 </refentry>