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=
"glPixelStore">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glPixelStore
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glPixelStore
</refname>
17 <refpurpose>set pixel storage modes
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glPixelStoref
</function></funcdef>
23 <paramdef>GLenum
<parameter>pname
</parameter></paramdef>
24 <paramdef>GLfloat
<parameter>param
</parameter></paramdef>
29 <funcdef>void
<function>glPixelStorei
</function></funcdef>
30 <paramdef>GLenum
<parameter>pname
</parameter></paramdef>
31 <paramdef>GLint
<parameter>param
</parameter></paramdef>
35 <!-- eqn: ignoring delim $$ -->
36 <refsect1 id=
"parameters"><title>Parameters
</title>
39 <term><parameter>pname
</parameter></term>
42 Specifies the symbolic name of the parameter to be set.
43 Six values affect the packing of pixel data into memory:
44 <constant>GL_PACK_SWAP_BYTES
</constant>,
45 <constant>GL_PACK_LSB_FIRST
</constant>,
46 <constant>GL_PACK_ROW_LENGTH
</constant>,
47 <constant>GL_PACK_IMAGE_HEIGHT
</constant>,
48 <constant>GL_PACK_SKIP_PIXELS
</constant>,
49 <constant>GL_PACK_SKIP_ROWS
</constant>,
50 <constant>GL_PACK_SKIP_IMAGES
</constant>, and
51 <constant>GL_PACK_ALIGNMENT
</constant>.
52 Six more affect the unpacking of pixel data
<emphasis>from
</emphasis> memory:
53 <constant>GL_UNPACK_SWAP_BYTES
</constant>,
54 <constant>GL_UNPACK_LSB_FIRST
</constant>,
55 <constant>GL_UNPACK_ROW_LENGTH
</constant>,
56 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant>,
57 <constant>GL_UNPACK_SKIP_PIXELS
</constant>,
58 <constant>GL_UNPACK_SKIP_ROWS
</constant>,
59 <constant>GL_UNPACK_SKIP_IMAGES
</constant>, and
60 <constant>GL_UNPACK_ALIGNMENT
</constant>.
65 <term><parameter>param
</parameter></term>
68 Specifies the value that
<parameter>pname
</parameter> is set to.
74 <refsect1 id=
"description"><title>Description
</title>
76 <function>glPixelStore
</function> sets pixel storage modes that affect the operation of subsequent
77 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry> as well as the unpacking of
78 texture patterns (see
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
79 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
80 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>).
83 <parameter>pname
</parameter> is a symbolic constant indicating the parameter to be set, and
84 <parameter>param
</parameter> is the new value. Six of the twelve storage parameters affect
85 how pixel data is returned to client memory.
90 <term><constant>GL_PACK_SWAP_BYTES
</constant></term>
94 byte ordering for multibyte color components,
99 if a four-byte component consists of bytes
100 <inlineequation><mml:math>
101 <!-- eqn: b sub 0: -->
102 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
105 </mml:math></inlineequation>,
106 <inlineequation><mml:math>
107 <!-- eqn: b sub 1: -->
108 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
111 </mml:math></inlineequation>,
112 <inlineequation><mml:math>
113 <!-- eqn: b sub 2: -->
114 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
117 </mml:math></inlineequation>,
118 <inlineequation><mml:math>
119 <!-- eqn: b sub 3: -->
120 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
123 </mml:math></inlineequation>,
124 it is stored in memory as
125 <inlineequation><mml:math>
126 <!-- eqn: b sub 3: -->
127 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
130 </mml:math></inlineequation>,
131 <inlineequation><mml:math>
132 <!-- eqn: b sub 2: -->
133 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
136 </mml:math></inlineequation>,
137 <inlineequation><mml:math>
138 <!-- eqn: b sub 1: -->
139 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
142 </mml:math></inlineequation>,
143 <inlineequation><mml:math>
144 <!-- eqn: b sub 0: -->
145 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
148 </mml:math></inlineequation>
149 if
<constant>GL_PACK_SWAP_BYTES
</constant> is true.
150 <constant>GL_PACK_SWAP_BYTES
</constant> has no effect on the memory order of components
152 only on the order of bytes within components or indices.
154 the three components of a
<constant>GL_RGB
</constant> format pixel are always stored with
158 regardless of the value of
<constant>GL_PACK_SWAP_BYTES
</constant>.
163 <term><constant>GL_PACK_LSB_FIRST
</constant></term>
167 bits are ordered within a byte from least significant to most significant;
169 the first bit in each byte is the most significant one.
174 <term><constant>GL_PACK_ROW_LENGTH
</constant></term>
178 <constant>GL_PACK_ROW_LENGTH
</constant> defines the number of pixels in a row.
179 If the first pixel of a row is placed at location
180 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
182 then the location of the first pixel of the next row is obtained by skipping
185 <informalequation><mml:math>
186 <!-- eqn: k = left { lpile { n l above {a over s} left ceiling { s n l } over a right ceiling} lpile {s >= a above s < a }: -->
188 <mml:mi mathvariant=
"italic">k
</mml:mi>
190 <mml:mfenced open=
"{" close=
"">
195 <mml:mi mathvariant=
"italic">n
</mml:mi>
196 <mml:mo>⁢</mml:mo>
197 <mml:mi mathvariant=
"italic">l
</mml:mi>
202 <mml:mfenced open=
"" close=
"">
204 <mml:mi mathvariant=
"italic">a
</mml:mi>
205 <mml:mi mathvariant=
"italic">s
</mml:mi>
208 <mml:mo>⁢</mml:mo>
209 <mml:mfenced open=
"⌈" close=
"⌉">
211 <mml:mfenced open=
"" close=
"">
213 <mml:mi mathvariant=
"italic">s
</mml:mi>
214 <mml:mo>⁢</mml:mo>
215 <mml:mi mathvariant=
"italic">n
</mml:mi>
216 <mml:mo>⁢</mml:mo>
217 <mml:mi mathvariant=
"italic">l
</mml:mi>
220 <mml:mi mathvariant=
"italic">a
</mml:mi>
226 <mml:mo>⁢</mml:mo>
230 <mml:mi mathvariant=
"italic">s
</mml:mi>
231 <mml:mo>>=
</mml:mo>
232 <mml:mi mathvariant=
"italic">a
</mml:mi>
237 <mml:mi mathvariant=
"italic">s
</mml:mi>
238 <mml:mo><</mml:mo>
239 <mml:mi mathvariant=
"italic">a
</mml:mi>
246 </mml:math></informalequation>
249 components or indices,
251 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
252 is the number of components or indices in a pixel,
253 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
254 is the number of pixels in a row
255 (
<constant>GL_PACK_ROW_LENGTH
</constant> if it is greater than
0,
257 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
258 argument to the pixel routine otherwise),
259 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
260 is the value of
<constant>GL_PACK_ALIGNMENT
</constant>, and
261 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
262 is the size, in bytes, of a single component
264 <inlineequation><mml:math>
267 <mml:mi mathvariant=
"italic">a
</mml:mi>
268 <mml:mo><</mml:mo>
269 <mml:mi mathvariant=
"italic">s
</mml:mi>
271 </mml:math></inlineequation>,
273 <inlineequation><mml:math>
276 <mml:mi mathvariant=
"italic">a
</mml:mi>
278 <mml:mi mathvariant=
"italic">s
</mml:mi>
280 </mml:math></inlineequation>).
281 In the case of
1-bit values,
282 the location of the next row is obtained by skipping
285 <inlineequation><mml:math>
286 <!-- eqn: k = 8 a left ceiling { n l } over { 8 a } right ceiling: -->
288 <mml:mi mathvariant=
"italic">k
</mml:mi>
292 <mml:mo>⁢</mml:mo>
293 <mml:mi mathvariant=
"italic">a
</mml:mi>
294 <mml:mo>⁢</mml:mo>
295 <mml:mfenced open=
"⌈" close=
"⌉">
297 <mml:mfenced open=
"" close=
"">
299 <mml:mi mathvariant=
"italic">n
</mml:mi>
300 <mml:mo>⁢</mml:mo>
301 <mml:mi mathvariant=
"italic">l
</mml:mi>
304 <mml:mfenced open=
"" close=
"">
307 <mml:mo>⁢</mml:mo>
308 <mml:mi mathvariant=
"italic">a
</mml:mi>
315 </mml:math></inlineequation>
318 components or indices.
321 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
327 Storage format
<constant>GL_RGB
</constant>,
329 has three components per pixel:
337 <term><constant>GL_PACK_IMAGE_HEIGHT
</constant></term>
341 <constant>GL_PACK_IMAGE_HEIGHT
</constant> defines the number of pixels in an image
342 three-dimensional texture volume, where ``image'' is defined by all pixels
343 sharing the same third dimension index.
344 If the first pixel of a row is placed at location
345 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
347 then the location of the first pixel of the next row is obtained by skipping
350 <informalequation><mml:math>
351 <!-- eqn: k = left { lpile { n l h above {a over s} left ceiling { s n l h } over a right ceiling} lpile {s >= a above s < a }: -->
353 <mml:mi mathvariant=
"italic">k
</mml:mi>
355 <mml:mfenced open=
"{" close=
"">
360 <mml:mi mathvariant=
"italic">n
</mml:mi>
361 <mml:mo>⁢</mml:mo>
362 <mml:mi mathvariant=
"italic">l
</mml:mi>
363 <mml:mo>⁢</mml:mo>
364 <mml:mi mathvariant=
"italic">h
</mml:mi>
369 <mml:mfenced open=
"" close=
"">
371 <mml:mi mathvariant=
"italic">a
</mml:mi>
372 <mml:mi mathvariant=
"italic">s
</mml:mi>
375 <mml:mo>⁢</mml:mo>
376 <mml:mfenced open=
"⌈" close=
"⌉">
378 <mml:mfenced open=
"" close=
"">
380 <mml:mi mathvariant=
"italic">s
</mml:mi>
381 <mml:mo>⁢</mml:mo>
382 <mml:mi mathvariant=
"italic">n
</mml:mi>
383 <mml:mo>⁢</mml:mo>
384 <mml:mi mathvariant=
"italic">l
</mml:mi>
385 <mml:mo>⁢</mml:mo>
386 <mml:mi mathvariant=
"italic">h
</mml:mi>
389 <mml:mi mathvariant=
"italic">a
</mml:mi>
395 <mml:mo>⁢</mml:mo>
399 <mml:mi mathvariant=
"italic">s
</mml:mi>
400 <mml:mo>>=
</mml:mo>
401 <mml:mi mathvariant=
"italic">a
</mml:mi>
406 <mml:mi mathvariant=
"italic">s
</mml:mi>
407 <mml:mo><</mml:mo>
408 <mml:mi mathvariant=
"italic">a
</mml:mi>
415 </mml:math></informalequation>
418 components or indices, where
419 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
420 is the number of components or indices
422 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
423 is the number of pixels in a row
424 (
<constant>GL_PACK_ROW_LENGTH
</constant> if it is greater than
0, the
425 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
426 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
427 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
429 rows in a pixel image (
<constant>GL_PACK_IMAGE_HEIGHT
</constant> if it is greater than
431 <inlineequation><mml:math><mml:mi mathvariant=
"italic">height
</mml:mi></mml:math></inlineequation>
432 argument to the
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> routine otherwise),
433 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
435 <constant>GL_PACK_ALIGNMENT
</constant>, and
436 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
437 is the size, in bytes, of a single
439 <inlineequation><mml:math>
442 <mml:mi mathvariant=
"italic">a
</mml:mi>
443 <mml:mo><</mml:mo>
444 <mml:mi mathvariant=
"italic">s
</mml:mi>
446 </mml:math></inlineequation>,
448 <inlineequation><mml:math>
451 <mml:mi mathvariant=
"italic">a
</mml:mi>
453 <mml:mi mathvariant=
"italic">s
</mml:mi>
455 </mml:math></inlineequation>).
458 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
464 Storage format
<constant>GL_RGB
</constant>,
466 has three components per pixel:
474 <term><constant>GL_PACK_SKIP_PIXELS
</constant>,
<constant>GL_PACK_SKIP_ROWS
</constant>, and
<constant>GL_PACK_SKIP_IMAGES
</constant></term>
477 These values are provided as a convenience to the programmer;
478 they provide no functionality that cannot be duplicated simply by
479 incrementing the pointer passed to
<citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>.
480 Setting
<constant>GL_PACK_SKIP_PIXELS
</constant> to
481 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
482 is equivalent to incrementing
484 <inlineequation><mml:math>
487 <mml:mi mathvariant=
"italic">i
</mml:mi>
488 <mml:mo>⁢</mml:mo>
489 <mml:mi mathvariant=
"italic">n
</mml:mi>
491 </mml:math></inlineequation>
492 components or indices,
494 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
495 is the number of components or indices in each pixel.
496 Setting
<constant>GL_PACK_SKIP_ROWS
</constant> to
497 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>
498 is equivalent to incrementing
500 <inlineequation><mml:math>
503 <mml:mi mathvariant=
"italic">j
</mml:mi>
504 <mml:mo>⁢</mml:mo>
505 <mml:mi mathvariant=
"italic">m
</mml:mi>
507 </mml:math></inlineequation>
508 components or indices,
510 <inlineequation><mml:math><mml:mi mathvariant=
"italic">m
</mml:mi></mml:math></inlineequation>
511 is the number of components or indices per row,
512 as just computed in the
<constant>GL_PACK_ROW_LENGTH
</constant> section.
513 Setting
<constant>GL_PACK_SKIP_IMAGES
</constant> to
514 <inlineequation><mml:math><mml:mi mathvariant=
"italic">k
</mml:mi></mml:math></inlineequation>
515 is equivalent to incrementing
517 <inlineequation><mml:math>
520 <mml:mi mathvariant=
"italic">k
</mml:mi>
521 <mml:mo>⁢</mml:mo>
522 <mml:mi mathvariant=
"italic">p
</mml:mi>
524 </mml:math></inlineequation>,
526 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
527 is the number of components or indices
528 per image, as computed in the
<constant>GL_PACK_IMAGE_HEIGHT
</constant> section.
533 <term><constant>GL_PACK_ALIGNMENT
</constant></term>
536 Specifies the alignment requirements for the start of each pixel row in memory.
537 The allowable values are
539 2 (rows aligned to even-numbered bytes),
540 4 (word-alignment), and
541 8 (rows start on double-word boundaries).
547 The other six of the twelve storage parameters affect how pixel data is
548 read from client memory.
549 These values are significant for
550 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
551 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
552 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
553 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
554 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>, and
555 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
562 <term><constant>GL_UNPACK_SWAP_BYTES
</constant></term>
566 byte ordering for multibyte color components,
571 if a four-byte component consists of bytes
572 <inlineequation><mml:math>
573 <!-- eqn: b sub 0: -->
574 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
577 </mml:math></inlineequation>,
578 <inlineequation><mml:math>
579 <!-- eqn: b sub 1: -->
580 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
583 </mml:math></inlineequation>,
584 <inlineequation><mml:math>
585 <!-- eqn: b sub 2: -->
586 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
589 </mml:math></inlineequation>,
590 <inlineequation><mml:math>
591 <!-- eqn: b sub 3: -->
592 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
595 </mml:math></inlineequation>,
596 it is taken from memory as
597 <inlineequation><mml:math>
598 <!-- eqn: b sub 3: -->
599 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
602 </mml:math></inlineequation>,
603 <inlineequation><mml:math>
604 <!-- eqn: b sub 2: -->
605 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
608 </mml:math></inlineequation>,
609 <inlineequation><mml:math>
610 <!-- eqn: b sub 1: -->
611 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
614 </mml:math></inlineequation>,
615 <inlineequation><mml:math>
616 <!-- eqn: b sub 0: -->
617 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
620 </mml:math></inlineequation>
621 if
<constant>GL_UNPACK_SWAP_BYTES
</constant> is true.
622 <constant>GL_UNPACK_SWAP_BYTES
</constant> has no effect on the memory order of components
624 only on the order of bytes within components or indices.
626 the three components of a
<constant>GL_RGB
</constant> format pixel are always stored with
630 regardless of the value of
<constant>GL_UNPACK_SWAP_BYTES
</constant>.
635 <term><constant>GL_UNPACK_LSB_FIRST
</constant></term>
639 bits are ordered within a byte from least significant to most significant;
641 the first bit in each byte is the most significant one.
646 <term><constant>GL_UNPACK_ROW_LENGTH
</constant></term>
650 <constant>GL_UNPACK_ROW_LENGTH
</constant> defines the number of pixels in a row.
651 If the first pixel of a row is placed at location
652 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
654 then the location of the first pixel of the next row is obtained by skipping
657 <informalequation><mml:math>
658 <!-- eqn: k = left { lpile { n l above {a over s} left ceiling { s n l } over a right ceiling } lpile { s >= a above s < a }: -->
660 <mml:mi mathvariant=
"italic">k
</mml:mi>
662 <mml:mfenced open=
"{" close=
"">
667 <mml:mi mathvariant=
"italic">n
</mml:mi>
668 <mml:mo>⁢</mml:mo>
669 <mml:mi mathvariant=
"italic">l
</mml:mi>
674 <mml:mfenced open=
"" close=
"">
676 <mml:mi mathvariant=
"italic">a
</mml:mi>
677 <mml:mi mathvariant=
"italic">s
</mml:mi>
680 <mml:mo>⁢</mml:mo>
681 <mml:mfenced open=
"⌈" close=
"⌉">
683 <mml:mfenced open=
"" close=
"">
685 <mml:mi mathvariant=
"italic">s
</mml:mi>
686 <mml:mo>⁢</mml:mo>
687 <mml:mi mathvariant=
"italic">n
</mml:mi>
688 <mml:mo>⁢</mml:mo>
689 <mml:mi mathvariant=
"italic">l
</mml:mi>
692 <mml:mi mathvariant=
"italic">a
</mml:mi>
698 <mml:mo>⁢</mml:mo>
702 <mml:mi mathvariant=
"italic">s
</mml:mi>
703 <mml:mo>>=
</mml:mo>
704 <mml:mi mathvariant=
"italic">a
</mml:mi>
709 <mml:mi mathvariant=
"italic">s
</mml:mi>
710 <mml:mo><</mml:mo>
711 <mml:mi mathvariant=
"italic">a
</mml:mi>
718 </mml:math></informalequation>
721 components or indices,
723 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
724 is the number of components or indices in a pixel,
725 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
726 is the number of pixels in a row
727 (
<constant>GL_UNPACK_ROW_LENGTH
</constant> if it is greater than
0,
729 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
730 argument to the pixel routine otherwise),
731 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
732 is the value of
<constant>GL_UNPACK_ALIGNMENT
</constant>, and
733 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
734 is the size, in bytes, of a single component
736 <inlineequation><mml:math>
739 <mml:mi mathvariant=
"italic">a
</mml:mi>
740 <mml:mo><</mml:mo>
741 <mml:mi mathvariant=
"italic">s
</mml:mi>
743 </mml:math></inlineequation>,
745 <inlineequation><mml:math>
748 <mml:mi mathvariant=
"italic">a
</mml:mi>
750 <mml:mi mathvariant=
"italic">s
</mml:mi>
752 </mml:math></inlineequation>).
753 In the case of
1-bit values,
754 the location of the next row is obtained by skipping
757 <inlineequation><mml:math>
758 <!-- eqn: k = 8 a left ceiling { n l } over { 8 a } right ceiling: -->
760 <mml:mi mathvariant=
"italic">k
</mml:mi>
764 <mml:mo>⁢</mml:mo>
765 <mml:mi mathvariant=
"italic">a
</mml:mi>
766 <mml:mo>⁢</mml:mo>
767 <mml:mfenced open=
"⌈" close=
"⌉">
769 <mml:mfenced open=
"" close=
"">
771 <mml:mi mathvariant=
"italic">n
</mml:mi>
772 <mml:mo>⁢</mml:mo>
773 <mml:mi mathvariant=
"italic">l
</mml:mi>
776 <mml:mfenced open=
"" close=
"">
779 <mml:mo>⁢</mml:mo>
780 <mml:mi mathvariant=
"italic">a
</mml:mi>
787 </mml:math></inlineequation>
790 components or indices.
793 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
799 Storage format
<constant>GL_RGB
</constant>,
801 has three components per pixel:
809 <term><constant>GL_UNPACK_IMAGE_HEIGHT
</constant></term>
813 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant> defines the number of pixels in an image of
814 a three-dimensional texture volume. Where ``image'' is defined by all
815 pixel sharing the same third dimension index.
816 If the first pixel of a row is placed at location
817 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
819 then the location of the first pixel of the next row is obtained by skipping
822 <informalequation><mml:math>
823 <!-- eqn: k = left { lpile { n l h above {a over s} left ceiling { s n l h } over a right ceiling } lpile { s >= a above s < a }: -->
825 <mml:mi mathvariant=
"italic">k
</mml:mi>
827 <mml:mfenced open=
"{" close=
"">
832 <mml:mi mathvariant=
"italic">n
</mml:mi>
833 <mml:mo>⁢</mml:mo>
834 <mml:mi mathvariant=
"italic">l
</mml:mi>
835 <mml:mo>⁢</mml:mo>
836 <mml:mi mathvariant=
"italic">h
</mml:mi>
841 <mml:mfenced open=
"" close=
"">
843 <mml:mi mathvariant=
"italic">a
</mml:mi>
844 <mml:mi mathvariant=
"italic">s
</mml:mi>
847 <mml:mo>⁢</mml:mo>
848 <mml:mfenced open=
"⌈" close=
"⌉">
850 <mml:mfenced open=
"" close=
"">
852 <mml:mi mathvariant=
"italic">s
</mml:mi>
853 <mml:mo>⁢</mml:mo>
854 <mml:mi mathvariant=
"italic">n
</mml:mi>
855 <mml:mo>⁢</mml:mo>
856 <mml:mi mathvariant=
"italic">l
</mml:mi>
857 <mml:mo>⁢</mml:mo>
858 <mml:mi mathvariant=
"italic">h
</mml:mi>
861 <mml:mi mathvariant=
"italic">a
</mml:mi>
867 <mml:mo>⁢</mml:mo>
871 <mml:mi mathvariant=
"italic">s
</mml:mi>
872 <mml:mo>>=
</mml:mo>
873 <mml:mi mathvariant=
"italic">a
</mml:mi>
878 <mml:mi mathvariant=
"italic">s
</mml:mi>
879 <mml:mo><</mml:mo>
880 <mml:mi mathvariant=
"italic">a
</mml:mi>
887 </mml:math></informalequation>
890 components or indices,
892 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
893 is the number of components or indices in a pixel,
894 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
895 is the number of pixels in a row
896 (
<constant>GL_UNPACK_ROW_LENGTH
</constant> if it is greater than
0,
898 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
899 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
900 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
901 is the number of rows in an image (
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant> if
902 it is greater than
0, the
903 <inlineequation><mml:math><mml:mi mathvariant=
"italic">height
</mml:mi></mml:math></inlineequation>
904 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
905 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
906 is the value of
<constant>GL_UNPACK_ALIGNMENT
</constant>, and
907 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
908 is the size, in bytes, of a single component
910 <inlineequation><mml:math>
913 <mml:mi mathvariant=
"italic">a
</mml:mi>
914 <mml:mo><</mml:mo>
915 <mml:mi mathvariant=
"italic">s
</mml:mi>
917 </mml:math></inlineequation>,
919 <inlineequation><mml:math>
922 <mml:mi mathvariant=
"italic">a
</mml:mi>
924 <mml:mi mathvariant=
"italic">s
</mml:mi>
926 </mml:math></inlineequation>).
929 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
935 Storage format
<constant>GL_RGB
</constant>,
937 has three components per pixel:
945 <term><constant>GL_UNPACK_SKIP_PIXELS
</constant> and
<constant>GL_UNPACK_SKIP_ROWS
</constant></term>
948 These values are provided as a convenience to the programmer;
949 they provide no functionality that cannot be duplicated by
950 incrementing the pointer passed to
951 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
952 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
953 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry> or
954 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>.
955 Setting
<constant>GL_UNPACK_SKIP_PIXELS
</constant> to
956 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
957 is equivalent to incrementing
959 <inlineequation><mml:math>
962 <mml:mi mathvariant=
"italic">i
</mml:mi>
963 <mml:mo>⁢</mml:mo>
964 <mml:mi mathvariant=
"italic">n
</mml:mi>
966 </mml:math></inlineequation>
967 components or indices,
969 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
970 is the number of components or indices in each pixel.
971 Setting
<constant>GL_UNPACK_SKIP_ROWS
</constant> to
972 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>
973 is equivalent to incrementing
975 <inlineequation><mml:math>
978 <mml:mi mathvariant=
"italic">j
</mml:mi>
979 <mml:mo>⁢</mml:mo>
980 <mml:mi mathvariant=
"italic">k
</mml:mi>
982 </mml:math></inlineequation>
983 components or indices,
985 <inlineequation><mml:math><mml:mi mathvariant=
"italic">k
</mml:mi></mml:math></inlineequation>
986 is the number of components or indices per row,
987 as just computed in the
<constant>GL_UNPACK_ROW_LENGTH
</constant> section.
992 <term><constant>GL_UNPACK_ALIGNMENT
</constant></term>
995 Specifies the alignment requirements for the start of each pixel row in memory.
996 The allowable values are
998 2 (rows aligned to even-numbered bytes),
999 4 (word-alignment), and
1000 8 (rows start on double-word boundaries).
1006 The following table gives the type,
1008 and range of valid values for each storage parameter
1009 that can be set with
<function>glPixelStore
</function>.
1013 <informaltable frame=
"topbot">
1014 <tgroup cols=
"4" align=
"left">
1015 <colspec colwidth=
"2.5*" />
1016 <colspec colwidth=
"1*" align=
"center"/>
1017 <colspec colwidth=
"1*" align=
"center"/>
1018 <colspec colwidth=
"2*" align=
"center"/>
1021 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
1022 <parameter>pname
</parameter>
1024 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1027 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1030 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1037 <entry align=
"left">
1038 <constant>GL_PACK_SWAP_BYTES
</constant>
1040 <entry align=
"center">
1043 <entry align=
"center">
1046 <entry align=
"center">
1051 <entry align=
"left">
1052 <constant>GL_PACK_LSB_FIRST
</constant>
1054 <entry align=
"center">
1057 <entry align=
"center">
1060 <entry align=
"center">
1065 <entry align=
"left">
1066 <constant>GL_PACK_ROW_LENGTH
</constant>
1068 <entry align=
"center">
1071 <entry align=
"center">
1074 <entry align=
"center">
1075 <inlineequation><mml:math>
1076 <!-- eqn: left [ 0,\(if right ): -->
1077 <mml:mfenced open=
"[" close=
")">
1081 </mml:math></inlineequation>
1085 <entry align=
"left">
1086 <constant>GL_PACK_IMAGE_HEIGHT
</constant>
1088 <entry align=
"center">
1091 <entry align=
"center">
1094 <entry align=
"center">
1095 <inlineequation><mml:math>
1096 <!-- eqn: left [ 0, \(if right ): -->
1097 <mml:mfenced open=
"[" close=
")">
1101 </mml:math></inlineequation>
1105 <entry align=
"left">
1106 <constant>GL_PACK_SKIP_ROWS
</constant>
1108 <entry align=
"center">
1111 <entry align=
"center">
1114 <entry align=
"center">
1115 <inlineequation><mml:math>
1116 <!-- eqn: left [ 0,\(if right ): -->
1117 <mml:mfenced open=
"[" close=
")">
1121 </mml:math></inlineequation>
1125 <entry align=
"left">
1126 <constant>GL_PACK_SKIP_PIXELS
</constant>
1128 <entry align=
"center">
1131 <entry align=
"center">
1134 <entry align=
"center">
1135 <inlineequation><mml:math>
1136 <!-- eqn: left [ 0,\(if right ): -->
1137 <mml:mfenced open=
"[" close=
")">
1141 </mml:math></inlineequation>
1145 <entry align=
"left">
1146 <constant>GL_PACK_SKIP_IMAGES
</constant>
1148 <entry align=
"center">
1151 <entry align=
"center">
1154 <entry align=
"center">
1155 <inlineequation><mml:math>
1156 <!-- eqn: left [ 0,\(if right ): -->
1157 <mml:mfenced open=
"[" close=
")">
1161 </mml:math></inlineequation>
1165 <entry align=
"left">
1166 <constant>GL_PACK_ALIGNMENT
</constant>
1168 <entry align=
"center">
1171 <entry align=
"center">
1174 <entry align=
"center">
1179 <entry align=
"left">
1180 <constant>GL_UNPACK_SWAP_BYTES
</constant>
1182 <entry align=
"center">
1185 <entry align=
"center">
1188 <entry align=
"center">
1193 <entry align=
"left">
1194 <constant>GL_UNPACK_LSB_FIRST
</constant>
1196 <entry align=
"center">
1199 <entry align=
"center">
1202 <entry align=
"center">
1207 <entry align=
"left">
1208 <constant>GL_UNPACK_ROW_LENGTH
</constant>
1210 <entry align=
"center">
1213 <entry align=
"center">
1216 <entry align=
"center">
1217 <inlineequation><mml:math>
1218 <!-- eqn: left [ 0,\(if right ): -->
1219 <mml:mfenced open=
"[" close=
")">
1223 </mml:math></inlineequation>
1227 <entry align=
"left">
1228 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant>
1230 <entry align=
"center">
1233 <entry align=
"center">
1236 <entry align=
"center">
1237 <inlineequation><mml:math>
1238 <!-- eqn: left [ 0,\(if right ): -->
1239 <mml:mfenced open=
"[" close=
")">
1243 </mml:math></inlineequation>
1247 <entry align=
"left">
1248 <constant>GL_UNPACK_SKIP_ROWS
</constant>
1250 <entry align=
"center">
1253 <entry align=
"center">
1256 <entry align=
"center">
1257 <inlineequation><mml:math>
1258 <!-- eqn: left [ 0,\(if right ): -->
1259 <mml:mfenced open=
"[" close=
")">
1263 </mml:math></inlineequation>
1267 <entry align=
"left">
1268 <constant>GL_UNPACK_SKIP_PIXELS
</constant>
1270 <entry align=
"center">
1273 <entry align=
"center">
1276 <entry align=
"center">
1277 <inlineequation><mml:math>
1278 <!-- eqn: left [ 0,\(if right ): -->
1279 <mml:mfenced open=
"[" close=
")">
1283 </mml:math></inlineequation>
1287 <entry align=
"left">
1288 <constant>GL_UNPACK_SKIP_IMAGES
</constant>
1290 <entry align=
"center">
1293 <entry align=
"center">
1296 <entry align=
"center">
1297 <inlineequation><mml:math>
1298 <!-- eqn: left [ 0,\(if right ): -->
1299 <mml:mfenced open=
"[" close=
")">
1303 </mml:math></inlineequation>
1307 <entry align=
"left">
1308 <constant>GL_UNPACK_ALIGNMENT
</constant>
1310 <entry align=
"center">
1313 <entry align=
"center">
1316 <entry align=
"center">
1324 <function>glPixelStoref
</function> can be used to set any pixel store parameter.
1325 If the parameter type is boolean,
1326 then if
<parameter>param
</parameter> is
0,
1327 the parameter is false;
1328 otherwise it is set to true.
1329 If
<parameter>pname
</parameter> is a integer type parameter,
1330 <parameter>param
</parameter> is rounded to the nearest integer.
1333 Likewise,
<function>glPixelStorei
</function> can also be used to set any of the
1334 pixel store parameters.
1335 Boolean parameters are set to false if
<parameter>param
</parameter> is
0 and true otherwise.
1338 <refsect1 id=
"errors"><title>Errors
</title>
1340 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>pname
</parameter> is not an accepted value.
1343 <constant>GL_INVALID_VALUE
</constant> is generated if a negative row length,
1345 or row skip value is specified,
1346 or if alignment is specified as other than
1,
2,
4, or
8.
1349 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
1351 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SWAP_BYTES
</constant>
1354 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_LSB_FIRST
</constant>
1357 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_ROW_LENGTH
</constant>
1360 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_IMAGE_HEIGHT
</constant>
1363 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_ROWS
</constant>
1366 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_PIXELS
</constant>
1369 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_IMAGES
</constant>
1372 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_ALIGNMENT
</constant>
1375 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SWAP_BYTES
</constant>
1378 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_LSB_FIRST
</constant>
1381 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_ROW_LENGTH
</constant>
1384 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant>
1387 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_ROWS
</constant>
1390 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_PIXELS
</constant>
1393 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_IMAGES
</constant>
1396 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_ALIGNMENT
</constant>
1399 <refsect1 id=
"seealso"><title>See Also
</title>
1401 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>,
1402 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
1403 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
1404 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
1405 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
1406 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
1407 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
1410 <refsect1 id=
"Copyright"><title>Copyright
</title>
1412 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
1413 Silicon Graphics, Inc. This document is licensed under the SGI
1414 Free Software B License. For details, see
1415 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.