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