HCoop / clinton / guile-figl.git / blob
? search:


edbceee76700dc9d6771eba6daf193cd325430f9
[clinton/guile-figl.git] / upstream-man-pages / man2 / glDrawPixels.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="glDrawPixels">
5 <refmeta>
6 <refmetainfo>
7 <copyright>
8 <year>1991-2006</year>
9 <holder>Silicon Graphics, Inc.</holder>
10 </copyright>
11 </refmetainfo>
12 <refentrytitle>glDrawPixels</refentrytitle>
13 <manvolnum>3G</manvolnum>
14 </refmeta>
15 <refnamediv>
16 <refname>glDrawPixels</refname>
17 <refpurpose>write a block of pixels to the frame buffer</refpurpose>
18 </refnamediv>
19 <refsynopsisdiv><title>C Specification</title>
20 <funcsynopsis>
21 <funcprototype>
22 <funcdef>void <function>glDrawPixels</function></funcdef>
23 <paramdef>GLsizei <parameter>width</parameter></paramdef>
24 <paramdef>GLsizei <parameter>height</parameter></paramdef>
25 <paramdef>GLenum <parameter>format</parameter></paramdef>
26 <paramdef>GLenum <parameter>type</parameter></paramdef>
27 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
28 </funcprototype>
29 </funcsynopsis>
30 </refsynopsisdiv>
31 <!-- eqn: ignoring delim $$ -->
32 <refsect1 id="parameters"><title>Parameters</title>
33 <variablelist>
34 <varlistentry>
35 <term><parameter>width</parameter></term>
36 <term><parameter>height</parameter></term>
37 <listitem>
38 <para>
39 Specify the dimensions of the pixel rectangle to be written
40 into the frame buffer.
41 </para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>format</parameter></term>
46 <listitem>
47 <para>
48 Specifies the format of the pixel data.
49 Symbolic constants
50 <constant>GL_COLOR_INDEX</constant>,
51 <constant>GL_STENCIL_INDEX</constant>,
52 <constant>GL_DEPTH_COMPONENT</constant>,
53 <constant>GL_RGB</constant>,
54 <constant>GL_BGR</constant>,
55 <constant>GL_RGBA</constant>,
56 <constant>GL_BGRA</constant>,
57 <constant>GL_RED</constant>,
58 <constant>GL_GREEN</constant>,
59 <constant>GL_BLUE</constant>,
60 <constant>GL_ALPHA</constant>,
61 <constant>GL_LUMINANCE</constant>, and
62 <constant>GL_LUMINANCE_ALPHA</constant> are accepted.
63 </para>
64 </listitem>
65 </varlistentry>
66 <varlistentry>
67 <term><parameter>type</parameter></term>
68 <listitem>
69 <para>
70 Specifies the data type for <parameter>data</parameter>.
71 Symbolic constants
72 <constant>GL_UNSIGNED_BYTE</constant>,
73 <constant>GL_BYTE</constant>,
74 <constant>GL_BITMAP</constant>,
75 <constant>GL_UNSIGNED_SHORT</constant>,
76 <constant>GL_SHORT</constant>,
77 <constant>GL_UNSIGNED_INT</constant>,
78 <constant>GL_INT</constant>,
79 <constant>GL_FLOAT</constant>,
80 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
81 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
82 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
83 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
84 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
85 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
86 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
87 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
88 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
89 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
90 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
91 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
92 are accepted.
93 </para>
94 </listitem>
95 </varlistentry>
96 <varlistentry>
97 <term><parameter>data</parameter></term>
98 <listitem>
99 <para>
100 Specifies a pointer to the pixel data.
101 </para>
102 </listitem>
103 </varlistentry>
104 </variablelist>
105 </refsect1>
106 <refsect1 id="description"><title>Description</title>
107 <para>
108 <function>glDrawPixels</function> reads pixel data from memory and writes it into the frame buffer
109 relative to the current raster position, provided that the raster
110 position is valid. Use
111 <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry> to set the current raster position; use
112 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
113 to determine if the specified raster position is valid, and
114 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
115 to query the raster position.
116 </para>
117 <para>
118 Several parameters define the encoding of pixel data in memory
119 and control the processing of the pixel data
120 before it is placed in the frame buffer.
121 These parameters are set with four commands:
122 <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
123 <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
124 <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>.
125 This reference page describes the effects on <function>glDrawPixels</function> of many,
126 but not all, of the parameters specified by these four commands.
127 </para>
128 <para>
129 Data is read from <parameter>data</parameter> as a sequence of signed or unsigned bytes,
130 signed or unsigned shorts, signed or unsigned integers, or
131 single-precision floating-point values, depending on <parameter>type</parameter>.
132 When <parameter>type</parameter> is one of <constant>GL_UNSIGNED_BYTE</constant>, <constant>GL_BYTE</constant>,
133 <constant>GL_UNSIGNED_SHORT</constant>, <constant>GL_SHORT</constant>, <constant>GL_UNSIGNED_INT</constant>,
134 <constant>GL_INT</constant>, or <constant>GL_FLOAT</constant> each of these bytes, shorts, integers, or
135 floating-point values is interpreted as one color or depth component, or
136 one index, depending on <parameter>format</parameter>.
137 When <parameter>type</parameter> is one of <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
138 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
139 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>, <constant>GL_UNSIGNED_INT_8_8_8_8</constant>, or
140 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, each unsigned value is interpreted as
141 containing all the components for a single pixel, with the color
142 components arranged according to <parameter>format</parameter>.
143 When <parameter>type</parameter> is one of <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
144 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>, <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
145 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>, <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>, or
146 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>, each unsigned value is interpreted
147 as containing all color components, specified by <parameter>format</parameter>, for a single
148 pixel in a reversed order. Indices are always treated individually.
149 Color components are treated as groups of one, two, three, or four
150 values, again based on <parameter>format</parameter>. Both individual indices and groups of
151 components are referred to as pixels.
152 If <parameter>type</parameter> is <constant>GL_BITMAP</constant>, the data must be unsigned bytes, and
153 <parameter>format</parameter> must be either <constant>GL_COLOR_INDEX</constant> or <constant>GL_STENCIL_INDEX</constant>.
154 Each unsigned byte is treated as eight 1-bit pixels, with bit ordering
155 determined by <constant>GL_UNPACK_LSB_FIRST</constant> (see <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>).
156 </para>
157 <para>
158 <inlineequation><mml:math>
159 <!-- eqn: width times height:-->
160 <mml:mrow>
161 <mml:mi mathvariant="italic">width</mml:mi>
162 <mml:mo>&times;</mml:mo>
163 <mml:mi mathvariant="italic">height</mml:mi>
164 </mml:mrow>
165 </mml:math></inlineequation>
166 pixels are read from memory,
167 starting at location <parameter>data</parameter>.
168 By default, these pixels are taken from adjacent memory locations,
169 except that after all <parameter>width</parameter> pixels are read,
170 the read pointer is advanced to the next four-byte boundary.
171 The four-byte row alignment is specified by <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> with
172 argument <constant>GL_UNPACK_ALIGNMENT</constant>,
173 and it can be set to one, two, four, or eight bytes.
174 Other pixel store parameters specify different read pointer advancements,
175 both before the first pixel is read
176 and after all <parameter>width</parameter> pixels are read.
177 See the <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> reference page for details on these options.
178 </para>
179 <para>
180 If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
181 (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a block of pixels is
182 specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
183 </para>
184 <para>
185 The
186 <inlineequation><mml:math>
187 <!-- eqn: width times height:-->
188 <mml:mrow>
189 <mml:mi mathvariant="italic">width</mml:mi>
190 <mml:mo>&times;</mml:mo>
191 <mml:mi mathvariant="italic">height</mml:mi>
192 </mml:mrow>
193 </mml:math></inlineequation>
194 pixels that are read from memory are
195 each operated on in the same way,
196 based on the values of several parameters specified by <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>
197 and <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>.
198 The details of these operations,
199 as well as the target buffer into which the pixels are drawn,
200 are specific to the format of the pixels,
201 as specified by <parameter>format</parameter>.
202 <parameter>format</parameter> can assume one of 13 symbolic values:
203 </para>
204 <variablelist>
205 <varlistentry>
206 <term><constant>GL_COLOR_INDEX</constant></term>
207 <listitem>
208 <para>
209 Each pixel is a single value,
210 a color index.
211 It is converted to fixed-point format,
212 with an unspecified number of bits to the right of the binary point,
213 regardless of the memory data type.
214 Floating-point values convert to true fixed-point values.
215 Signed and unsigned integer data is converted with all fraction bits
216 set to 0.
217 Bitmap data convert to either 0 or 1.
218 </para>
219 <para>
220 Each fixed-point index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits
221 and added to <constant>GL_INDEX_OFFSET</constant>.
222 If <constant>GL_INDEX_SHIFT</constant> is negative,
223 the shift is to the right.
224 In either case, zero bits fill otherwise unspecified bit locations in the
225 result.
226 </para>
227 <para>
228 If the GL is in RGBA mode,
229 the resulting index is converted to an RGBA pixel
230 with the help of the <constant>GL_PIXEL_MAP_I_TO_R</constant>,
231 <constant>GL_PIXEL_MAP_I_TO_G</constant>,
232 <constant>GL_PIXEL_MAP_I_TO_B</constant>,
233 and <constant>GL_PIXEL_MAP_I_TO_A</constant> tables.
234 If the GL is in color index mode,
235 and if <constant>GL_MAP_COLOR</constant> is true,
236 the index is replaced with the value that it references in lookup table
237 <constant>GL_PIXEL_MAP_I_TO_I</constant>.
238 Whether the lookup replacement of the index is done or not,
239 the integer part of the index is then ANDed with
240 <inlineequation><mml:math>
241 <!-- eqn: 2 sup b -1:-->
242 <mml:mrow>
243 <mml:msup><mml:mn>2</mml:mn>
244 <mml:mi mathvariant="italic">b</mml:mi>
245 </mml:msup>
246 <mml:mo>-</mml:mo>
247 <mml:mn>1</mml:mn>
248 </mml:mrow>
249 </mml:math></inlineequation>,
250 where
251 <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
252 is the number of bits in a color index buffer.
253 </para>
254 <para>
255 The GL then converts the resulting indices or RGBA colors to fragments
256 by attaching the current raster position <emphasis>z</emphasis> coordinate and
257 texture coordinates to each pixel,
258 then assigning
259 <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
260 and
261 <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
262 window coordinates to the
263 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
264 fragment such that
265 <informalequation><mml:math>
266 <!-- eqn: x sub n = x sub r + n mod width:-->
267 <mml:mrow>
268 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
269 <mml:mi mathvariant="italic">n</mml:mi>
270 </mml:msub>
271 <mml:mo>=</mml:mo>
272 <mml:mrow>
273 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
274 <mml:mi mathvariant="italic">r</mml:mi>
275 </mml:msub>
276 <mml:mo>+</mml:mo>
277 <mml:mrow>
278 <mml:mi mathvariant="italic">n</mml:mi>
279 <mml:mo>%</mml:mo>
280 <mml:mi mathvariant="italic">width</mml:mi>
281 </mml:mrow>
282 </mml:mrow>
283 </mml:mrow>
284 </mml:math></informalequation>
285 <para>
286 <informalequation><mml:math>
287 <!-- eqn: y sub n = y sub r + \(lf n / width \(rf:-->
288 <mml:mrow>
289 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
290 <mml:mi mathvariant="italic">n</mml:mi>
291 </mml:msub>
292 <mml:mo>=</mml:mo>
293 <mml:mrow>
294 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
295 <mml:mi mathvariant="italic">r</mml:mi>
296 </mml:msub>
297 <mml:mo>+</mml:mo>
298 <mml:mfenced open="&LeftFloor;" close="&RightFloor;">
299 <mml:mfrac>
300 <mml:mi mathvariant="italic">n</mml:mi>
301 <mml:mi mathvariant="italic">width</mml:mi>
302 </mml:mfrac>
303 </mml:mfenced>
304 </mml:mrow>
305 </mml:mrow>
306 </mml:math></informalequation>
307 </para>
308 <para>
309 </para>
310 </para>
311 <para>
312 where
313 <inlineequation><mml:math>
314 <!-- eqn: (x sub r , y sub r):-->
315 <mml:mfenced open="(" close=")">
316 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
317 <mml:mi mathvariant="italic">r</mml:mi>
318 </mml:msub>
319 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
320 <mml:mi mathvariant="italic">r</mml:mi>
321 </mml:msub>
322 </mml:mfenced>
323 </mml:math></inlineequation>
324 is the current raster position.
325 These pixel fragments are then treated just like the fragments generated by
326 rasterizing points, lines, or polygons.
327 Texture mapping,
328 fog,
329 and all the fragment operations are applied before the fragments are written
330 to the frame buffer.
331 </para>
332 </listitem>
333 </varlistentry>
334 <varlistentry>
335 <term><constant>GL_STENCIL_INDEX</constant></term>
336 <listitem>
337 <para>
338 Each pixel is a single value,
339 a stencil index.
340 It is converted to fixed-point format,
341 with an unspecified number of bits to the right of the binary point,
342 regardless of the memory data type.
343 Floating-point values convert to true fixed-point values.
344 Signed and unsigned integer data is converted with all fraction bits
345 set to 0.
346 Bitmap data convert to either 0 or 1.
347 </para>
348 <para>
349 Each fixed-point index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits,
350 and added to <constant>GL_INDEX_OFFSET</constant>.
351 If <constant>GL_INDEX_SHIFT</constant> is negative,
352 the shift is to the right.
353 In either case, zero bits fill otherwise unspecified bit locations in the
354 result.
355 If <constant>GL_MAP_STENCIL</constant> is true,
356 the index is replaced with the value that it references in lookup table
357 <constant>GL_PIXEL_MAP_S_TO_S</constant>.
358 Whether the lookup replacement of the index is done or not,
359 the integer part of the index is then ANDed with
360 <inlineequation><mml:math>
361 <!-- eqn: 2 sup b -1:-->
362 <mml:mrow>
363 <mml:msup><mml:mn>2</mml:mn>
364 <mml:mi mathvariant="italic">b</mml:mi>
365 </mml:msup>
366 <mml:mo>-</mml:mo>
367 <mml:mn>1</mml:mn>
368 </mml:mrow>
369 </mml:math></inlineequation>,
370 where
371 <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
372 is the number of bits in the stencil buffer.
373 The resulting stencil indices are then written to the stencil buffer
374 such that the
375 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
376 index is written to location
377 </para>
378 <para>
379 <informalequation><mml:math>
380 <!-- eqn: x sub n = x sub r + n mod width:-->
381 <mml:mrow>
382 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
383 <mml:mi mathvariant="italic">n</mml:mi>
384 </mml:msub>
385 <mml:mo>=</mml:mo>
386 <mml:mrow>
387 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
388 <mml:mi mathvariant="italic">r</mml:mi>
389 </mml:msub>
390 <mml:mo>+</mml:mo>
391 <mml:mrow>
392 <mml:mi mathvariant="italic">n</mml:mi>
393 <mml:mo>%</mml:mo>
394 <mml:mi mathvariant="italic">width</mml:mi>
395 </mml:mrow>
396 </mml:mrow>
397 </mml:mrow>
398 </mml:math></informalequation>
399 <para>
400 <informalequation><mml:math>
401 <!-- eqn: y sub n = y sub r + \(lf n / width \(rf:-->
402 <mml:mrow>
403 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
404 <mml:mi mathvariant="italic">n</mml:mi>
405 </mml:msub>
406 <mml:mo>=</mml:mo>
407 <mml:mrow>
408 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
409 <mml:mi mathvariant="italic">r</mml:mi>
410 </mml:msub>
411 <mml:mo>+</mml:mo>
412 <mml:mfenced open="&LeftFloor;" close="&RightFloor;">
413 <mml:mfrac>
414 <mml:mi mathvariant="italic">n</mml:mi>
415 <mml:mi mathvariant="italic">width</mml:mi>
416 </mml:mfrac>
417 </mml:mfenced>
418 </mml:mrow>
419 </mml:mrow>
420 </mml:math></informalequation>
421 </para>
422 </para>
423 <para>
424 where
425 <inlineequation><mml:math>
426 <!-- eqn: (x sub r , y sub r):-->
427 <mml:mfenced open="(" close=")">
428 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
429 <mml:mi mathvariant="italic">r</mml:mi>
430 </mml:msub>
431 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
432 <mml:mi mathvariant="italic">r</mml:mi>
433 </mml:msub>
434 </mml:mfenced>
435 </mml:math></inlineequation>
436 is the current raster position.
437 Only the pixel ownership test,
438 the scissor test,
439 and the stencil writemask affect these write operations.
440 </para>
441 </listitem>
442 </varlistentry>
443 <varlistentry>
444 <term><constant>GL_DEPTH_COMPONENT</constant></term>
445 <listitem>
446 <para>
447 Each pixel is a single-depth component.
448 Floating-point data is converted directly to an internal floating-point
449 format with unspecified precision.
450 Signed integer data is mapped linearly to the internal floating-point
451 format such that the most positive representable integer value maps to 1.0,
452 and the most negative representable value maps to
453 <inlineequation><mml:math>
454 <!-- eqn: -1.0:-->
455 <mml:mn>-1.0</mml:mn>
456 </mml:math></inlineequation>.
457 Unsigned integer data is mapped similarly:
458 the largest integer value maps to 1.0,
459 and 0 maps to 0.0.
460 The resulting floating-point depth value is then multiplied
461 by <constant>GL_DEPTH_SCALE</constant> and added to <constant>GL_DEPTH_BIAS</constant>.
462 The result is clamped to the range
463 <inlineequation><mml:math>
464 <!-- eqn: [0,1]:-->
465 <mml:mfenced open="[" close="]">
466 <mml:mn>0</mml:mn>
467 <mml:mn>1</mml:mn>
468 </mml:mfenced>
469 </mml:math></inlineequation>.
470 </para>
471 <para>
472 The GL then converts the resulting depth components to fragments
473 by attaching the current raster position color or color index and
474 texture coordinates to each pixel,
475 then assigning
476 <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
477 and
478 <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
479 window coordinates to the
480 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
481 fragment such that
482 </para>
483 <para>
484 <informalequation><mml:math>
485 <!-- eqn: x sub n = x sub r + n mod width:-->
486 <mml:mrow>
487 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
488 <mml:mi mathvariant="italic">n</mml:mi>
489 </mml:msub>
490 <mml:mo>=</mml:mo>
491 <mml:mrow>
492 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
493 <mml:mi mathvariant="italic">r</mml:mi>
494 </mml:msub>
495 <mml:mo>+</mml:mo>
496 <mml:mrow>
497 <mml:mi mathvariant="italic">n</mml:mi>
498 <mml:mo>%</mml:mo>
499 <mml:mi mathvariant="italic">width</mml:mi>
500 </mml:mrow>
501 </mml:mrow>
502 </mml:mrow>
503 </mml:math></informalequation>
504 <para>
505 <informalequation><mml:math>
506 <!-- eqn: y sub n = y sub r + \(lf n / width \(rf:-->
507 <mml:mrow>
508 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
509 <mml:mi mathvariant="italic">n</mml:mi>
510 </mml:msub>
511 <mml:mo>=</mml:mo>
512 <mml:mrow>
513 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
514 <mml:mi mathvariant="italic">r</mml:mi>
515 </mml:msub>
516 <mml:mo>+</mml:mo>
517 <mml:mfenced open="&LeftFloor;" close="&RightFloor;">
518 <mml:mfrac>
519 <mml:mi mathvariant="italic">n</mml:mi>
520 <mml:mi mathvariant="italic">width</mml:mi>
521 </mml:mfrac>
522 </mml:mfenced>
523 </mml:mrow>
524 </mml:mrow>
525 </mml:math></informalequation>
526 </para>
527 </para>
528 <para>
529 where
530 <inlineequation><mml:math>
531 <!-- eqn: (x sub r , y sub r):-->
532 <mml:mfenced open="(" close=")">
533 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
534 <mml:mi mathvariant="italic">r</mml:mi>
535 </mml:msub>
536 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
537 <mml:mi mathvariant="italic">r</mml:mi>
538 </mml:msub>
539 </mml:mfenced>
540 </mml:math></inlineequation>
541 is the current raster position.
542 These pixel fragments are then treated just like the fragments generated by
543 rasterizing points, lines, or polygons.
544 Texture mapping,
545 fog,
546 and all the fragment operations are applied before the fragments are written
547 to the frame buffer.
548 </para>
549 </listitem>
550 </varlistentry>
551 <varlistentry>
552 <term><constant>GL_RGBA</constant></term>
553 <listitem>
554 </listitem>
555 </varlistentry>
556 <varlistentry>
557 <term><constant>GL_BGRA</constant></term>
558 <listitem>
559 <para>
560 Each pixel is a four-component group: For <constant>GL_RGBA</constant>, the red
561 component is first, followed by green, followed by blue, followed by
562 alpha; for <constant>GL_BGRA</constant> the order is blue, green, red and then alpha.
563 Floating-point values are converted directly to an internal floating-point
564 format with unspecified precision.
565 Signed integer values are mapped linearly to the internal floating-point
566 format such that the most positive representable integer value maps to 1.0,
567 and the most negative representable value maps to
568 <inlineequation><mml:math>
569 <!-- eqn: -1.0:-->
570 <mml:mn>-1.0</mml:mn>
571 </mml:math></inlineequation>.
572 (Note that
573 this mapping does not convert 0 precisely to 0.0.)
574 Unsigned integer data is mapped similarly:
575 The largest integer value maps to 1.0,
576 and 0 maps to 0.0.
577 The resulting floating-point color values are then multiplied
578 by <constant>GL_c_SCALE</constant> and added to <constant>GL_c_BIAS</constant>,
579 where <emphasis>c</emphasis> is RED, GREEN, BLUE, and ALPHA
580 for the respective color components.
581 The results are clamped to the range
582 <inlineequation><mml:math>
583 <!-- eqn: [0,1]:-->
584 <mml:mfenced open="[" close="]">
585 <mml:mn>0</mml:mn>
586 <mml:mn>1</mml:mn>
587 </mml:mfenced>
588 </mml:math></inlineequation>.
589 </para>
590 <para>
591 If <constant>GL_MAP_COLOR</constant> is true,
592 each color component is scaled by the size of lookup table
593 <constant>GL_PIXEL_MAP_c_TO_c</constant>,
594 then replaced by the value that it references in that table.
595 <emphasis>c</emphasis> is R, G, B, or A respectively.
596 </para>
597 <para>
598 The GL then converts the resulting RGBA colors to fragments
599 by attaching the current raster position <emphasis>z</emphasis> coordinate and
600 texture coordinates to each pixel,
601 then assigning
602 <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
603 and
604 <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
605 window coordinates to the
606 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
607 fragment such that
608 </para>
609 <para>
610 <informalequation><mml:math>
611 <!-- eqn: x sub n = x sub r + n mod width:-->
612 <mml:mrow>
613 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
614 <mml:mi mathvariant="italic">n</mml:mi>
615 </mml:msub>
616 <mml:mo>=</mml:mo>
617 <mml:mrow>
618 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
619 <mml:mi mathvariant="italic">r</mml:mi>
620 </mml:msub>
621 <mml:mo>+</mml:mo>
622 <mml:mrow>
623 <mml:mi mathvariant="italic">n</mml:mi>
624 <mml:mo>%</mml:mo>
625 <mml:mi mathvariant="italic">width</mml:mi>
626 </mml:mrow>
627 </mml:mrow>
628 </mml:mrow>
629 </mml:math></informalequation>
630 <para>
631 <informalequation><mml:math>
632 <!-- eqn: y sub n = y sub r + \(lf n / width \(rf:-->
633 <mml:mrow>
634 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
635 <mml:mi mathvariant="italic">n</mml:mi>
636 </mml:msub>
637 <mml:mo>=</mml:mo>
638 <mml:mrow>
639 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
640 <mml:mi mathvariant="italic">r</mml:mi>
641 </mml:msub>
642 <mml:mo>+</mml:mo>
643 <mml:mfenced open="&LeftFloor;" close="&RightFloor;">
644 <mml:mfrac>
645 <mml:mi mathvariant="italic">n</mml:mi>
646 <mml:mi mathvariant="italic">width</mml:mi>
647 </mml:mfrac>
648 </mml:mfenced>
649 </mml:mrow>
650 </mml:mrow>
651 </mml:math></informalequation>
652 </para>
653 </para>
654 <para>
655 where
656 <inlineequation><mml:math>
657 <!-- eqn: (x sub r , y sub r):-->
658 <mml:mfenced open="(" close=")">
659 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
660 <mml:mi mathvariant="italic">r</mml:mi>
661 </mml:msub>
662 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
663 <mml:mi mathvariant="italic">r</mml:mi>
664 </mml:msub>
665 </mml:mfenced>
666 </mml:math></inlineequation>
667 is the current raster position.
668 These pixel fragments are then treated just like the fragments generated by
669 rasterizing points, lines, or polygons.
670 Texture mapping,
671 fog,
672 and all the fragment operations are applied before the fragments are written
673 to the frame buffer.
674 </para>
675 </listitem>
676 </varlistentry>
677 <varlistentry>
678 <term><constant>GL_RED</constant></term>
679 <listitem>
680 <para>
681 Each pixel is a single red component.
682 This component is converted to the internal floating-point format in
683 the same way the red component of an RGBA pixel is. It is
684 then converted to an RGBA pixel with green and blue set to 0,
685 and alpha set to 1.
686 After this conversion, the pixel is treated as if it had been read
687 as an RGBA pixel.
688 </para>
689 </listitem>
690 </varlistentry>
691 <varlistentry>
692 <term><constant>GL_GREEN</constant></term>
693 <listitem>
694 <para>
695 Each pixel is a single green component.
696 This component is converted to the internal floating-point format in
697 the same way the green component of an RGBA pixel is.
698 It is then converted to an RGBA pixel with red and blue set to 0,
699 and alpha set to 1.
700 After this conversion, the pixel is treated as if it had been read
701 as an RGBA pixel.
702 </para>
703 </listitem>
704 </varlistentry>
705 <varlistentry>
706 <term><constant>GL_BLUE</constant></term>
707 <listitem>
708 <para>
709 Each pixel is a single blue component.
710 This component is converted to the internal floating-point format in
711 the same way the blue component of an RGBA pixel is.
712 It is then converted to an RGBA pixel with red and green set to 0,
713 and alpha set to 1.
714 After this conversion, the pixel is treated as if it had been read
715 as an RGBA pixel.
716 </para>
717 </listitem>
718 </varlistentry>
719 <varlistentry>
720 <term><constant>GL_ALPHA</constant></term>
721 <listitem>
722 <para>
723 Each pixel is a single alpha component.
724 This component is converted to the internal floating-point format in
725 the same way the alpha component of an RGBA pixel is.
726 It is then converted to an RGBA pixel with red, green, and blue set to 0.
727 After this conversion, the pixel is treated as if it had been read
728 as an RGBA pixel.
729 </para>
730 </listitem>
731 </varlistentry>
732 <varlistentry>
733 <term><constant>GL_RGB</constant></term>
734 <listitem>
735 </listitem>
736 </varlistentry>
737 <varlistentry>
738 <term><constant>GL_BGR</constant></term>
739 <listitem>
740 <para>
741 Each pixel is a three-component group:
742 red first, followed by green, followed by blue; for <constant>GL_BGR</constant>, the
743 first component is blue, followed by green and then red.
744 Each component is converted to the internal floating-point format in
745 the same way the red, green, and blue components of an RGBA pixel are.
746 The color triple is converted to an RGBA pixel with alpha set to 1.
747 After this conversion, the pixel is treated as if it had been read
748 as an RGBA pixel.
749 </para>
750 </listitem>
751 </varlistentry>
752 <varlistentry>
753 <term><constant>GL_LUMINANCE</constant></term>
754 <listitem>
755 <para>
756 Each pixel is a single luminance component.
757 This component is converted to the internal floating-point format in
758 the same way the red component of an RGBA pixel is.
759 It is then converted to an RGBA pixel with red, green, and blue set to the
760 converted luminance value,
761 and alpha set to 1.
762 After this conversion, the pixel is treated as if it had been read
763 as an RGBA pixel.
764 </para>
765 </listitem>
766 </varlistentry>
767 <varlistentry>
768 <term><constant>GL_LUMINANCE_ALPHA</constant></term>
769 <listitem>
770 <para>
771 Each pixel is a two-component group:
772 luminance first, followed by alpha.
773 The two components are converted to the internal floating-point format in
774 the same way the red component of an RGBA pixel is.
775 They are then converted to an RGBA pixel with red, green, and blue set to the
776 converted luminance value,
777 and alpha set to the converted alpha value.
778 After this conversion, the pixel is treated as if it had been read
779 as an RGBA pixel.
780
781 </para>
782 </listitem>
783 </varlistentry>
784 </variablelist>
785
786 <para>
787 The following table summarizes the meaning of the valid constants for the
788 <emphasis>type</emphasis> parameter:
789 </para>
790 <para>
791 <informaltable frame="topbot">
792 <tgroup cols="2" align="left">
793 <colspec colwidth="1*" />
794 <colspec colwidth="1*" />
795 <thead>
796 <row>
797 <entry rowsep="1" align="left"><emphasis role="bold">
798 Type
799 </emphasis></entry>
800 <entry rowsep="1" align="left"><emphasis role="bold">
801 Corresponding Type
802 </emphasis></entry>
803 </row>
804 </thead>
805 <tbody>
806 <row>
807 <entry align="left">
808 <constant>GL_UNSIGNED_BYTE</constant>
809 </entry>
810 <entry align="left">
811 unsigned 8-bit integer
812 </entry>
813 </row>
814 <row>
815 <entry align="left">
816 <constant>GL_BYTE</constant>
817 </entry>
818 <entry align="left">
819 signed 8-bit integer
820 </entry>
821 </row>
822 <row>
823 <entry align="left">
824 <constant>GL_BITMAP</constant>
825 </entry>
826 <entry align="left">
827 single bits in unsigned 8-bit integers
828 </entry>
829 </row>
830 <row>
831 <entry align="left">
832 <constant>GL_UNSIGNED_SHORT</constant>
833 </entry>
834 <entry align="left">
835 unsigned 16-bit integer
836 </entry>
837 </row>
838 <row>
839 <entry align="left">
840 <constant>GL_SHORT</constant>
841 </entry>
842 <entry align="left">
843 signed 16-bit integer
844 </entry>
845 </row>
846 <row>
847 <entry align="left">
848 <constant>GL_UNSIGNED_INT</constant>
849 </entry>
850 <entry align="left">
851 unsigned 32-bit integer
852 </entry>
853 </row>
854 <row>
855 <entry align="left">
856 <constant>GL_INT</constant>
857 </entry>
858 <entry align="left">
859 32-bit integer
860 </entry>
861 </row>
862 <row>
863 <entry align="left">
864 <constant>GL_FLOAT</constant>
865 </entry>
866 <entry align="left">
867 single-precision floating-point
868 </entry>
869 </row>
870 <row>
871 <entry align="left">
872 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>
873 </entry>
874 <entry align="left">
875 unsigned 8-bit integer
876 </entry>
877 </row>
878 <row>
879 <entry align="left">
880 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>
881 </entry>
882 <entry align="left">
883 unsigned 8-bit integer with reversed component ordering
884 </entry>
885 </row>
886 <row>
887 <entry align="left">
888 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>
889 </entry>
890 <entry align="left">
891 unsigned 16-bit integer
892 </entry>
893 </row>
894 <row>
895 <entry align="left">
896 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
897 </entry>
898 <entry align="left">
899 unsigned 16-bit integer with reversed component ordering
900 </entry>
901 </row>
902 <row>
903 <entry align="left">
904 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>
905 </entry>
906 <entry align="left">
907 unsigned 16-bit integer
908 </entry>
909 </row>
910 <row>
911 <entry align="left">
912 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>
913 </entry>
914 <entry align="left">
915 unsigned 16-bit integer with reversed component ordering
916 </entry>
917 </row>
918 <row>
919 <entry align="left">
920 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>
921 </entry>
922 <entry align="left">
923 unsigned 16-bit integer
924 </entry>
925 </row>
926 <row>
927 <entry align="left">
928 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>
929 </entry>
930 <entry align="left">
931 unsigned 16-bit integer with reversed component ordering
932 </entry>
933 </row>
934 <row>
935 <entry align="left">
936 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>
937 </entry>
938 <entry align="left">
939 unsigned 32-bit integer
940 </entry>
941 </row>
942 <row>
943 <entry align="left">
944 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>
945 </entry>
946 <entry align="left">
947 unsigned 32-bit integer with reversed component ordering
948 </entry>
949 </row>
950 <row>
951 <entry align="left">
952 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>
953 </entry>
954 <entry align="left">
955 unsigned 32-bit integer
956 </entry>
957 </row>
958 <row>
959 <entry align="left">
960 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
961 </entry>
962 <entry align="left">
963 unsigned 32-bit integer with reversed component ordering
964 </entry>
965 </row>
966 </tbody>
967 </tgroup>
968 </informaltable>
969 </para>
970 <para>
971 </para>
972 <!--/listitem-->
973 <!--/varlistentry-->
974 <!--/variablelist-->
975 <para>
976 The rasterization described so far assumes pixel zoom factors of 1.
977 If
978 <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry> is used to change the
979 <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
980 and
981 <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
982 pixel zoom factors,
983 pixels are converted to fragments as follows.
984 If
985 <inlineequation><mml:math>
986 <!-- eqn: (x sub r, y sub r):-->
987 <mml:mfenced open="(" close=")">
988 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
989 <mml:mi mathvariant="italic">r</mml:mi>
990 </mml:msub>
991 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
992 <mml:mi mathvariant="italic">r</mml:mi>
993 </mml:msub>
994 </mml:mfenced>
995 </mml:math></inlineequation>
996 is the current raster position,
997 and a given pixel is in the
998 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
999 column and
1000 <inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>th
1001 row
1002 of the pixel rectangle,
1003 then fragments are generated for pixels whose centers are in the rectangle
1004 with corners at
1005 </para>
1006 <para>
1007 <informalequation><mml:math>
1008 <!-- eqn: left ( x sub r + {zoom sub x} n, y sub r + {zoom sub y} m right ):-->
1009 <mml:mfenced open="(" close=")">
1010 <mml:mrow>
1011 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
1012 <mml:mi mathvariant="italic">r</mml:mi>
1013 </mml:msub>
1014 <mml:mo>+</mml:mo>
1015 <mml:mfenced open="" close="">
1016 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1017 <mml:mi mathvariant="italic">x</mml:mi>
1018 </mml:msub>
1019 </mml:mfenced>
1020 <mml:mo>&it;</mml:mo>
1021 <mml:mi mathvariant="italic">n</mml:mi>
1022 </mml:mrow>
1023 <mml:mrow>
1024 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
1025 <mml:mi mathvariant="italic">r</mml:mi>
1026 </mml:msub>
1027 <mml:mo>+</mml:mo>
1028 <mml:mfenced open="" close="">
1029 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1030 <mml:mi mathvariant="italic">y</mml:mi>
1031 </mml:msub>
1032 </mml:mfenced>
1033 <mml:mo>&it;</mml:mo>
1034 <mml:mi mathvariant="italic">m</mml:mi>
1035 </mml:mrow>
1036 </mml:mfenced>
1037 </mml:math></informalequation>
1038 <para>
1039 <informalequation><mml:math>
1040 <!-- eqn: left ( x sub r + {zoom sub x} (n + 1), y sub r + {zoom sub y} ( m + 1 ) right ):-->
1041 <mml:mfenced open="(" close=")">
1042 <mml:mrow>
1043 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
1044 <mml:mi mathvariant="italic">r</mml:mi>
1045 </mml:msub>
1046 <mml:mo>+</mml:mo>
1047 <mml:mrow>
1048 <mml:mfenced open="" close="">
1049 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1050 <mml:mi mathvariant="italic">x</mml:mi>
1051 </mml:msub>
1052 </mml:mfenced>
1053 <mml:mo>&af;</mml:mo>
1054 <mml:mfenced open="(" close=")">
1055 <mml:mrow>
1056 <mml:mi mathvariant="italic">n</mml:mi>
1057 <mml:mo>+</mml:mo>
1058 <mml:mn>1</mml:mn>
1059 </mml:mrow>
1060 </mml:mfenced>
1061 </mml:mrow>
1062 </mml:mrow>
1063 <mml:mrow>
1064 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
1065 <mml:mi mathvariant="italic">r</mml:mi>
1066 </mml:msub>
1067 <mml:mo>+</mml:mo>
1068 <mml:mrow>
1069 <mml:mfenced open="" close="">
1070 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1071 <mml:mi mathvariant="italic">y</mml:mi>
1072 </mml:msub>
1073 </mml:mfenced>
1074 <mml:mo>&af;</mml:mo>
1075 <mml:mfenced open="(" close=")">
1076 <mml:mrow>
1077 <mml:mi mathvariant="italic">m</mml:mi>
1078 <mml:mo>+</mml:mo>
1079 <mml:mn>1</mml:mn>
1080 </mml:mrow>
1081 </mml:mfenced>
1082 </mml:mrow>
1083 </mml:mrow>
1084 </mml:mfenced>
1085 </mml:math></informalequation>
1086 </para>
1087 </para>
1088 <para>
1089 where
1090 <inlineequation><mml:math>
1091 <!-- eqn: zoom sub x:-->
1092 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1093 <mml:mi mathvariant="italic">x</mml:mi>
1094 </mml:msub>
1095 </mml:math></inlineequation>
1096 is the value of <constant>GL_ZOOM_X</constant> and
1097 <inlineequation><mml:math>
1098 <!-- eqn: zoom sub y:-->
1099 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
1100 <mml:mi mathvariant="italic">y</mml:mi>
1101 </mml:msub>
1102 </mml:math></inlineequation>
1103 is the value of <constant>GL_ZOOM_Y</constant>.
1104 </para>
1105 </refsect1>
1106 <refsect1 id="notes"><title>Notes</title>
1107 <para>
1108 <constant>GL_BGR</constant> and <constant>GL_BGRA</constant> are only valid for <parameter>format</parameter> if the GL
1109 version is 1.2 or greater.
1110 </para>
1111 <para>
1112 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
1113 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
1114 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
1115 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
1116 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
1117 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
1118 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
1119 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
1120 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
1121 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
1122 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
1123 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are only valid for <parameter>type</parameter> if the
1124 GL version is 1.2 or greater.
1125 </para>
1126 </refsect1>
1127 <refsect1 id="errors"><title>Errors</title>
1128 <para>
1129 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> or <parameter>type</parameter> is not one of
1130 the accepted values.
1131 </para>
1132 <para>
1133 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and
1134 <parameter>format</parameter> is not either <constant>GL_COLOR_INDEX</constant> or <constant>GL_STENCIL_INDEX</constant>.
1135 </para>
1136 <para>
1137 <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
1138 </para>
1139 <para>
1140 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_STENCIL_INDEX</constant>
1141 and there is no stencil buffer.
1142 </para>
1143 <para>
1144 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is
1145 <constant>GL_RED</constant>,
1146 <constant>GL_GREEN</constant>,
1147 <constant>GL_BLUE</constant>,
1148 <constant>GL_ALPHA</constant>,
1149 <constant>GL_RGB</constant>,
1150 <constant>GL_RGBA</constant>,
1151 <constant>GL_BGR</constant>,
1152 <constant>GL_BGRA</constant>,
1153 <constant>GL_LUMINANCE</constant>,
1154 or
1155 <constant>GL_LUMINANCE_ALPHA</constant>,
1156 and the GL is in color index mode.
1157 </para>
1158 <para>
1159 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is one of
1160 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
1161 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
1162 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
1163 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
1164 and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
1165 </para>
1166 <para>
1167 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is one of
1168 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
1169 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
1170 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
1171 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
1172 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
1173 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
1174 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
1175 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
1176 and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
1177 </para>
1178 <para>
1179 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1180 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
1181 </para>
1182 <para>
1183 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1184 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
1185 object such that the memory reads required would exceed the data store size.
1186 </para>
1187 <para>
1188 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1189 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
1190 into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
1191 </para>
1192 <para>
1193 <constant>GL_INVALID_OPERATION</constant> is generated if <function>glDrawPixels</function>
1194 is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
1195 and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
1196 </para>
1197 </refsect1>
1198 <refsect1 id="associatedgets"><title>Associated Gets</title>
1199 <para>
1200 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
1201 </para>
1202 <para>
1203 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
1204 </para>
1205 <para>
1206 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
1207 </para>
1208 </refsect1>
1209 <refsect1 id="seealso"><title>See Also</title>
1210 <para>
1211 <citerefentry><refentrytitle>glAlphaFunc</refentrytitle></citerefentry>,
1212 <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
1213 <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
1214 <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
1215 <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
1216 <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>,
1217 <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
1218 <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
1219 <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>,
1220 <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>,
1221 <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
1222 <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
1223 <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
1224 <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>
1225 </para>
1226 </refsect1>
1227 <refsect1 id="Copyright"><title>Copyright</title>
1228 <para>
1229 Copyright <trademark class="copyright"></trademark> 1991-2006
1230 Silicon Graphics, Inc. This document is licensed under the SGI
1231 Free Software B License. For details, see
1232 <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
1233 </para>
1234 </refsect1>
1235 </refentry>
Unnamed repository; edit this file 'description' to name the repository.