upstream-doc/man2/glWindowPos.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="glWindowPos">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glWindowPos</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glWindowPos</refname>
  17         <refpurpose>specify the raster position in window coordinates for pixel operations</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glWindowPos2s</function></funcdef>
  23                 <paramdef>GLshort <parameter>x</parameter></paramdef>
  24                 <paramdef>GLshort <parameter>y</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27         <funcsynopsis>
  28             <funcprototype>
  29                 <funcdef>void <function>glWindowPos2i</function></funcdef>
  30                 <paramdef>GLint <parameter>x</parameter></paramdef>
  31                 <paramdef>GLint <parameter>y</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34         <funcsynopsis>
  35             <funcprototype>
  36                 <funcdef>void <function>glWindowPos2f</function></funcdef>
  37                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
  38                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
  39             </funcprototype>
  40         </funcsynopsis>
  41         <funcsynopsis>
  42             <funcprototype>
  43                 <funcdef>void <function>glWindowPos2d</function></funcdef>
  44                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
  45                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
  46             </funcprototype>
  47         </funcsynopsis>
  48         <funcsynopsis>
  49             <funcprototype>
  50                 <funcdef>void <function>glWindowPos3s</function></funcdef>
  51                 <paramdef>GLshort <parameter>x</parameter></paramdef>
  52                 <paramdef>GLshort <parameter>y</parameter></paramdef>
  53                 <paramdef>GLshort <parameter>z</parameter></paramdef>
  54             </funcprototype>
  55         </funcsynopsis>
  56         <funcsynopsis>
  57             <funcprototype>
  58                 <funcdef>void <function>glWindowPos3i</function></funcdef>
  59                 <paramdef>GLint <parameter>x</parameter></paramdef>
  60                 <paramdef>GLint <parameter>y</parameter></paramdef>
  61                 <paramdef>GLint <parameter>z</parameter></paramdef>
  62             </funcprototype>
  63         </funcsynopsis>
  64         <funcsynopsis>
  65             <funcprototype>
  66                 <funcdef>void <function>glWindowPos3f</function></funcdef>
  67                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
  68                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
  69                 <paramdef>GLfloat <parameter>z</parameter></paramdef>
  70             </funcprototype>
  71         </funcsynopsis>
  72         <funcsynopsis>
  73             <funcprototype>
  74                 <funcdef>void <function>glWindowPos3d</function></funcdef>
  75                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
  76                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
  77                 <paramdef>GLdouble <parameter>z</parameter></paramdef>
  78             </funcprototype>
  79         </funcsynopsis>
  80     </refsynopsisdiv>
  81     <!-- eqn: ignoring delim $$ -->
  82     <refsect1 id="parameters"><title>Parameters</title>
  83         <variablelist>
  84         <varlistentry>
  85             <term><parameter>x</parameter></term>
  86             <term><parameter>y</parameter></term>
  87             <term><parameter>z</parameter></term>
  88             <listitem>
  89                 <para>
  90                     Specify the
  91                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
  92                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
  93                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
  94                     coordinates for the raster position.
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98         </variablelist>
  99     </refsect1>
 100     <refsynopsisdiv><title>C Specification</title>
 101         <funcsynopsis>
 102             <funcprototype>
 103                 <funcdef>void <function>glWindowPos2sv</function></funcdef>
 104                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 105             </funcprototype>
 106         </funcsynopsis>
 107         <funcsynopsis>
 108             <funcprototype>
 109                 <funcdef>void <function>glWindowPos2iv</function></funcdef>
 110                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 111             </funcprototype>
 112         </funcsynopsis>
 113         <funcsynopsis>
 114             <funcprototype>
 115                 <funcdef>void <function>glWindowPos2fv</function></funcdef>
 116                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 117             </funcprototype>
 118         </funcsynopsis>
 119         <funcsynopsis>
 120             <funcprototype>
 121                 <funcdef>void <function>glWindowPos2dv</function></funcdef>
 122                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 123             </funcprototype>
 124         </funcsynopsis>
 125         <funcsynopsis>
 126             <funcprototype>
 127                 <funcdef>void <function>glWindowPos3sv</function></funcdef>
 128                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 129             </funcprototype>
 130         </funcsynopsis>
 131         <funcsynopsis>
 132             <funcprototype>
 133                 <funcdef>void <function>glWindowPos3iv</function></funcdef>
 134                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 135             </funcprototype>
 136         </funcsynopsis>
 137         <funcsynopsis>
 138             <funcprototype>
 139                 <funcdef>void <function>glWindowPos3fv</function></funcdef>
 140                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 141             </funcprototype>
 142         </funcsynopsis>
 143         <funcsynopsis>
 144             <funcprototype>
 145                 <funcdef>void <function>glWindowPos3dv</function></funcdef>
 146                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 147             </funcprototype>
 148         </funcsynopsis>
 149     </refsynopsisdiv>
 150     <refsect1 id="parameters2"><title>Parameters</title>
 151         <variablelist>
 152         <varlistentry>
 153             <term><parameter>v</parameter></term>
 154             <listitem>
 155                 <para>
 156                     Specifies a pointer to an array of two or three elements,
 157                     specifying
 158                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 159                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 160                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 161                     coordinates, respectively.
 162                 </para>
 163             </listitem>
 164         </varlistentry>
 165         </variablelist>
 166     </refsect1>
 167     <refsect1 id="description"><title>Description</title>
 168         <para>
 169             The GL maintains a 3D position in window coordinates.  This position,
 170             called the raster position, is used to position pixel and bitmap write
 171             operations. It is maintained with subpixel accuracy.  See <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>,
 172             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
 173         </para>
 174         <para>
 175             <function>glWindowPos2</function> specifies the
 176             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
 177             and
 178             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
 179             coordinates, while
 180             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 181             is
 182             implicitly set to 0.  <function>glWindowPos3</function> specifies all three coordinates.
 183             The
 184             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 185             coordinate of the current raster position is always set to 1.0.
 186         </para>
 187         <para>
 188             <function>glWindowPos</function> directly updates the
 189             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
 190             and
 191             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
 192             coordinates of the current raster
 193             position with the values specified.  That is, the values are neither
 194             transformed by the current modelview and projection matrices, nor by
 195             the viewport-to-window transform.  The
 196             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 197             coordinate of the current raster
 198             position is updated in the following manner:
 199         </para>
 200         <para>
 201             <informalequation><mml:math>
 202                 <!-- eqn: z =  left{   lpile {    n above    f above    {n + z * (f - n)} }        lpile { if z <= 0 above if z >= 1 above {roman otherwise} }:-->
 203                 <mml:mrow>
 204                     <mml:mi mathvariant="italic">z</mml:mi>
 205                     <mml:mo>=</mml:mo>
 206                     <mml:mfenced open="{" close="">
 207                         <mml:mrow>
 208                             <mml:mtable>
 209                                 <mml:mtr><mml:mtd>
 210                                     <mml:mi mathvariant="italic">n</mml:mi>
 211                                 </mml:mtd></mml:mtr>
 212                                 <mml:mtr><mml:mtd>
 213                                     <mml:mi mathvariant="italic">f</mml:mi>
 214                                 </mml:mtd></mml:mtr>
 215                                 <mml:mtr><mml:mtd>
 216                                     <mml:mfenced open="" close="">
 217                                         <mml:mrow>
 218                                             <mml:mi mathvariant="italic">n</mml:mi>
 219                                             <mml:mo>+</mml:mo>
 220                                             <mml:mrow>
 221                                                 <mml:mi mathvariant="italic">z</mml:mi>
 222                                                 <mml:mo>&times;</mml:mo>
 223                                                 <mml:mfenced open="(" close=")">
 224                                                     <mml:mrow>
 225                                                         <mml:mi mathvariant="italic">f</mml:mi>
 226                                                         <mml:mo>-</mml:mo>
 227                                                         <mml:mi mathvariant="italic">n</mml:mi>
 228                                                     </mml:mrow>
 229                                                 </mml:mfenced>
 230                                             </mml:mrow>
 231                                         </mml:mrow>
 232                                     </mml:mfenced>
 233                                 </mml:mtd></mml:mtr>
 234                             </mml:mtable>
 235                             <mml:mo>&it;</mml:mo>
 236                             <mml:mtable>
 237                                 <mml:mtr><mml:mtd>
 238                                     <mml:mrow>
 239                                         <mml:mrow>
 240                                             <mml:mi mathvariant="italic">if</mml:mi>
 241                                             <mml:mo>&it;</mml:mo>
 242                                             <mml:mi mathvariant="italic">z</mml:mi>
 243                                         </mml:mrow>
 244                                         <mml:mo>&lt;=</mml:mo>
 245                                         <mml:mn>0</mml:mn>
 246                                     </mml:mrow>
 247                                 </mml:mtd></mml:mtr>
 248                                 <mml:mtr><mml:mtd>
 249                                     <mml:mrow>
 250                                         <mml:mrow>
 251                                             <mml:mi mathvariant="italic">if</mml:mi>
 252                                             <mml:mo>&it;</mml:mo>
 253                                             <mml:mi mathvariant="italic">z</mml:mi>
 254                                         </mml:mrow>
 255                                         <mml:mo>&gt;=</mml:mo>
 256                                         <mml:mn>1</mml:mn>
 257                                     </mml:mrow>
 258                                 </mml:mtd></mml:mtr>
 259                                 <mml:mtr><mml:mtd>
 260                                     <mml:mfenced open="" close="">
 261                                         <mml:mi mathvariant="normal">otherwise</mml:mi>
 262                                     </mml:mfenced>
 263                                 </mml:mtd></mml:mtr>
 264                             </mml:mtable>
 265                         </mml:mrow>
 266                     </mml:mfenced>
 267                 </mml:mrow>
 268             </mml:math></informalequation>
 269         </para>
 270         <para>
 271         </para>
 272         <para>
 273             where
 274             <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
 275             is <constant>GL_DEPTH_RANGE</constant>'s near value, and
 276             <inlineequation><mml:math><mml:mi mathvariant="italic">f</mml:mi></mml:math></inlineequation>
 277             is
 278             <constant>GL_DEPTH_RANGE</constant>'s far value.  See <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>.
 279         </para>
 280         <para>
 281             The specified coordinates are not clip-tested, causing the raster position
 282             to always be valid.
 283         </para>
 284         <para>
 285             The current raster position also includes some associated color data and
 286             texture coordinates.  If lighting is enabled, then
 287             <constant>GL_CURRENT_RASTER_COLOR</constant> (in RGBA mode) or <constant>GL_CURRENT_RASTER_INDEX</constant>
 288             (in color index mode) is set to the color produced by the lighting
 289             calculation (see <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glShadeModel</refentrytitle></citerefentry>).
 290             If lighting is disabled, current color (in RGBA mode, state variable
 291             <constant>GL_CURRENT_COLOR</constant>) or color index (in color index mode, state variable
 292             <constant>GL_CURRENT_INDEX</constant>) is used to update the current raster color.
 293             <constant>GL_CURRENT_RASTER_SECONDARY_COLOR</constant> (in RGBA mode) is likewise updated.
 294         </para>
 295         <para>
 296             Likewise, <constant>GL_CURRENT_RASTER_TEXTURE_COORDS</constant> is updated as a function of
 297             <constant>GL_CURRENT_TEXTURE_COORDS</constant>, based on the texture matrix and the texture
 298             generation functions (see <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>).  The
 299             <constant>GL_CURRENT_RASTER_DISTANCE</constant> is set to the <constant>GL_CURRENT_FOG_COORD</constant>.
 300         </para>
 301         <para>
 302         </para>
 303     </refsect1>
 304     <refsect1 id="notes"><title>Notes</title>
 305         <para>
 306             <function>glWindowPos</function> is available only if the GL version is 1.4 or greater.
 307         </para>
 308         <para>
 309             The raster position is modified by <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>, and
 310             <function>glWindowPos</function>.
 311         </para>
 312         <para>
 313             Calling <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> may leave the
 314             current color or index indeterminate.
 315             If <function>glWindowPos</function> is executed while the current color or index is indeterminate, the
 316             current raster color or current raster index remains indeterminate.
 317         </para>
 318         <para>
 319             There are distinct raster texture coordinates for each texture unit. Each
 320             texture unit's current raster texture coordinates are updated by <function>glWindowPos</function>.
 321         </para>
 322     </refsect1>
 323     <refsect1 id="errors"><title>Errors</title>
 324         <para>
 325             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glWindowPos</function>
 326             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 327             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 328         </para>
 329     </refsect1>
 330     <refsect1 id="associatedgets"><title>Associated Gets</title>
 331         <para>
 332             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
 333         </para>
 334         <para>
 335             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
 336         </para>
 337         <para>
 338             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_DISTANCE</constant>
 339         </para>
 340         <para>
 341             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_COLOR</constant>
 342         </para>
 343         <para>
 344             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_SECONDARY_COLOR</constant>
 345         </para>
 346         <para>
 347             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_INDEX</constant>
 348         </para>
 349         <para>
 350             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_TEXTURE_COORDS</constant>
 351         </para>
 352     </refsect1>
 353     <refsect1 id="seealso"><title>See Also</title>
 354         <para>
 355             <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>,
 356             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 357             <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
 358             <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
 359             <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
 360             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 361             <citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
 362             <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>,
 363             <citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
 364             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 365             <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
 366         </para>
 367     </refsect1>
 368     <refsect1 id="Copyright"><title>Copyright</title>
 369         <para>
 370             Copyright <trademark class="copyright"></trademark> 1991-2006
 371             Silicon Graphics, Inc. This document is licensed under the SGI
 372             Free Software B License. For details, see
 373             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 374         </para>
 375     </refsect1>
 376 </refentry>