Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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> |