upstream-man-pages/man2/gluUnProject4.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="gluUnProject4">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluUnProject4</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluUnProject4</refname>
  17         <refpurpose>map window and clip coordinates to object coordinates</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>GLint <function>gluUnProject4</function></funcdef>
  23                 <paramdef>GLdouble <parameter>winX</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>winY</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>winZ</parameter></paramdef>
  26                 <paramdef>GLdouble <parameter>clipW</parameter></paramdef>
  27                 <paramdef>const GLdouble * <parameter>model</parameter></paramdef>
  28                 <paramdef>const GLdouble * <parameter>proj</parameter></paramdef>
  29                 <paramdef>const GLint * <parameter>view</parameter></paramdef>
  30                 <paramdef>GLdouble <parameter>nearVal</parameter></paramdef>
  31                 <paramdef>GLdouble <parameter>farVal</parameter></paramdef>
  32                 <paramdef>GLdouble* <parameter>objX</parameter></paramdef>
  33                 <paramdef>GLdouble* <parameter>objY</parameter></paramdef>
  34                 <paramdef>GLdouble* <parameter>objZ</parameter></paramdef>
  35                 <paramdef>GLdouble* <parameter>objW</parameter></paramdef>
  36             </funcprototype>
  37         </funcsynopsis>
  38     </refsynopsisdiv>
  39     <!-- eqn: ignoring delim $$ -->
  40     <refsect1 id="parameters"><title>Parameters</title>
  41         <variablelist>
  42         <varlistentry>
  43             <term><parameter>winX</parameter></term>
  44             <term><parameter>winY</parameter></term>
  45             <term><parameter>winZ</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specify the window coordinates to be mapped.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         <varlistentry>
  53             <term><parameter>clipW</parameter></term>
  54             <listitem>
  55                 <para>
  56                     Specify the clip w coordinate to be mapped.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>model</parameter></term>
  62             <listitem>
  63                 <para>
  64                     Specifies the modelview matrix (as from a <citerefentry><refentrytitle>glGetDoublev</refentrytitle></citerefentry> call).
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         <varlistentry>
  69             <term><parameter>proj</parameter></term>
  70             <listitem>
  71                 <para>
  72                     Specifies the projection matrix (as from a <citerefentry><refentrytitle>glGetDoublev</refentrytitle></citerefentry> call).
  73                 </para>
  74             </listitem>
  75         </varlistentry>
  76         <varlistentry>
  77             <term><parameter>view</parameter></term>
  78             <listitem>
  79                 <para>
  80                     Specifies the viewport (as from a <citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> call).
  81                 </para>
  82             </listitem>
  83         </varlistentry>
  84         <varlistentry>
  85             <term><parameter>nearVal</parameter></term>
  86             <term><parameter>farVal</parameter></term>
  87             <listitem>
  88                 <para>
  89                     Specifies the near and far planes (as from a <citerefentry><refentrytitle>glGetDoublev</refentrytitle></citerefentry> call).
  90                 </para>
  91             </listitem>
  92         </varlistentry>
  93         <varlistentry>
  94             <term><parameter>objX</parameter></term>
  95             <term><parameter>objY</parameter></term>
  96             <term><parameter>objZ</parameter></term>
  97             <term><parameter>objW</parameter></term>
  98             <listitem>
  99                 <para>
 100                     Returns the computed object coordinates.
 101                 </para>
 102             </listitem>
 103         </varlistentry>
 104         </variablelist>
 105     </refsect1>
 106     <refsect1 id="description"><title>Description</title>
 107         <para>
 108             <function>gluUnProject4</function> maps the specified window coordinatesi: <parameter>winX</parameter>, <parameter>winY</parameter>, and <parameter>winZ</parameter>
 109             and its clip w coordinate <parameter>clipW</parameter>
 110             into object
 111             coordinates
 112             <inlineequation><mml:math>
 113                 <!-- eqn: (objX, objY, objZ, objW):-->
 114                 <mml:mfenced open="(" close=")">
 115                     <mml:mi mathvariant="italic">objX</mml:mi>
 116                     <mml:mi mathvariant="italic">objY</mml:mi>
 117                     <mml:mi mathvariant="italic">objZ</mml:mi>
 118                     <mml:mi mathvariant="italic">objW</mml:mi>
 119                 </mml:mfenced>
 120             </mml:math></inlineequation>
 121             using <parameter>model</parameter>, <parameter>proj</parameter>, and <parameter>view</parameter>. <parameter>clipW</parameter> can be other than
 122             1 as for vertices in <citerefentry><refentrytitle>glFeedbackBuffer</refentrytitle></citerefentry> when data type
 123             <constant>GLU_4D_COLOR_TEXTURE</constant> is returned.
 124             This also handles the case
 125             where the <parameter>nearVal</parameter> and <parameter>farVal</parameter> planes are different from the default,
 126             0 and 1, respectively.
 127             A return
 128             value of <constant>GLU_TRUE</constant> indicates success; a return value of <constant>GLU_FALSE</constant>
 129             indicates failure.
 130         </para>
 131         <para>
 132             To compute the coordinates
 133             <inlineequation><mml:math>
 134                 <!-- eqn: (objX, objY, objZ, objW):-->
 135                 <mml:mfenced open="(" close=")">
 136                     <mml:mi mathvariant="italic">objX</mml:mi>
 137                     <mml:mi mathvariant="italic">objY</mml:mi>
 138                     <mml:mi mathvariant="italic">objZ</mml:mi>
 139                     <mml:mi mathvariant="italic">objW</mml:mi>
 140                 </mml:mfenced>
 141             </mml:math></inlineequation>,
 142             <function>gluUnProject4</function> multiplies the normalized device coordinates by the inverse of
 143             <parameter>model</parameter> * <parameter>proj</parameter> as follows:
 144         </para>
 145         <para>
 146             <informalequation><mml:math>
 147                 <!-- eqn: left ( cpile {  objX above  objY above  objZ above  objW}    right )  =  INV(P M)  left ( cpile {  {2(winX  -  view[0])} over {view[2]}  -  1 above  {2(winY  -  view[1])} over {view[3]}  -  1 above  {2(winZ  -  nearVal)} over {(farVal  -  nearVal)}  -  1 above  clipW}    right ):-->
 148                 <mml:mrow>
 149                     <mml:mfenced open="(" close=")">
 150                         <mml:mtable>
 151                             <mml:mtr><mml:mtd>
 152                                 <mml:mi mathvariant="italic">objX</mml:mi>
 153                             </mml:mtd></mml:mtr>
 154                             <mml:mtr><mml:mtd>
 155                                 <mml:mi mathvariant="italic">objY</mml:mi>
 156                             </mml:mtd></mml:mtr>
 157                             <mml:mtr><mml:mtd>
 158                                 <mml:mi mathvariant="italic">objZ</mml:mi>
 159                             </mml:mtd></mml:mtr>
 160                             <mml:mtr><mml:mtd>
 161                                 <mml:mi mathvariant="italic">objW</mml:mi>
 162                             </mml:mtd></mml:mtr>
 163                         </mml:mtable>
 164                     </mml:mfenced>
 165                     <mml:mo>=</mml:mo>
 166                     <mml:mrow>
 167                         <mml:mrow>
 168                             <mml:mi mathvariant="italic">INV</mml:mi>
 169                             <mml:mo>&af;</mml:mo>
 170                             <mml:mfenced open="(" close=")">
 171                                 <mml:mrow>
 172                                     <mml:mi mathvariant="italic">P</mml:mi>
 173                                     <mml:mo>&it;</mml:mo>
 174                                     <mml:mi mathvariant="italic">M</mml:mi>
 175                                 </mml:mrow>
 176                             </mml:mfenced>
 177                         </mml:mrow>
 178                         <mml:mo>&it;</mml:mo>
 179                         <mml:mfenced open="(" close=")">
 180                             <mml:mtable>
 181                                 <mml:mtr><mml:mtd>
 182                                     <mml:mrow>
 183                                         <mml:mfrac>
 184                                             <mml:mfenced open="" close="">
 185                                                 <mml:mrow>
 186                                                     <mml:mn>2</mml:mn>
 187                                                     <mml:mo>&af;</mml:mo>
 188                                                     <mml:mfenced open="(" close=")">
 189                                                         <mml:mrow>
 190                                                             <mml:mi mathvariant="italic">winX</mml:mi>
 191                                                             <mml:mo>-</mml:mo>
 192                                                             <mml:mrow>
 193                                                                 <mml:mi mathvariant="italic">view</mml:mi>
 194                                                                 <mml:mo>&af;</mml:mo>
 195                                                                 <mml:mfenced open="[" close="]">
 196                                                                     <mml:mn>0</mml:mn>
 197                                                                 </mml:mfenced>
 198                                                             </mml:mrow>
 199                                                         </mml:mrow>
 200                                                     </mml:mfenced>
 201                                                 </mml:mrow>
 202                                             </mml:mfenced>
 203                                             <mml:mfenced open="" close="">
 204                                                 <mml:mrow>
 205                                                     <mml:mi mathvariant="italic">view</mml:mi>
 206                                                     <mml:mo>&af;</mml:mo>
 207                                                     <mml:mfenced open="[" close="]">
 208                                                         <mml:mn>2</mml:mn>
 209                                                     </mml:mfenced>
 210                                                 </mml:mrow>
 211                                             </mml:mfenced>
 212                                         </mml:mfrac>
 213                                         <mml:mo>-</mml:mo>
 214                                         <mml:mn>1</mml:mn>
 215                                     </mml:mrow>
 216                                 </mml:mtd></mml:mtr>
 217                                 <mml:mtr><mml:mtd>
 218                                     <mml:mrow>
 219                                         <mml:mfrac>
 220                                             <mml:mfenced open="" close="">
 221                                                 <mml:mrow>
 222                                                     <mml:mn>2</mml:mn>
 223                                                     <mml:mo>&af;</mml:mo>
 224                                                     <mml:mfenced open="(" close=")">
 225                                                         <mml:mrow>
 226                                                             <mml:mi mathvariant="italic">winY</mml:mi>
 227                                                             <mml:mo>-</mml:mo>
 228                                                             <mml:mrow>
 229                                                                 <mml:mi mathvariant="italic">view</mml:mi>
 230                                                                 <mml:mo>&af;</mml:mo>
 231                                                                 <mml:mfenced open="[" close="]">
 232                                                                     <mml:mn>1</mml:mn>
 233                                                                 </mml:mfenced>
 234                                                             </mml:mrow>
 235                                                         </mml:mrow>
 236                                                     </mml:mfenced>
 237                                                 </mml:mrow>
 238                                             </mml:mfenced>
 239                                             <mml:mfenced open="" close="">
 240                                                 <mml:mrow>
 241                                                     <mml:mi mathvariant="italic">view</mml:mi>
 242                                                     <mml:mo>&af;</mml:mo>
 243                                                     <mml:mfenced open="[" close="]">
 244                                                         <mml:mn>3</mml:mn>
 245                                                     </mml:mfenced>
 246                                                 </mml:mrow>
 247                                             </mml:mfenced>
 248                                         </mml:mfrac>
 249                                         <mml:mo>-</mml:mo>
 250                                         <mml:mn>1</mml:mn>
 251                                     </mml:mrow>
 252                                 </mml:mtd></mml:mtr>
 253                                 <mml:mtr><mml:mtd>
 254                                     <mml:mrow>
 255                                         <mml:mfrac>
 256                                             <mml:mfenced open="" close="">
 257                                                 <mml:mrow>
 258                                                     <mml:mn>2</mml:mn>
 259                                                     <mml:mo>&af;</mml:mo>
 260                                                     <mml:mfenced open="(" close=")">
 261                                                         <mml:mrow>
 262                                                             <mml:mi mathvariant="italic">winZ</mml:mi>
 263                                                             <mml:mo>-</mml:mo>
 264                                                             <mml:mi mathvariant="italic">nearVal</mml:mi>
 265                                                         </mml:mrow>
 266                                                     </mml:mfenced>
 267                                                 </mml:mrow>
 268                                             </mml:mfenced>
 269                                             <mml:mfenced open="" close="">
 270                                                 <mml:mfenced open="(" close=")">
 271                                                     <mml:mrow>
 272                                                         <mml:mi mathvariant="italic">farVal</mml:mi>
 273                                                         <mml:mo>-</mml:mo>
 274                                                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 275                                                     </mml:mrow>
 276                                                 </mml:mfenced>
 277                                             </mml:mfenced>
 278                                         </mml:mfrac>
 279                                         <mml:mo>-</mml:mo>
 280                                         <mml:mn>1</mml:mn>
 281                                     </mml:mrow>
 282                                 </mml:mtd></mml:mtr>
 283                                 <mml:mtr><mml:mtd>
 284                                     <mml:mi mathvariant="italic">clipW</mml:mi>
 285                                 </mml:mtd></mml:mtr>
 286                             </mml:mtable>
 287                         </mml:mfenced>
 288                     </mml:mrow>
 289                 </mml:mrow>
 290             </mml:math></informalequation>
 291         </para>
 292         <para>
 293             <inlineequation><mml:math><mml:mi mathvariant="italic">INV</mml:mi></mml:math></inlineequation>
 294             denotes matrix inversion.
 295         </para>
 296         <para>
 297             <function>gluUnProject4</function> is equivalent to <citerefentry><refentrytitle>gluUnProject</refentrytitle></citerefentry> when <parameter>clipW</parameter> is 1, <parameter>nearVal</parameter> is 0, and
 298             <parameter>farVal</parameter> is 1.
 299         </para>
 300     </refsect1>
 301     <refsect1 id="notes"><title>Notes</title>
 302         <para>
 303             <function>gluUnProject4</function> is available only if the GLU version is 1.3 or greater.
 304         </para>
 305     </refsect1>
 306     <refsect1 id="seealso"><title>See Also</title>
 307         <para>
 308             <citerefentry><refentrytitle>gluProject</refentrytitle></citerefentry>,
 309             <citerefentry><refentrytitle>gluUnProject</refentrytitle></citerefentry>,
 310             <citerefentry><refentrytitle>glFeedbackBuffer</refentrytitle></citerefentry>,
 311             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 312         </para>
 313     </refsect1>
 314     <refsect1 id="Copyright"><title>Copyright</title>
 315         <para>
 316             Copyright <trademark class="copyright"></trademark> 1991-2006
 317             Silicon Graphics, Inc. This document is licensed under the SGI
 318             Free Software B License. For details, see
 319             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 320         </para>
 321     </refsect1>
 322 </refentry>