upstream-man-pages/man2/glFrustum.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="glFrustum">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glFrustum</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glFrustum</refname>
  17         <refpurpose>multiply the current matrix by a perspective matrix</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glFrustum</function></funcdef>
  23                 <paramdef>GLdouble <parameter>left</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>right</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>bottom</parameter></paramdef>
  26                 <paramdef>GLdouble <parameter>top</parameter></paramdef>
  27                 <paramdef>GLdouble <parameter>nearVal</parameter></paramdef>
  28                 <paramdef>GLdouble <parameter>farVal</parameter></paramdef>
  29             </funcprototype>
  30         </funcsynopsis>
  31     </refsynopsisdiv>
  32     <!-- eqn: ignoring delim $$ -->
  33     <refsect1 id="parameters"><title>Parameters</title>
  34         <variablelist>
  35         <varlistentry>
  36             <term><parameter>left</parameter></term>
  37             <term><parameter>right</parameter></term>
  38             <listitem>
  39                 <para>
  40                     Specify the coordinates for the left and right vertical clipping planes.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>bottom</parameter></term>
  46             <term><parameter>top</parameter></term>
  47             <listitem>
  48                 <para>
  49                     Specify the coordinates for the bottom and top horizontal clipping planes.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>nearVal</parameter></term>
  55             <term><parameter>farVal</parameter></term>
  56             <listitem>
  57                 <para>
  58                     Specify the distances to the near and far depth clipping planes.
  59                     Both distances must be positive.
  60                 </para>
  61             </listitem>
  62         </varlistentry>
  63         </variablelist>
  64     </refsect1>
  65     <refsect1 id="description"><title>Description</title>
  66         <para>
  67             <function>glFrustum</function> describes a perspective matrix that produces a perspective projection.
  68             The current matrix (see <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>) is multiplied by this matrix
  69             and the result replaces the current matrix, as if
  70             <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called with the following matrix
  71             as its argument:
  72         </para>
  73         <para>
  74         </para>
  75         <para>
  76             <informalequation><mml:math>
  77                 <!-- eqn:  left [      matrix {    ccol { {{2   nearVal} over {right  -  left}} above 0 above 0 above 0 }    ccol { 0 above {{2   nearVal} over {top  -  bottom}}   above 0 above 0 }    ccol { A      above B      above C      above -1     }    ccol { 0 above 0 above D above 0} }     right ]:-->
  78                 <mml:mfenced open="[" close="]">
  79                     <mml:mtable>
  80                         <mml:mtr>
  81                             <mml:mtd>
  82                                 <mml:mfenced open="" close="">
  83                                     <mml:mfrac>
  84                                         <mml:mfenced open="" close="">
  85                                             <mml:mrow>
  86                                                 <mml:mn>2</mml:mn>
  87                                                 <mml:mo>&it;</mml:mo>
  88                                                 <mml:mi mathvariant="italic">nearVal</mml:mi>
  89                                             </mml:mrow>
  90                                         </mml:mfenced>
  91                                         <mml:mfenced open="" close="">
  92                                             <mml:mrow>
  93                                                 <mml:mi mathvariant="italic">right</mml:mi>
  94                                                 <mml:mo>-</mml:mo>
  95                                                 <mml:mi mathvariant="italic">left</mml:mi>
  96                                             </mml:mrow>
  97                                         </mml:mfenced>
  98                                     </mml:mfrac>
  99                                 </mml:mfenced>
 100                             </mml:mtd>
 101                             <mml:mtd>
 102                                 <mml:mn>0</mml:mn>
 103                             </mml:mtd>
 104                             <mml:mtd>
 105                                 <mml:mi mathvariant="italic">A</mml:mi>
 106                             </mml:mtd>
 107                             <mml:mtd>
 108                                 <mml:mn>0</mml:mn>
 109                             </mml:mtd>
 110                         </mml:mtr>
 111                         <mml:mtr>
 112                             <mml:mtd>
 113                                 <mml:mn>0</mml:mn>
 114                             </mml:mtd>
 115                             <mml:mtd>
 116                                 <mml:mfenced open="" close="">
 117                                     <mml:mfrac>
 118                                         <mml:mfenced open="" close="">
 119                                             <mml:mrow>
 120                                                 <mml:mn>2</mml:mn>
 121                                                 <mml:mo>&it;</mml:mo>
 122                                                 <mml:mi mathvariant="italic">nearVal</mml:mi>
 123                                             </mml:mrow>
 124                                         </mml:mfenced>
 125                                         <mml:mfenced open="" close="">
 126                                             <mml:mrow>
 127                                                 <mml:mi mathvariant="italic">top</mml:mi>
 128                                                 <mml:mo>-</mml:mo>
 129                                                 <mml:mi mathvariant="italic">bottom</mml:mi>
 130                                             </mml:mrow>
 131                                         </mml:mfenced>
 132                                     </mml:mfrac>
 133                                 </mml:mfenced>
 134                             </mml:mtd>
 135                             <mml:mtd>
 136                                 <mml:mi mathvariant="italic">B</mml:mi>
 137                             </mml:mtd>
 138                             <mml:mtd>
 139                                 <mml:mn>0</mml:mn>
 140                             </mml:mtd>
 141                         </mml:mtr>
 142                         <mml:mtr>
 143                             <mml:mtd>
 144                                 <mml:mn>0</mml:mn>
 145                             </mml:mtd>
 146                             <mml:mtd>
 147                                 <mml:mn>0</mml:mn>
 148                             </mml:mtd>
 149                             <mml:mtd>
 150                                 <mml:mi mathvariant="italic">C</mml:mi>
 151                             </mml:mtd>
 152                             <mml:mtd>
 153                                 <mml:mi mathvariant="italic">D</mml:mi>
 154                             </mml:mtd>
 155                         </mml:mtr>
 156                         <mml:mtr>
 157                             <mml:mtd>
 158                                 <mml:mn>0</mml:mn>
 159                             </mml:mtd>
 160                             <mml:mtd>
 161                                 <mml:mn>0</mml:mn>
 162                             </mml:mtd>
 163                             <mml:mtd>
 164                                 <mml:mn>-1</mml:mn>
 165                             </mml:mtd>
 166                             <mml:mtd>
 167                                 <mml:mn>0</mml:mn>
 168                             </mml:mtd>
 169                         </mml:mtr>
 170                     </mml:mtable>
 171                 </mml:mfenced>
 172             </mml:math></informalequation>
 173         </para>
 174         <para>
 175             <informalequation><mml:math>
 176                 <!-- eqn:  A  =  {right  +  left} over {right  -  left}:-->
 177                 <mml:mrow>
 178                     <mml:mi mathvariant="italic">A</mml:mi>
 179                     <mml:mo>=</mml:mo>
 180                     <mml:mfrac>
 181                         <mml:mfenced open="" close="">
 182                             <mml:mrow>
 183                                 <mml:mi mathvariant="italic">right</mml:mi>
 184                                 <mml:mo>+</mml:mo>
 185                                 <mml:mi mathvariant="italic">left</mml:mi>
 186                             </mml:mrow>
 187                         </mml:mfenced>
 188                         <mml:mfenced open="" close="">
 189                             <mml:mrow>
 190                                 <mml:mi mathvariant="italic">right</mml:mi>
 191                                 <mml:mo>-</mml:mo>
 192                                 <mml:mi mathvariant="italic">left</mml:mi>
 193                             </mml:mrow>
 194                         </mml:mfenced>
 195                     </mml:mfrac>
 196                 </mml:mrow>
 197             </mml:math></informalequation>
 198         </para>
 199         <para>
 200             <informalequation><mml:math>
 201                 <!-- eqn:  B  =  {top  +  bottom} over {top  -  bottom}:-->
 202                 <mml:mrow>
 203                     <mml:mi mathvariant="italic">B</mml:mi>
 204                     <mml:mo>=</mml:mo>
 205                     <mml:mfrac>
 206                         <mml:mfenced open="" close="">
 207                             <mml:mrow>
 208                                 <mml:mi mathvariant="italic">top</mml:mi>
 209                                 <mml:mo>+</mml:mo>
 210                                 <mml:mi mathvariant="italic">bottom</mml:mi>
 211                             </mml:mrow>
 212                         </mml:mfenced>
 213                         <mml:mfenced open="" close="">
 214                             <mml:mrow>
 215                                 <mml:mi mathvariant="italic">top</mml:mi>
 216                                 <mml:mo>-</mml:mo>
 217                                 <mml:mi mathvariant="italic">bottom</mml:mi>
 218                             </mml:mrow>
 219                         </mml:mfenced>
 220                     </mml:mfrac>
 221                 </mml:mrow>
 222             </mml:math></informalequation>
 223         </para>
 224         <para>
 225             <informalequation><mml:math>
 226                 <!-- eqn:  C  =  -{{farVal  +  nearVal} over {farVal  -  nearVal}}:-->
 227                 <mml:mrow>
 228                     <mml:mi mathvariant="italic">C</mml:mi>
 229                     <mml:mo>=</mml:mo>
 230                     <mml:mrow>
 231                         <mml:mo>-</mml:mo>
 232                         <mml:mfenced open="" close="">
 233                             <mml:mfrac>
 234                                 <mml:mfenced open="" close="">
 235                                     <mml:mrow>
 236                                         <mml:mi mathvariant="italic">farVal</mml:mi>
 237                                         <mml:mo>+</mml:mo>
 238                                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 239                                     </mml:mrow>
 240                                 </mml:mfenced>
 241                                 <mml:mfenced open="" close="">
 242                                     <mml:mrow>
 243                                         <mml:mi mathvariant="italic">farVal</mml:mi>
 244                                         <mml:mo>-</mml:mo>
 245                                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 246                                     </mml:mrow>
 247                                 </mml:mfenced>
 248                             </mml:mfrac>
 249                         </mml:mfenced>
 250                     </mml:mrow>
 251                 </mml:mrow>
 252             </mml:math></informalequation>
 253         </para>
 254         <para>
 255             <informalequation><mml:math>
 256                 <!-- eqn:  D  =  -{{2   farVal   nearVal} over {farVal  -  nearVal}}:-->
 257                 <mml:mrow>
 258                     <mml:mi mathvariant="italic">D</mml:mi>
 259                     <mml:mo>=</mml:mo>
 260                     <mml:mrow>
 261                         <mml:mo>-</mml:mo>
 262                         <mml:mfenced open="" close="">
 263                             <mml:mfrac>
 264                                 <mml:mfenced open="" close="">
 265                                     <mml:mrow>
 266                                         <mml:mn>2</mml:mn>
 267                                         <mml:mo>&it;</mml:mo>
 268                                         <mml:mi mathvariant="italic">farVal</mml:mi>
 269                                         <mml:mo>&it;</mml:mo>
 270                                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 271                                     </mml:mrow>
 272                                 </mml:mfenced>
 273                                 <mml:mfenced open="" close="">
 274                                     <mml:mrow>
 275                                         <mml:mi mathvariant="italic">farVal</mml:mi>
 276                                         <mml:mo>-</mml:mo>
 277                                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 278                                     </mml:mrow>
 279                                 </mml:mfenced>
 280                             </mml:mfrac>
 281                         </mml:mfenced>
 282                     </mml:mrow>
 283                 </mml:mrow>
 284             </mml:math></informalequation>
 285         </para>
 286         <para>
 287         </para>
 288         <para>
 289             Typically, the matrix mode is <constant>GL_PROJECTION</constant>, and
 290             <inlineequation><mml:math>
 291                 <!-- eqn: (left, bottom,  -nearVal):-->
 292                 <mml:mfenced open="(" close=")">
 293                     <mml:mi mathvariant="italic">left</mml:mi>
 294                     <mml:mi mathvariant="italic">bottom</mml:mi>
 295                     <mml:mrow>
 296                         <mml:mo>-</mml:mo>
 297                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 298                     </mml:mrow>
 299                 </mml:mfenced>
 300             </mml:math></inlineequation>
 301             and
 302             <inlineequation><mml:math>
 303                 <!-- eqn: (right, top,  -nearVal):-->
 304                 <mml:mfenced open="(" close=")">
 305                     <mml:mi mathvariant="italic">right</mml:mi>
 306                     <mml:mi mathvariant="italic">top</mml:mi>
 307                     <mml:mrow>
 308                         <mml:mo>-</mml:mo>
 309                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 310                     </mml:mrow>
 311                 </mml:mfenced>
 312             </mml:math></inlineequation>
 313             specify the points on the near clipping plane that are mapped
 314             to the lower left and upper right corners of the window,
 315             assuming that the eye is located at (0, 0, 0).
 316             <inlineequation><mml:math>
 317                 <!-- eqn: -farVal:-->
 318                 <mml:mrow>
 319                     <mml:mo>-</mml:mo>
 320                     <mml:mi mathvariant="italic">farVal</mml:mi>
 321                 </mml:mrow>
 322             </mml:math></inlineequation>
 323             specifies the location of the far clipping plane.
 324             Both <parameter>nearVal</parameter> and <parameter>farVal</parameter> must be positive.
 325         </para>
 326         <para>
 327             Use <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to save and restore
 328             the current matrix stack.
 329         </para>
 330     </refsect1>
 331     <refsect1 id="notes"><title>Notes</title>
 332         <para>
 333             Depth buffer precision is affected by the values specified for
 334             <parameter>nearVal</parameter> and <parameter>farVal</parameter>.
 335             The greater the ratio of <parameter>farVal</parameter> to <parameter>nearVal</parameter> is,
 336             the less effective the depth buffer will be at distinguishing between
 337             surfaces that are near each other.
 338             If
 339         </para>
 340         <para>
 341             <inlineequation><mml:math>
 342                 <!-- eqn: r  =  farVal over nearVal:-->
 343                 <mml:mrow>
 344                     <mml:mi mathvariant="italic">r</mml:mi>
 345                     <mml:mo>=</mml:mo>
 346                     <mml:mfrac>
 347                         <mml:mi mathvariant="italic">farVal</mml:mi>
 348                         <mml:mi mathvariant="italic">nearVal</mml:mi>
 349                     </mml:mfrac>
 350                 </mml:mrow>
 351             </mml:math></inlineequation>
 352         </para>
 353         <para>
 354             roughly
 355             <inlineequation><mml:math>
 356                 <!-- eqn: log sub 2 (r):-->
 357                 <mml:mrow>
 358                     <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 359                     <mml:mn>2</mml:mn>
 360                     </mml:msub>
 361                     <mml:mo>&af;</mml:mo>
 362                     <mml:mfenced open="(" close=")">
 363                         <mml:mi mathvariant="italic">r</mml:mi>
 364                     </mml:mfenced>
 365                 </mml:mrow>
 366             </mml:math></inlineequation>
 367             bits of depth buffer precision are lost.
 368             Because
 369             <inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>
 370             approaches infinity as <parameter>nearVal</parameter> approaches 0,
 371             <parameter>nearVal</parameter> must never be set to 0.
 372         </para>
 373     </refsect1>
 374     <refsect1 id="errors"><title>Errors</title>
 375         <para>
 376             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>nearVal</parameter> or <parameter>farVal</parameter> is not
 377             positive, or if <parameter>left</parameter> = <parameter>right</parameter>, or <parameter>bottom</parameter> = <parameter>top</parameter>,
 378             or <parameter>near</parameter> = <parameter>far</parameter>.
 379         </para>
 380         <para>
 381             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glFrustum</function>
 382             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 383             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 384         </para>
 385     </refsect1>
 386     <refsect1 id="associatedgets"><title>Associated Gets</title>
 387         <para>
 388             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MATRIX_MODE</constant>
 389         </para>
 390         <para>
 391             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MODELVIEW_MATRIX</constant>
 392         </para>
 393         <para>
 394             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PROJECTION_MATRIX</constant>
 395         </para>
 396         <para>
 397             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_MATRIX</constant>
 398         </para>
 399         <para>
 400             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATRIX</constant>
 401         </para>
 402     </refsect1>
 403     <refsect1 id="seealso"><title>See Also</title>
 404         <para>
 405             <citerefentry><refentrytitle>glOrtho</refentrytitle></citerefentry>,
 406             <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
 407             <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>,
 408             <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
 409             <citerefentry><refentrytitle>glViewport</refentrytitle></citerefentry>
 410         </para>
 411     </refsect1>
 412     <refsect1 id="Copyright"><title>Copyright</title>
 413         <para>
 414             Copyright <trademark class="copyright"></trademark> 1991-2006
 415             Silicon Graphics, Inc. This document is licensed under the SGI
 416             Free Software B License. For details, see
 417             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 418         </para>
 419     </refsect1>
 420 </refentry>