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=
"glPixelMap">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glPixelMap
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glPixelMap
</refname>
17 <refpurpose>set up pixel transfer maps
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glPixelMapfv
</function></funcdef>
23 <paramdef>GLenum
<parameter>map
</parameter></paramdef>
24 <paramdef>GLsizei
<parameter>mapsize
</parameter></paramdef>
25 <paramdef>const GLfloat *
<parameter>values
</parameter></paramdef>
30 <funcdef>void
<function>glPixelMapuiv
</function></funcdef>
31 <paramdef>GLenum
<parameter>map
</parameter></paramdef>
32 <paramdef>GLsizei
<parameter>mapsize
</parameter></paramdef>
33 <paramdef>const GLuint *
<parameter>values
</parameter></paramdef>
38 <funcdef>void
<function>glPixelMapusv
</function></funcdef>
39 <paramdef>GLenum
<parameter>map
</parameter></paramdef>
40 <paramdef>GLsizei
<parameter>mapsize
</parameter></paramdef>
41 <paramdef>const GLushort *
<parameter>values
</parameter></paramdef>
45 <!-- eqn: ignoring delim $$ -->
46 <refsect1 id=
"parameters"><title>Parameters
</title>
49 <term><parameter>map
</parameter></term>
52 Specifies a symbolic map name.
53 Must be one of the following:
54 <constant>GL_PIXEL_MAP_I_TO_I
</constant>,
55 <constant>GL_PIXEL_MAP_S_TO_S
</constant>,
56 <constant>GL_PIXEL_MAP_I_TO_R
</constant>,
57 <constant>GL_PIXEL_MAP_I_TO_G
</constant>,
58 <constant>GL_PIXEL_MAP_I_TO_B
</constant>,
59 <constant>GL_PIXEL_MAP_I_TO_A
</constant>,
60 <constant>GL_PIXEL_MAP_R_TO_R
</constant>,
61 <constant>GL_PIXEL_MAP_G_TO_G
</constant>,
62 <constant>GL_PIXEL_MAP_B_TO_B
</constant>, or
63 <constant>GL_PIXEL_MAP_A_TO_A
</constant>.
68 <term><parameter>mapsize
</parameter></term>
71 Specifies the size of the map being defined.
76 <term><parameter>values
</parameter></term>
79 Specifies an array of
<parameter>mapsize
</parameter> values.
85 <refsect1 id=
"description"><title>Description
</title>
87 <function>glPixelMap
</function> sets up translation tables,
88 or
<emphasis>maps
</emphasis>,
90 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
91 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
92 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
93 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
94 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
95 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
96 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
97 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>,
98 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
99 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
100 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
101 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
102 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>, and
103 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>.
104 Additionally, if the
<code>ARB_imaging
</code> subset is supported, the
106 <citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>,
107 <citerefentry><refentrytitle>glColorSubTable
</refentrytitle></citerefentry>,
108 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
109 <citerefentry><refentrytitle>glConvolutionFilter2D
</refentrytitle></citerefentry>,
110 <citerefentry><refentrytitle>glHistogram
</refentrytitle></citerefentry>,
111 <citerefentry><refentrytitle>glMinmax
</refentrytitle></citerefentry>, and
112 <citerefentry><refentrytitle>glSeparableFilter2D
</refentrytitle></citerefentry>.
113 Use of these maps is described completely in the
114 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry> reference page,
115 and partly in the reference pages for the pixel and texture image commands.
116 Only the specification of the maps is described in this reference page.
119 <parameter>map
</parameter> is a symbolic map name,
120 indicating one of ten maps to set.
121 <parameter>mapsize
</parameter> specifies the number of entries in the map,
122 and
<parameter>values
</parameter> is a pointer to an array of
<parameter>mapsize
</parameter> map values.
125 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
126 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a pixel transfer map is
127 specified,
<parameter>values
</parameter> is treated as a byte offset into the buffer object's data store.
130 The ten maps are as follows:
134 <term><constant>GL_PIXEL_MAP_I_TO_I
</constant></term>
137 Maps color indices to color indices.
142 <term><constant>GL_PIXEL_MAP_S_TO_S
</constant></term>
145 Maps stencil indices to stencil indices.
150 <term><constant>GL_PIXEL_MAP_I_TO_R
</constant></term>
153 Maps color indices to red components.
158 <term><constant>GL_PIXEL_MAP_I_TO_G
</constant></term>
161 Maps color indices to green components.
166 <term><constant>GL_PIXEL_MAP_I_TO_B
</constant></term>
169 Maps color indices to blue components.
174 <term><constant>GL_PIXEL_MAP_I_TO_A
</constant></term>
177 Maps color indices to alpha components.
182 <term><constant>GL_PIXEL_MAP_R_TO_R
</constant></term>
185 Maps red components to red components.
190 <term><constant>GL_PIXEL_MAP_G_TO_G
</constant></term>
193 Maps green components to green components.
198 <term><constant>GL_PIXEL_MAP_B_TO_B
</constant></term>
201 Maps blue components to blue components.
206 <term><constant>GL_PIXEL_MAP_A_TO_A
</constant></term>
209 Maps alpha components to alpha components.
215 The entries in a map can be specified as single-precision
216 floating-point numbers,
217 unsigned short integers,
218 or unsigned int integers.
219 Maps that store color component values
220 (all but
<constant>GL_PIXEL_MAP_I_TO_I
</constant> and
<constant>GL_PIXEL_MAP_S_TO_S
</constant>)
221 retain their values in floating-point format,
222 with unspecified mantissa and exponent sizes.
223 Floating-point values specified by
<function>glPixelMapfv
</function> are converted directly
224 to the internal floating-point format of these maps,
225 then clamped to the range [
0,
1].
226 Unsigned integer values specified by
<function>glPixelMapusv
</function> and
227 <function>glPixelMapuiv
</function> are converted linearly such that
228 the largest representable integer maps to
1.0,
232 Maps that store indices,
233 <constant>GL_PIXEL_MAP_I_TO_I
</constant> and
<constant>GL_PIXEL_MAP_S_TO_S
</constant>,
234 retain their values in fixed-point format,
235 with an unspecified number of bits to the right of the binary point.
236 Floating-point values specified by
<function>glPixelMapfv
</function> are converted directly
237 to the internal fixed-point format of these maps.
238 Unsigned integer values specified by
<function>glPixelMapusv
</function> and
239 <function>glPixelMapuiv
</function> specify integer values,
240 with all
0's to the right of the binary point.
243 The following table shows the initial sizes and values for each of the maps.
244 Maps that are indexed by either color or stencil indices must have
245 <parameter>mapsize
</parameter> =
246 <inlineequation><mml:math>
247 <!-- eqn: 2 sup n:-->
248 <mml:msup><mml:mn>2</mml:mn>
249 <mml:mi mathvariant=
"italic">n
</mml:mi>
251 </mml:math></inlineequation>
253 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
254 or the results are undefined.
255 The maximum allowable size for each map depends on the implementation
256 and can be determined by calling
<citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
257 <constant>GL_MAX_PIXEL_MAP_TABLE
</constant>.
258 The single maximum applies to all maps; it is at
261 <informaltable frame=
"topbot">
262 <tgroup cols=
"5" align=
"left">
263 <colspec colwidth=
"4*" />
264 <colspec colwidth=
"2*" align=
"center"/>
265 <colspec colwidth=
"2*" align=
"center"/>
266 <colspec colwidth=
"1*" align=
"center"/>
267 <colspec colwidth=
"1*" align=
"center"/>
270 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
271 <parameter>map
</parameter>
273 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
276 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
279 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
282 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
290 <constant>GL_PIXEL_MAP_I_TO_I
</constant>
292 <entry align=
"center">
295 <entry align=
"center">
298 <entry align=
"center">
301 <entry align=
"center">
307 <constant>GL_PIXEL_MAP_S_TO_S
</constant>
309 <entry align=
"center">
312 <entry align=
"center">
315 <entry align=
"center">
318 <entry align=
"center">
324 <constant>GL_PIXEL_MAP_I_TO_R
</constant>
326 <entry align=
"center">
329 <entry align=
"center">
332 <entry align=
"center">
335 <entry align=
"center">
341 <constant>GL_PIXEL_MAP_I_TO_G
</constant>
343 <entry align=
"center">
346 <entry align=
"center">
349 <entry align=
"center">
352 <entry align=
"center">
358 <constant>GL_PIXEL_MAP_I_TO_B
</constant>
360 <entry align=
"center">
363 <entry align=
"center">
366 <entry align=
"center">
369 <entry align=
"center">
375 <constant>GL_PIXEL_MAP_I_TO_A
</constant>
377 <entry align=
"center">
380 <entry align=
"center">
383 <entry align=
"center">
386 <entry align=
"center">
392 <constant>GL_PIXEL_MAP_R_TO_R
</constant>
394 <entry align=
"center">
397 <entry align=
"center">
400 <entry align=
"center">
403 <entry align=
"center">
409 <constant>GL_PIXEL_MAP_G_TO_G
</constant>
411 <entry align=
"center">
414 <entry align=
"center">
417 <entry align=
"center">
420 <entry align=
"center">
426 <constant>GL_PIXEL_MAP_B_TO_B
</constant>
428 <entry align=
"center">
431 <entry align=
"center">
434 <entry align=
"center">
437 <entry align=
"center">
443 <constant>GL_PIXEL_MAP_A_TO_A
</constant>
445 <entry align=
"center">
448 <entry align=
"center">
451 <entry align=
"center">
454 <entry align=
"center">
462 <refsect1 id=
"errors"><title>Errors
</title>
464 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>map
</parameter> is not an accepted value.
467 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>mapsize
</parameter> is less than one
468 or larger than
<constant>GL_MAX_PIXEL_MAP_TABLE
</constant>.
471 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>map
</parameter> is
472 <constant>GL_PIXEL_MAP_I_TO_I
</constant>,
473 <constant>GL_PIXEL_MAP_S_TO_S
</constant>,
474 <constant>GL_PIXEL_MAP_I_TO_R
</constant>,
475 <constant>GL_PIXEL_MAP_I_TO_G
</constant>,
476 <constant>GL_PIXEL_MAP_I_TO_B
</constant>, or
477 <constant>GL_PIXEL_MAP_I_TO_A
</constant>,
478 and
<parameter>mapsize
</parameter> is not a power of two.
481 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
482 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
485 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
486 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
487 object such that the memory reads required would exceed the data store size.
490 <constant>GL_INVALID_OPERATION
</constant> is generated by
<function>glPixelMapfv
</function> if a non-zero buffer object name is bound to the
491 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>values
</parameter> is not evenly divisible
492 into the number of bytes needed to store in memory a GLfloat datum.
495 <constant>GL_INVALID_OPERATION
</constant> is generated by
<function>glPixelMapuiv
</function> if a non-zero buffer object name is bound to the
496 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>values
</parameter> is not evenly divisible
497 into the number of bytes needed to store in memory a GLuint datum.
500 <constant>GL_INVALID_OPERATION
</constant> is generated by
<function>glPixelMapusv
</function> if a non-zero buffer object name is bound to the
501 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>values
</parameter> is not evenly divisible
502 into the number of bytes needed to store in memory a GLushort datum.
505 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glPixelMap
</function>
506 is executed between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
507 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
510 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
512 <citerefentry><refentrytitle>glGetPixelMap
</refentrytitle></citerefentry>
515 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_I_TO_I_SIZE
</constant>
518 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_S_TO_S_SIZE
</constant>
521 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_I_TO_R_SIZE
</constant>
524 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_I_TO_G_SIZE
</constant>
527 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_I_TO_B_SIZE
</constant>
530 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_I_TO_A_SIZE
</constant>
533 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_R_TO_R_SIZE
</constant>
536 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_G_TO_G_SIZE
</constant>
539 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_B_TO_B_SIZE
</constant>
542 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_MAP_A_TO_A_SIZE
</constant>
545 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_PIXEL_MAP_TABLE
</constant>
548 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
551 <refsect1 id=
"seealso"><title>See Also
</title>
553 <citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>,
554 <citerefentry><refentrytitle>glColorSubTable
</refentrytitle></citerefentry>,
555 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
556 <citerefentry><refentrytitle>glConvolutionFilter2D
</refentrytitle></citerefentry>,
557 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
558 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
559 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
560 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
561 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
562 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
563 <citerefentry><refentrytitle>glHistogram
</refentrytitle></citerefentry>,
564 <citerefentry><refentrytitle>glMinmax
</refentrytitle></citerefentry>,
565 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
566 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
567 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>,
568 <citerefentry><refentrytitle>glSeparableFilter2D
</refentrytitle></citerefentry>,
569 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
570 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
571 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
572 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
573 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
574 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
577 <refsect1 id=
"Copyright"><title>Copyright
</title>
579 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
580 Silicon Graphics, Inc. This document is licensed under the SGI
581 Free Software B License. For details, see
582 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.