upstream-man-pages/man2/glRasterPos.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="glRasterPos">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glRasterPos</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glRasterPos</refname>
  17         <refpurpose>specify the raster position for pixel operations</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glRasterPos2s</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>glRasterPos2i</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>glRasterPos2f</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>glRasterPos2d</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>glRasterPos3s</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>glRasterPos3i</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>glRasterPos3f</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>glRasterPos3d</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         <funcsynopsis>
  81             <funcprototype>
  82                 <funcdef>void <function>glRasterPos4s</function></funcdef>
  83                 <paramdef>GLshort <parameter>x</parameter></paramdef>
  84                 <paramdef>GLshort <parameter>y</parameter></paramdef>
  85                 <paramdef>GLshort <parameter>z</parameter></paramdef>
  86                 <paramdef>GLshort <parameter>w</parameter></paramdef>
  87             </funcprototype>
  88         </funcsynopsis>
  89         <funcsynopsis>
  90             <funcprototype>
  91                 <funcdef>void <function>glRasterPos4i</function></funcdef>
  92                 <paramdef>GLint <parameter>x</parameter></paramdef>
  93                 <paramdef>GLint <parameter>y</parameter></paramdef>
  94                 <paramdef>GLint <parameter>z</parameter></paramdef>
  95                 <paramdef>GLint <parameter>w</parameter></paramdef>
  96             </funcprototype>
  97         </funcsynopsis>
  98         <funcsynopsis>
  99             <funcprototype>
 100                 <funcdef>void <function>glRasterPos4f</function></funcdef>
 101                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
 102                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
 103                 <paramdef>GLfloat <parameter>z</parameter></paramdef>
 104                 <paramdef>GLfloat <parameter>w</parameter></paramdef>
 105             </funcprototype>
 106         </funcsynopsis>
 107         <funcsynopsis>
 108             <funcprototype>
 109                 <funcdef>void <function>glRasterPos4d</function></funcdef>
 110                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
 111                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
 112                 <paramdef>GLdouble <parameter>z</parameter></paramdef>
 113                 <paramdef>GLdouble <parameter>w</parameter></paramdef>
 114             </funcprototype>
 115         </funcsynopsis>
 116     </refsynopsisdiv>
 117     <!-- eqn: ignoring delim $$ -->
 118     <refsect1 id="parameters"><title>Parameters</title>
 119         <variablelist>
 120         <varlistentry>
 121             <term><parameter>x</parameter></term>
 122             <term><parameter>y</parameter></term>
 123             <term><parameter>z</parameter></term>
 124             <term><parameter>w</parameter></term>
 125             <listitem>
 126                 <para>
 127                     Specify the
 128                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 129                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 130                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>,
 131                     and
 132                     <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 133                     object coordinates
 134                     (if present)
 135                     for the raster
 136                     position.
 137                 </para>
 138             </listitem>
 139         </varlistentry>
 140         </variablelist>
 141     </refsect1>
 142     <refsynopsisdiv><title>C Specification</title>
 143         <funcsynopsis>
 144             <funcprototype>
 145                 <funcdef>void <function>glRasterPos2sv</function></funcdef>
 146                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 147             </funcprototype>
 148         </funcsynopsis>
 149         <funcsynopsis>
 150             <funcprototype>
 151                 <funcdef>void <function>glRasterPos2iv</function></funcdef>
 152                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 153             </funcprototype>
 154         </funcsynopsis>
 155         <funcsynopsis>
 156             <funcprototype>
 157                 <funcdef>void <function>glRasterPos2fv</function></funcdef>
 158                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 159             </funcprototype>
 160         </funcsynopsis>
 161         <funcsynopsis>
 162             <funcprototype>
 163                 <funcdef>void <function>glRasterPos2dv</function></funcdef>
 164                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 165             </funcprototype>
 166         </funcsynopsis>
 167         <funcsynopsis>
 168             <funcprototype>
 169                 <funcdef>void <function>glRasterPos3sv</function></funcdef>
 170                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 171             </funcprototype>
 172         </funcsynopsis>
 173         <funcsynopsis>
 174             <funcprototype>
 175                 <funcdef>void <function>glRasterPos3iv</function></funcdef>
 176                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 177             </funcprototype>
 178         </funcsynopsis>
 179         <funcsynopsis>
 180             <funcprototype>
 181                 <funcdef>void <function>glRasterPos3fv</function></funcdef>
 182                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 183             </funcprototype>
 184         </funcsynopsis>
 185         <funcsynopsis>
 186             <funcprototype>
 187                 <funcdef>void <function>glRasterPos3dv</function></funcdef>
 188                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 189             </funcprototype>
 190         </funcsynopsis>
 191         <funcsynopsis>
 192             <funcprototype>
 193                 <funcdef>void <function>glRasterPos4sv</function></funcdef>
 194                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 195             </funcprototype>
 196         </funcsynopsis>
 197         <funcsynopsis>
 198             <funcprototype>
 199                 <funcdef>void <function>glRasterPos4iv</function></funcdef>
 200                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 201             </funcprototype>
 202         </funcsynopsis>
 203         <funcsynopsis>
 204             <funcprototype>
 205                 <funcdef>void <function>glRasterPos4fv</function></funcdef>
 206                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 207             </funcprototype>
 208         </funcsynopsis>
 209         <funcsynopsis>
 210             <funcprototype>
 211                 <funcdef>void <function>glRasterPos4dv</function></funcdef>
 212                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 213             </funcprototype>
 214         </funcsynopsis>
 215     </refsynopsisdiv>
 216     <refsect1 id="parameters2"><title>Parameters</title>
 217         <variablelist>
 218         <varlistentry>
 219             <term><parameter>v</parameter></term>
 220             <listitem>
 221                 <para>
 222                     Specifies a pointer to an array of two,
 223                     three,
 224                     or four elements,
 225                     specifying
 226                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 227                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 228                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>,
 229                     and
 230                     <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 231                     coordinates, respectively.
 232                 </para>
 233             </listitem>
 234         </varlistentry>
 235         </variablelist>
 236     </refsect1>
 237     <refsect1 id="description"><title>Description</title>
 238         <para>
 239             The GL maintains a 3D position in window coordinates.
 240             This position,
 241             called the raster position,
 242             is used to position pixel and bitmap write operations. It is
 243             maintained with subpixel accuracy.
 244             See <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>.
 245         </para>
 246         <para>
 247             The current raster position consists of three window coordinates
 248             (<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 249             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 250             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>),
 251             a clip coordinate value
 252             (<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>),
 253             an eye coordinate distance,
 254             a valid bit,
 255             and associated color data and texture coordinates.
 256             The
 257             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 258             coordinate is a clip coordinate,
 259             because
 260             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 261             is not projected to window coordinates.
 262             <function>glRasterPos4</function> specifies object coordinates
 263             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 264             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 265             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>,
 266             and
 267             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 268             explicitly.
 269             <function>glRasterPos3</function> specifies object coordinate
 270             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 271             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 272             and
 273             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 274             explicitly,
 275             while
 276             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 277             is implicitly set to 1.
 278             <function>glRasterPos2</function> uses the argument values for
 279             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
 280             and
 281             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
 282             while
 283             implicitly setting
 284             <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 285             and
 286             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 287             to 0 and 1.
 288         </para>
 289         <para>
 290             The object coordinates presented by <function>glRasterPos</function> are treated just like those
 291             of a <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry> command:
 292             They are transformed by the current modelview and projection matrices
 293             and passed to the clipping stage.
 294             If the vertex is not culled,
 295             then it is projected and scaled to window coordinates,
 296             which become the new current raster position,
 297             and the <constant>GL_CURRENT_RASTER_POSITION_VALID</constant> flag is set.
 298             If the vertex
 299             <emphasis>is</emphasis>
 300             culled,
 301             then the valid bit is cleared and the current raster position
 302             and associated color and texture coordinates are undefined.
 303         </para>
 304         <para>
 305             The current raster position also includes some associated color data
 306             and texture coordinates.
 307             If lighting is enabled,
 308             then <constant>GL_CURRENT_RASTER_COLOR</constant>
 309             (in RGBA mode)
 310             or <constant>GL_CURRENT_RASTER_INDEX</constant>
 311             (in color index mode)
 312             is set to the color produced by the lighting calculation
 313             (see <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>, and
 314             <citerefentry><refentrytitle>glShadeModel</refentrytitle></citerefentry>).
 315             If lighting is disabled,
 316             current color
 317             (in RGBA mode, state variable <constant>GL_CURRENT_COLOR</constant>)
 318             or color index
 319             (in color index mode, state variable <constant>GL_CURRENT_INDEX</constant>)
 320             is used to update the current raster color.
 321             <constant>GL_CURRENT_RASTER_SECONDARY_COLOR</constant> (in RGBA mode) is likewise updated.
 322         </para>
 323         <para>
 324             Likewise,
 325             <constant>GL_CURRENT_RASTER_TEXTURE_COORDS</constant> is updated as a function
 326             of <constant>GL_CURRENT_TEXTURE_COORDS</constant>,
 327             based on the texture matrix and the texture generation functions
 328             (see <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>).
 329             Finally,
 330             the distance from the origin of the eye coordinate system to the
 331             vertex as transformed by only the modelview matrix replaces
 332             <constant>GL_CURRENT_RASTER_DISTANCE</constant>.
 333         </para>
 334         <para>
 335             Initially, the current raster position is (0, 0, 0, 1),
 336             the current raster distance is 0,
 337             the valid bit is set,
 338             the associated RGBA color is (1, 1, 1, 1),
 339             the associated color index is 1,
 340             and the associated texture coordinates are (0, 0, 0, 1).
 341             In RGBA mode,
 342             <constant>GL_CURRENT_RASTER_INDEX</constant> is always 1;
 343             in color index mode,
 344             the current raster RGBA color always maintains its initial value.
 345         </para>
 346     </refsect1>
 347     <refsect1 id="notes"><title>Notes</title>
 348         <para>
 349             The raster position is modified by <function>glRasterPos</function>, <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>.
 350         </para>
 351         <para>
 352             When the raster position coordinates are invalid,
 353             drawing commands that are based on the raster position are
 354             ignored (that is, they do not result in changes to GL state).
 355         </para>
 356         <para>
 357             Calling <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry> may leave the
 358             current color or index indeterminate.
 359             If <function>glRasterPos</function> is executed while the current color or index is indeterminate, the
 360             current raster color or current raster index remains indeterminate.
 361         </para>
 362         <para>
 363             To set a valid raster position outside the viewport, first set a valid
 364             raster position, then call <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry> with NULL as the <emphasis>bitmap</emphasis>
 365             parameter.
 366         </para>
 367         <para>
 368             When the <code>ARB_imaging</code> extension is supported, there are distinct
 369             raster texture coordinates for each texture unit. Each texture unit's
 370             current raster texture coordinates are updated by <function>glRasterPos</function>.
 371         </para>
 372     </refsect1>
 373     <refsect1 id="errors"><title>Errors</title>
 374         <para>
 375             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glRasterPos</function>
 376             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 377             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 378         </para>
 379     </refsect1>
 380     <refsect1 id="associatedgets"><title>Associated Gets</title>
 381         <para>
 382             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
 383         </para>
 384         <para>
 385             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
 386         </para>
 387         <para>
 388             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_DISTANCE</constant>
 389         </para>
 390         <para>
 391             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_COLOR</constant>
 392         </para>
 393         <para>
 394             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_SECONDARY_COLOR</constant>
 395         </para>
 396         <para>
 397             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_INDEX</constant>
 398         </para>
 399         <para>
 400             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_TEXTURE_COORDS</constant>
 401         </para>
 402     </refsect1>
 403     <refsect1 id="seealso"><title>See Also</title>
 404         <para>
 405             <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>,
 406             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 407             <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
 408             <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
 409             <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
 410             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 411             <citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
 412             <citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
 413             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 414             <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>,
 415             <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>
 416         </para>
 417     </refsect1>
 418     <refsect1 id="Copyright"><title>Copyright</title>
 419         <para>
 420             Copyright <trademark class="copyright"></trademark> 1991-2006
 421             Silicon Graphics, Inc. This document is licensed under the SGI
 422             Free Software B License. For details, see
 423             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 424         </para>
 425     </refsect1>
 426 </refentry>