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>),
81 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
82 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
83 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>.
86 <parameter>pname
</parameter> is a symbolic constant indicating the parameter to be set, and
87 <parameter>param
</parameter> is the new value. Six of the twelve storage parameters affect
88 how pixel data is returned to client memory.
93 <term><constant>GL_PACK_SWAP_BYTES
</constant></term>
97 byte ordering for multibyte color components,
102 if a four-byte component consists of bytes
103 <inlineequation><mml:math>
104 <!-- eqn: b sub 0: -->
105 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
108 </mml:math></inlineequation>,
109 <inlineequation><mml:math>
110 <!-- eqn: b sub 1: -->
111 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
114 </mml:math></inlineequation>,
115 <inlineequation><mml:math>
116 <!-- eqn: b sub 2: -->
117 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
120 </mml:math></inlineequation>,
121 <inlineequation><mml:math>
122 <!-- eqn: b sub 3: -->
123 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
126 </mml:math></inlineequation>,
127 it is stored in memory as
128 <inlineequation><mml:math>
129 <!-- eqn: b sub 3: -->
130 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
133 </mml:math></inlineequation>,
134 <inlineequation><mml:math>
135 <!-- eqn: b sub 2: -->
136 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
139 </mml:math></inlineequation>,
140 <inlineequation><mml:math>
141 <!-- eqn: b sub 1: -->
142 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
145 </mml:math></inlineequation>,
146 <inlineequation><mml:math>
147 <!-- eqn: b sub 0: -->
148 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
151 </mml:math></inlineequation>
152 if
<constant>GL_PACK_SWAP_BYTES
</constant> is true.
153 <constant>GL_PACK_SWAP_BYTES
</constant> has no effect on the memory order of components
155 only on the order of bytes within components or indices.
157 the three components of a
<constant>GL_RGB
</constant> format pixel are always stored with
161 regardless of the value of
<constant>GL_PACK_SWAP_BYTES
</constant>.
166 <term><constant>GL_PACK_LSB_FIRST
</constant></term>
170 bits are ordered within a byte from least significant to most significant;
172 the first bit in each byte is the most significant one.
177 <term><constant>GL_PACK_ROW_LENGTH
</constant></term>
181 <constant>GL_PACK_ROW_LENGTH
</constant> defines the number of pixels in a row.
182 If the first pixel of a row is placed at location
183 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
185 then the location of the first pixel of the next row is obtained by skipping
188 <informalequation><mml:math>
189 <!-- 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 }: -->
191 <mml:mi mathvariant=
"italic">k
</mml:mi>
193 <mml:mfenced open=
"{" close=
"">
198 <mml:mi mathvariant=
"italic">n
</mml:mi>
199 <mml:mo>⁢</mml:mo>
200 <mml:mi mathvariant=
"italic">l
</mml:mi>
205 <mml:mfenced open=
"" close=
"">
207 <mml:mi mathvariant=
"italic">a
</mml:mi>
208 <mml:mi mathvariant=
"italic">s
</mml:mi>
211 <mml:mo>⁢</mml:mo>
212 <mml:mfenced open=
"⌈" close=
"⌉">
214 <mml:mfenced open=
"" close=
"">
216 <mml:mi mathvariant=
"italic">s
</mml:mi>
217 <mml:mo>⁢</mml:mo>
218 <mml:mi mathvariant=
"italic">n
</mml:mi>
219 <mml:mo>⁢</mml:mo>
220 <mml:mi mathvariant=
"italic">l
</mml:mi>
223 <mml:mi mathvariant=
"italic">a
</mml:mi>
229 <mml:mo>⁢</mml:mo>
233 <mml:mi mathvariant=
"italic">s
</mml:mi>
234 <mml:mo>>=
</mml:mo>
235 <mml:mi mathvariant=
"italic">a
</mml:mi>
240 <mml:mi mathvariant=
"italic">s
</mml:mi>
241 <mml:mo><</mml:mo>
242 <mml:mi mathvariant=
"italic">a
</mml:mi>
249 </mml:math></informalequation>
252 components or indices,
254 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
255 is the number of components or indices in a pixel,
256 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
257 is the number of pixels in a row
258 (
<constant>GL_PACK_ROW_LENGTH
</constant> if it is greater than
0,
260 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
261 argument to the pixel routine otherwise),
262 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
263 is the value of
<constant>GL_PACK_ALIGNMENT
</constant>, and
264 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
265 is the size, in bytes, of a single component
267 <inlineequation><mml:math>
270 <mml:mi mathvariant=
"italic">a
</mml:mi>
271 <mml:mo><</mml:mo>
272 <mml:mi mathvariant=
"italic">s
</mml:mi>
274 </mml:math></inlineequation>,
276 <inlineequation><mml:math>
279 <mml:mi mathvariant=
"italic">a
</mml:mi>
281 <mml:mi mathvariant=
"italic">s
</mml:mi>
283 </mml:math></inlineequation>).
284 In the case of
1-bit values,
285 the location of the next row is obtained by skipping
288 <inlineequation><mml:math>
289 <!-- eqn: k = 8 a left ceiling { n l } over { 8 a } right ceiling: -->
291 <mml:mi mathvariant=
"italic">k
</mml:mi>
295 <mml:mo>⁢</mml:mo>
296 <mml:mi mathvariant=
"italic">a
</mml:mi>
297 <mml:mo>⁢</mml:mo>
298 <mml:mfenced open=
"⌈" close=
"⌉">
300 <mml:mfenced open=
"" close=
"">
302 <mml:mi mathvariant=
"italic">n
</mml:mi>
303 <mml:mo>⁢</mml:mo>
304 <mml:mi mathvariant=
"italic">l
</mml:mi>
307 <mml:mfenced open=
"" close=
"">
310 <mml:mo>⁢</mml:mo>
311 <mml:mi mathvariant=
"italic">a
</mml:mi>
318 </mml:math></inlineequation>
321 components or indices.
324 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
330 Storage format
<constant>GL_RGB
</constant>,
332 has three components per pixel:
340 <term><constant>GL_PACK_IMAGE_HEIGHT
</constant></term>
344 <constant>GL_PACK_IMAGE_HEIGHT
</constant> defines the number of pixels in an image
345 three-dimensional texture volume, where ``image'' is defined by all pixels
346 sharing the same third dimension index.
347 If the first pixel of a row is placed at location
348 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
350 then the location of the first pixel of the next row is obtained by skipping
353 <informalequation><mml:math>
354 <!-- 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 }: -->
356 <mml:mi mathvariant=
"italic">k
</mml:mi>
358 <mml:mfenced open=
"{" close=
"">
363 <mml:mi mathvariant=
"italic">n
</mml:mi>
364 <mml:mo>⁢</mml:mo>
365 <mml:mi mathvariant=
"italic">l
</mml:mi>
366 <mml:mo>⁢</mml:mo>
367 <mml:mi mathvariant=
"italic">h
</mml:mi>
372 <mml:mfenced open=
"" close=
"">
374 <mml:mi mathvariant=
"italic">a
</mml:mi>
375 <mml:mi mathvariant=
"italic">s
</mml:mi>
378 <mml:mo>⁢</mml:mo>
379 <mml:mfenced open=
"⌈" close=
"⌉">
381 <mml:mfenced open=
"" close=
"">
383 <mml:mi mathvariant=
"italic">s
</mml:mi>
384 <mml:mo>⁢</mml:mo>
385 <mml:mi mathvariant=
"italic">n
</mml:mi>
386 <mml:mo>⁢</mml:mo>
387 <mml:mi mathvariant=
"italic">l
</mml:mi>
388 <mml:mo>⁢</mml:mo>
389 <mml:mi mathvariant=
"italic">h
</mml:mi>
392 <mml:mi mathvariant=
"italic">a
</mml:mi>
398 <mml:mo>⁢</mml:mo>
402 <mml:mi mathvariant=
"italic">s
</mml:mi>
403 <mml:mo>>=
</mml:mo>
404 <mml:mi mathvariant=
"italic">a
</mml:mi>
409 <mml:mi mathvariant=
"italic">s
</mml:mi>
410 <mml:mo><</mml:mo>
411 <mml:mi mathvariant=
"italic">a
</mml:mi>
418 </mml:math></informalequation>
421 components or indices, where
422 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
423 is the number of components or indices
425 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
426 is the number of pixels in a row
427 (
<constant>GL_PACK_ROW_LENGTH
</constant> if it is greater than
0, the
428 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
429 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
430 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
432 rows in a pixel image (
<constant>GL_PACK_IMAGE_HEIGHT
</constant> if it is greater than
434 <inlineequation><mml:math><mml:mi mathvariant=
"italic">height
</mml:mi></mml:math></inlineequation>
435 argument to the
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> routine otherwise),
436 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
438 <constant>GL_PACK_ALIGNMENT
</constant>, and
439 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
440 is the size, in bytes, of a single
442 <inlineequation><mml:math>
445 <mml:mi mathvariant=
"italic">a
</mml:mi>
446 <mml:mo><</mml:mo>
447 <mml:mi mathvariant=
"italic">s
</mml:mi>
449 </mml:math></inlineequation>,
451 <inlineequation><mml:math>
454 <mml:mi mathvariant=
"italic">a
</mml:mi>
456 <mml:mi mathvariant=
"italic">s
</mml:mi>
458 </mml:math></inlineequation>).
461 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
467 Storage format
<constant>GL_RGB
</constant>,
469 has three components per pixel:
477 <term><constant>GL_PACK_SKIP_PIXELS
</constant>,
<constant>GL_PACK_SKIP_ROWS
</constant>, and
<constant>GL_PACK_SKIP_IMAGES
</constant></term>
480 These values are provided as a convenience to the programmer;
481 they provide no functionality that cannot be duplicated simply by
482 incrementing the pointer passed to
<citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>.
483 Setting
<constant>GL_PACK_SKIP_PIXELS
</constant> to
484 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
485 is equivalent to incrementing
487 <inlineequation><mml:math>
490 <mml:mi mathvariant=
"italic">i
</mml:mi>
491 <mml:mo>⁢</mml:mo>
492 <mml:mi mathvariant=
"italic">n
</mml:mi>
494 </mml:math></inlineequation>
495 components or indices,
497 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
498 is the number of components or indices in each pixel.
499 Setting
<constant>GL_PACK_SKIP_ROWS
</constant> to
500 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>
501 is equivalent to incrementing
503 <inlineequation><mml:math>
506 <mml:mi mathvariant=
"italic">j
</mml:mi>
507 <mml:mo>⁢</mml:mo>
508 <mml:mi mathvariant=
"italic">m
</mml:mi>
510 </mml:math></inlineequation>
511 components or indices,
513 <inlineequation><mml:math><mml:mi mathvariant=
"italic">m
</mml:mi></mml:math></inlineequation>
514 is the number of components or indices per row,
515 as just computed in the
<constant>GL_PACK_ROW_LENGTH
</constant> section.
516 Setting
<constant>GL_PACK_SKIP_IMAGES
</constant> to
517 <inlineequation><mml:math><mml:mi mathvariant=
"italic">k
</mml:mi></mml:math></inlineequation>
518 is equivalent to incrementing
520 <inlineequation><mml:math>
523 <mml:mi mathvariant=
"italic">k
</mml:mi>
524 <mml:mo>⁢</mml:mo>
525 <mml:mi mathvariant=
"italic">p
</mml:mi>
527 </mml:math></inlineequation>,
529 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
530 is the number of components or indices
531 per image, as computed in the
<constant>GL_PACK_IMAGE_HEIGHT
</constant> section.
536 <term><constant>GL_PACK_ALIGNMENT
</constant></term>
539 Specifies the alignment requirements for the start of each pixel row in memory.
540 The allowable values are
542 2 (rows aligned to even-numbered bytes),
543 4 (word-alignment), and
544 8 (rows start on double-word boundaries).
550 The other six of the twelve storage parameters affect how pixel data is
551 read from client memory.
552 These values are significant for
553 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
554 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
555 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
556 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
557 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>, and
558 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
565 <term><constant>GL_UNPACK_SWAP_BYTES
</constant></term>
569 byte ordering for multibyte color components,
574 if a four-byte component consists of bytes
575 <inlineequation><mml:math>
576 <!-- eqn: b sub 0: -->
577 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
580 </mml:math></inlineequation>,
581 <inlineequation><mml:math>
582 <!-- eqn: b sub 1: -->
583 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
586 </mml:math></inlineequation>,
587 <inlineequation><mml:math>
588 <!-- eqn: b sub 2: -->
589 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
592 </mml:math></inlineequation>,
593 <inlineequation><mml:math>
594 <!-- eqn: b sub 3: -->
595 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
598 </mml:math></inlineequation>,
599 it is taken from memory as
600 <inlineequation><mml:math>
601 <!-- eqn: b sub 3: -->
602 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
605 </mml:math></inlineequation>,
606 <inlineequation><mml:math>
607 <!-- eqn: b sub 2: -->
608 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
611 </mml:math></inlineequation>,
612 <inlineequation><mml:math>
613 <!-- eqn: b sub 1: -->
614 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
617 </mml:math></inlineequation>,
618 <inlineequation><mml:math>
619 <!-- eqn: b sub 0: -->
620 <mml:msub><mml:mi mathvariant=
"italic">b
</mml:mi>
623 </mml:math></inlineequation>
624 if
<constant>GL_UNPACK_SWAP_BYTES
</constant> is true.
625 <constant>GL_UNPACK_SWAP_BYTES
</constant> has no effect on the memory order of components
627 only on the order of bytes within components or indices.
629 the three components of a
<constant>GL_RGB
</constant> format pixel are always stored with
633 regardless of the value of
<constant>GL_UNPACK_SWAP_BYTES
</constant>.
638 <term><constant>GL_UNPACK_LSB_FIRST
</constant></term>
642 bits are ordered within a byte from least significant to most significant;
644 the first bit in each byte is the most significant one.
649 <term><constant>GL_UNPACK_ROW_LENGTH
</constant></term>
653 <constant>GL_UNPACK_ROW_LENGTH
</constant> defines the number of pixels in a row.
654 If the first pixel of a row is placed at location
655 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
657 then the location of the first pixel of the next row is obtained by skipping
660 <informalequation><mml:math>
661 <!-- 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 }: -->
663 <mml:mi mathvariant=
"italic">k
</mml:mi>
665 <mml:mfenced open=
"{" close=
"">
670 <mml:mi mathvariant=
"italic">n
</mml:mi>
671 <mml:mo>⁢</mml:mo>
672 <mml:mi mathvariant=
"italic">l
</mml:mi>
677 <mml:mfenced open=
"" close=
"">
679 <mml:mi mathvariant=
"italic">a
</mml:mi>
680 <mml:mi mathvariant=
"italic">s
</mml:mi>
683 <mml:mo>⁢</mml:mo>
684 <mml:mfenced open=
"⌈" close=
"⌉">
686 <mml:mfenced open=
"" close=
"">
688 <mml:mi mathvariant=
"italic">s
</mml:mi>
689 <mml:mo>⁢</mml:mo>
690 <mml:mi mathvariant=
"italic">n
</mml:mi>
691 <mml:mo>⁢</mml:mo>
692 <mml:mi mathvariant=
"italic">l
</mml:mi>
695 <mml:mi mathvariant=
"italic">a
</mml:mi>
701 <mml:mo>⁢</mml:mo>
705 <mml:mi mathvariant=
"italic">s
</mml:mi>
706 <mml:mo>>=
</mml:mo>
707 <mml:mi mathvariant=
"italic">a
</mml:mi>
712 <mml:mi mathvariant=
"italic">s
</mml:mi>
713 <mml:mo><</mml:mo>
714 <mml:mi mathvariant=
"italic">a
</mml:mi>
721 </mml:math></informalequation>
724 components or indices,
726 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
727 is the number of components or indices in a pixel,
728 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
729 is the number of pixels in a row
730 (
<constant>GL_UNPACK_ROW_LENGTH
</constant> if it is greater than
0,
732 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
733 argument to the pixel routine otherwise),
734 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
735 is the value of
<constant>GL_UNPACK_ALIGNMENT
</constant>, and
736 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
737 is the size, in bytes, of a single component
739 <inlineequation><mml:math>
742 <mml:mi mathvariant=
"italic">a
</mml:mi>
743 <mml:mo><</mml:mo>
744 <mml:mi mathvariant=
"italic">s
</mml:mi>
746 </mml:math></inlineequation>,
748 <inlineequation><mml:math>
751 <mml:mi mathvariant=
"italic">a
</mml:mi>
753 <mml:mi mathvariant=
"italic">s
</mml:mi>
755 </mml:math></inlineequation>).
756 In the case of
1-bit values,
757 the location of the next row is obtained by skipping
760 <inlineequation><mml:math>
761 <!-- eqn: k = 8 a left ceiling { n l } over { 8 a } right ceiling: -->
763 <mml:mi mathvariant=
"italic">k
</mml:mi>
767 <mml:mo>⁢</mml:mo>
768 <mml:mi mathvariant=
"italic">a
</mml:mi>
769 <mml:mo>⁢</mml:mo>
770 <mml:mfenced open=
"⌈" close=
"⌉">
772 <mml:mfenced open=
"" close=
"">
774 <mml:mi mathvariant=
"italic">n
</mml:mi>
775 <mml:mo>⁢</mml:mo>
776 <mml:mi mathvariant=
"italic">l
</mml:mi>
779 <mml:mfenced open=
"" close=
"">
782 <mml:mo>⁢</mml:mo>
783 <mml:mi mathvariant=
"italic">a
</mml:mi>
790 </mml:math></inlineequation>
793 components or indices.
796 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
802 Storage format
<constant>GL_RGB
</constant>,
804 has three components per pixel:
812 <term><constant>GL_UNPACK_IMAGE_HEIGHT
</constant></term>
816 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant> defines the number of pixels in an image of
817 a three-dimensional texture volume. Where ``image'' is defined by all
818 pixel sharing the same third dimension index.
819 If the first pixel of a row is placed at location
820 <inlineequation><mml:math><mml:mi mathvariant=
"italic">p
</mml:mi></mml:math></inlineequation>
822 then the location of the first pixel of the next row is obtained by skipping
825 <informalequation><mml:math>
826 <!-- 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 }: -->
828 <mml:mi mathvariant=
"italic">k
</mml:mi>
830 <mml:mfenced open=
"{" close=
"">
835 <mml:mi mathvariant=
"italic">n
</mml:mi>
836 <mml:mo>⁢</mml:mo>
837 <mml:mi mathvariant=
"italic">l
</mml:mi>
838 <mml:mo>⁢</mml:mo>
839 <mml:mi mathvariant=
"italic">h
</mml:mi>
844 <mml:mfenced open=
"" close=
"">
846 <mml:mi mathvariant=
"italic">a
</mml:mi>
847 <mml:mi mathvariant=
"italic">s
</mml:mi>
850 <mml:mo>⁢</mml:mo>
851 <mml:mfenced open=
"⌈" close=
"⌉">
853 <mml:mfenced open=
"" close=
"">
855 <mml:mi mathvariant=
"italic">s
</mml:mi>
856 <mml:mo>⁢</mml:mo>
857 <mml:mi mathvariant=
"italic">n
</mml:mi>
858 <mml:mo>⁢</mml:mo>
859 <mml:mi mathvariant=
"italic">l
</mml:mi>
860 <mml:mo>⁢</mml:mo>
861 <mml:mi mathvariant=
"italic">h
</mml:mi>
864 <mml:mi mathvariant=
"italic">a
</mml:mi>
870 <mml:mo>⁢</mml:mo>
874 <mml:mi mathvariant=
"italic">s
</mml:mi>
875 <mml:mo>>=
</mml:mo>
876 <mml:mi mathvariant=
"italic">a
</mml:mi>
881 <mml:mi mathvariant=
"italic">s
</mml:mi>
882 <mml:mo><</mml:mo>
883 <mml:mi mathvariant=
"italic">a
</mml:mi>
890 </mml:math></informalequation>
893 components or indices,
895 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
896 is the number of components or indices in a pixel,
897 <inlineequation><mml:math><mml:mi mathvariant=
"italic">l
</mml:mi></mml:math></inlineequation>
898 is the number of pixels in a row
899 (
<constant>GL_UNPACK_ROW_LENGTH
</constant> if it is greater than
0,
901 <inlineequation><mml:math><mml:mi mathvariant=
"italic">width
</mml:mi></mml:math></inlineequation>
902 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
903 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
904 is the number of rows in an image (
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant> if
905 it is greater than
0, the
906 <inlineequation><mml:math><mml:mi mathvariant=
"italic">height
</mml:mi></mml:math></inlineequation>
907 argument to
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> otherwise),
908 <inlineequation><mml:math><mml:mi mathvariant=
"italic">a
</mml:mi></mml:math></inlineequation>
909 is the value of
<constant>GL_UNPACK_ALIGNMENT
</constant>, and
910 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
911 is the size, in bytes, of a single component
913 <inlineequation><mml:math>
916 <mml:mi mathvariant=
"italic">a
</mml:mi>
917 <mml:mo><</mml:mo>
918 <mml:mi mathvariant=
"italic">s
</mml:mi>
920 </mml:math></inlineequation>,
922 <inlineequation><mml:math>
925 <mml:mi mathvariant=
"italic">a
</mml:mi>
927 <mml:mi mathvariant=
"italic">s
</mml:mi>
929 </mml:math></inlineequation>).
932 The word
<emphasis>component
</emphasis> in this description refers to the nonindex values
938 Storage format
<constant>GL_RGB
</constant>,
940 has three components per pixel:
948 <term><constant>GL_UNPACK_SKIP_PIXELS
</constant> and
<constant>GL_UNPACK_SKIP_ROWS
</constant></term>
951 These values are provided as a convenience to the programmer;
952 they provide no functionality that cannot be duplicated by
953 incrementing the pointer passed to
954 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
955 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
956 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry> or
957 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>.
958 Setting
<constant>GL_UNPACK_SKIP_PIXELS
</constant> to
959 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
960 is equivalent to incrementing
962 <inlineequation><mml:math>
965 <mml:mi mathvariant=
"italic">i
</mml:mi>
966 <mml:mo>⁢</mml:mo>
967 <mml:mi mathvariant=
"italic">n
</mml:mi>
969 </mml:math></inlineequation>
970 components or indices,
972 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
973 is the number of components or indices in each pixel.
974 Setting
<constant>GL_UNPACK_SKIP_ROWS
</constant> to
975 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>
976 is equivalent to incrementing
978 <inlineequation><mml:math>
981 <mml:mi mathvariant=
"italic">j
</mml:mi>
982 <mml:mo>⁢</mml:mo>
983 <mml:mi mathvariant=
"italic">k
</mml:mi>
985 </mml:math></inlineequation>
986 components or indices,
988 <inlineequation><mml:math><mml:mi mathvariant=
"italic">k
</mml:mi></mml:math></inlineequation>
989 is the number of components or indices per row,
990 as just computed in the
<constant>GL_UNPACK_ROW_LENGTH
</constant> section.
995 <term><constant>GL_UNPACK_ALIGNMENT
</constant></term>
998 Specifies the alignment requirements for the start of each pixel row in memory.
999 The allowable values are
1001 2 (rows aligned to even-numbered bytes),
1002 4 (word-alignment), and
1003 8 (rows start on double-word boundaries).
1009 The following table gives the type,
1011 and range of valid values for each storage parameter
1012 that can be set with
<function>glPixelStore
</function>.
1016 <informaltable frame=
"topbot">
1017 <tgroup cols=
"4" align=
"left">
1018 <colspec colwidth=
"2.5*" />
1019 <colspec colwidth=
"1*" align=
"center"/>
1020 <colspec colwidth=
"1*" align=
"center"/>
1021 <colspec colwidth=
"2*" align=
"center"/>
1024 <entry rowsep=
"1" align=
"left"><emphasis role=
"bold">
1025 <parameter>pname
</parameter>
1027 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1030 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1033 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
1040 <entry align=
"left">
1041 <constant>GL_PACK_SWAP_BYTES
</constant>
1043 <entry align=
"center">
1046 <entry align=
"center">
1049 <entry align=
"center">
1054 <entry align=
"left">
1055 <constant>GL_PACK_LSB_FIRST
</constant>
1057 <entry align=
"center">
1060 <entry align=
"center">
1063 <entry align=
"center">
1068 <entry align=
"left">
1069 <constant>GL_PACK_ROW_LENGTH
</constant>
1071 <entry align=
"center">
1074 <entry align=
"center">
1077 <entry align=
"center">
1078 <inlineequation><mml:math>
1079 <!-- eqn: left [ 0,\(if right ): -->
1080 <mml:mfenced open=
"[" close=
")">
1084 </mml:math></inlineequation>
1088 <entry align=
"left">
1089 <constant>GL_PACK_IMAGE_HEIGHT
</constant>
1091 <entry align=
"center">
1094 <entry align=
"center">
1097 <entry align=
"center">
1098 <inlineequation><mml:math>
1099 <!-- eqn: left [ 0, \(if right ): -->
1100 <mml:mfenced open=
"[" close=
")">
1104 </mml:math></inlineequation>
1108 <entry align=
"left">
1109 <constant>GL_PACK_SKIP_ROWS
</constant>
1111 <entry align=
"center">
1114 <entry align=
"center">
1117 <entry align=
"center">
1118 <inlineequation><mml:math>
1119 <!-- eqn: left [ 0,\(if right ): -->
1120 <mml:mfenced open=
"[" close=
")">
1124 </mml:math></inlineequation>
1128 <entry align=
"left">
1129 <constant>GL_PACK_SKIP_PIXELS
</constant>
1131 <entry align=
"center">
1134 <entry align=
"center">
1137 <entry align=
"center">
1138 <inlineequation><mml:math>
1139 <!-- eqn: left [ 0,\(if right ): -->
1140 <mml:mfenced open=
"[" close=
")">
1144 </mml:math></inlineequation>
1148 <entry align=
"left">
1149 <constant>GL_PACK_SKIP_IMAGES
</constant>
1151 <entry align=
"center">
1154 <entry align=
"center">
1157 <entry align=
"center">
1158 <inlineequation><mml:math>
1159 <!-- eqn: left [ 0,\(if right ): -->
1160 <mml:mfenced open=
"[" close=
")">
1164 </mml:math></inlineequation>
1168 <entry align=
"left">
1169 <constant>GL_PACK_ALIGNMENT
</constant>
1171 <entry align=
"center">
1174 <entry align=
"center">
1177 <entry align=
"center">
1182 <entry align=
"left">
1183 <constant>GL_UNPACK_SWAP_BYTES
</constant>
1185 <entry align=
"center">
1188 <entry align=
"center">
1191 <entry align=
"center">
1196 <entry align=
"left">
1197 <constant>GL_UNPACK_LSB_FIRST
</constant>
1199 <entry align=
"center">
1202 <entry align=
"center">
1205 <entry align=
"center">
1210 <entry align=
"left">
1211 <constant>GL_UNPACK_ROW_LENGTH
</constant>
1213 <entry align=
"center">
1216 <entry align=
"center">
1219 <entry align=
"center">
1220 <inlineequation><mml:math>
1221 <!-- eqn: left [ 0,\(if right ): -->
1222 <mml:mfenced open=
"[" close=
")">
1226 </mml:math></inlineequation>
1230 <entry align=
"left">
1231 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant>
1233 <entry align=
"center">
1236 <entry align=
"center">
1239 <entry align=
"center">
1240 <inlineequation><mml:math>
1241 <!-- eqn: left [ 0,\(if right ): -->
1242 <mml:mfenced open=
"[" close=
")">
1246 </mml:math></inlineequation>
1250 <entry align=
"left">
1251 <constant>GL_UNPACK_SKIP_ROWS
</constant>
1253 <entry align=
"center">
1256 <entry align=
"center">
1259 <entry align=
"center">
1260 <inlineequation><mml:math>
1261 <!-- eqn: left [ 0,\(if right ): -->
1262 <mml:mfenced open=
"[" close=
")">
1266 </mml:math></inlineequation>
1270 <entry align=
"left">
1271 <constant>GL_UNPACK_SKIP_PIXELS
</constant>
1273 <entry align=
"center">
1276 <entry align=
"center">
1279 <entry align=
"center">
1280 <inlineequation><mml:math>
1281 <!-- eqn: left [ 0,\(if right ): -->
1282 <mml:mfenced open=
"[" close=
")">
1286 </mml:math></inlineequation>
1290 <entry align=
"left">
1291 <constant>GL_UNPACK_SKIP_IMAGES
</constant>
1293 <entry align=
"center">
1296 <entry align=
"center">
1299 <entry align=
"center">
1300 <inlineequation><mml:math>
1301 <!-- eqn: left [ 0,\(if right ): -->
1302 <mml:mfenced open=
"[" close=
")">
1306 </mml:math></inlineequation>
1310 <entry align=
"left">
1311 <constant>GL_UNPACK_ALIGNMENT
</constant>
1313 <entry align=
"center">
1316 <entry align=
"center">
1319 <entry align=
"center">
1327 <function>glPixelStoref
</function> can be used to set any pixel store parameter.
1328 If the parameter type is boolean,
1329 then if
<parameter>param
</parameter> is
0,
1330 the parameter is false;
1331 otherwise it is set to true.
1332 If
<parameter>pname
</parameter> is a integer type parameter,
1333 <parameter>param
</parameter> is rounded to the nearest integer.
1336 Likewise,
<function>glPixelStorei
</function> can also be used to set any of the
1337 pixel store parameters.
1338 Boolean parameters are set to false if
<parameter>param
</parameter> is
0 and true otherwise.
1341 <refsect1 id=
"errors"><title>Errors
</title>
1343 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>pname
</parameter> is not an accepted value.
1346 <constant>GL_INVALID_VALUE
</constant> is generated if a negative row length,
1348 or row skip value is specified,
1349 or if alignment is specified as other than
1,
2,
4, or
8.
1352 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
1354 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SWAP_BYTES
</constant>
1357 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_LSB_FIRST
</constant>
1360 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_ROW_LENGTH
</constant>
1363 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_IMAGE_HEIGHT
</constant>
1366 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_ROWS
</constant>
1369 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_PIXELS
</constant>
1372 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_SKIP_IMAGES
</constant>
1375 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PACK_ALIGNMENT
</constant>
1378 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SWAP_BYTES
</constant>
1381 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_LSB_FIRST
</constant>
1384 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_ROW_LENGTH
</constant>
1387 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant>
1390 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_ROWS
</constant>
1393 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_PIXELS
</constant>
1396 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_SKIP_IMAGES
</constant>
1399 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_UNPACK_ALIGNMENT
</constant>
1402 <refsect1 id=
"seealso"><title>See Also
</title>
1404 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry>,
1405 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
1406 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
1407 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
1408 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
1409 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
1410 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
1411 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
1412 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
1413 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
1414 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
1415 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
1416 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>.
1419 <refsect1 id=
"Copyright"><title>Copyright
</title>
1421 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
1422 Silicon Graphics, Inc.
<trademark class=
"copyright"></trademark> 2011
1423 Khronos Group. This document is licensed under the SGI
1424 Free Software B License. For details, see
1425 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.