glPixelStore(3G) OpenGL Reference glPixelStore(3G)
NAME
glPixelStoref, glPixelStorei - set pixel storage modes
C SPECIFICATION
void glPixelStoref( GLenum pname,
GLfloat param )
void glPixelStorei( GLenum pname,
GLint param )
PARAMETERS
pname Specifies the symbolic name of the parameter to be set. Ten
values affect the packing of pixel data into client memory:
GLPACKSWAPBYTES, GLPACKLSBFIRST, GLPACKROWLENGTH,
GLPACKSKIPPIXELS, GLPACKSKIPROWS, GLPACKALIGNMENT,
GLPACKIMAGEHEIGHTEXT, GLPACKIMAGEDEPTHSGIS,
GLPACKSKIPIMAGESEXT, and GLPACKSKIPVOLUMESSGIS.
Ten more affect the unpacking of pixel data from client memory:
GLUNPACKSWAPBYTES, GLUNPACKLSBFIRST, GLUNPACKROWLENGTH,
GLUNPACKSKIPPIXELS, GLUNPACKSKIPROWS, GLUNPACKALIGNMENT,
GLUNPACKIMAGEHEIGHTEXT, GLUNPACKIMAGEDEPTHSGIS,
GLUNPACKSKIPIMAGESEXT, and GLUNPACKSKIPVOLUMESSGIS.
param Specifies the value that pname is set to.
DESCRIPTION
glPixelStore sets pixel storage modes that affect the operation of
subsequent commands which unpack pixel data from client memory and which
pack pixel data into client memory. Pixel data is unpacked from client
memory during glDrawPixels commands and when specifying bitmaps (see
glBitmap), polygon stipple patterns (see glPolygonStipple), color tables
(see glColorTableSGI), convolution filters (see glConvolutionFilter1DEXT,
glConvolutionFilter2DEXT, and glSeparableFilter2DEXT), and texture
patterns (see glTexImage1D, glTexSubImage1DEXT, glTexImage2D,
glTexSubImage2DEXT, glTexImage3DEXT, glTexSubImage3DEXT,
glTexImage4DSGIS, and glTexSubImage4DSGIS). Pixel data is packed into
client memory during glReadPixels commands and when querying polygon
stipple patterns (see glGetPolygonStipple), color tables (see
glGetColorTableSGI), convolution filters (see glGetConvolutionFilterEXT
and glGetSeparableFilterEXT), texture patterns (see glGetTexImage),
histogram results (see glGetHistogramEXT), and minmax results (see
glGetMinmaxEXT);
When pixel data is unpacked from client memory, the interpretation of the
data in memory is controlled by the unpack parameters to glPixelStore and
by the type, format, and size arguments to the pixel command (for
example, by the width and height parameters to glDrawPixels). The pixel
format specifies that each pixel consists of either a single index value,
a single depth component, or one, two, three or four color components.
Page 1
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
Unless packed pixel formats are used, the type argument to the command
specifies that the elements of a pixel are to be read from memory as a
sequence of signed or unsigned bytes, shorts, or integers, or single-
precision floating-point values. Packed pixel types allow all the
elements of each pixel to be read from a single unsigned byte, unsigned
short, or unsigned int. (See glDrawPixels for more information.) In the
case of glBitmap and glPolygonStipple, the pixel format is inferred to be
GLCOLORINDEX and the type is inferred to be GLBITMAP.
When commands which pack data into client memory (for example,
glReadPixels or glGetTexImage) are called, pixels are written into client
memory as specified by the unpack state specified by glPixelStore and by
the type, format, and size arguments to the command. In a manner similar
to that of glDrawPixels, the pixel format determines the components of
each pixel and the pixel type indicates the data type and whether or not
the pixels are packed into memory. (See glReadPixels for more
information.) In the case of glGetPolygonStipple the pixel format is
inferred to be GLCOLORINDEX and the type is inferred to be GLBITMAP.
pname is a symbolic constant indicating the parameter to be set, and
param is the new value. The parameters GLPACKLSBFIRST,
GLUNPACKLSBFIRST, GLPACKSWAPBYTES, and GLUNPACKSWAPBYTES specify
the arrangement of bits within bytes or bytes within words of an image.
These parameters are described in detail below. The other parameters are
typically used when a subregion of a larger image in client memory is
being written or read by the GL. The parameters GLPACKROWLENGTH,
GLUNPACKROWLENGTH, GLPACKIMAGEHEIGHTEXT,
GLUNPACKIMAGEHEIGHTEXT, GLPACKIMAGEDEPTHSGIS, and
GLUNPACKIMAGEDEPTHSGIS are used specify the dimensions of the entire
client image. GLPACKALIGNMENT and GLUNPACKALIGNMENT are used to
specify the alignment in memory of the start of each row of the client
image. GLPACKSKIPPIXELS, GLUNPACKSKIPPIXELS, GLPACKSKIPROWS,
GLUNPACKSKIPROWS, GLPACKSKIPIMAGESEXT, GLUNPACKSKIPIMAGESEXT,
GLPACKSKIPVOLUMESSGIS, and GLUNPACKSKIPVOLUMESSGIS are used to
specify the location of the subregion which is to be read or written by
subsequent GL commands. These offsets describe the lower left corner of
the first image of the first volume. The size of the subregion is
specified by arguments to the GL command which will transfer the pixels.
A pointer passed into the routine (referred to in this document as p)
gives the location in client memory of the lower left corner of the large
image. More detailed and rigorous descriptions of each parameter may be
found below. Note that specifying a subregion of a larger image is a
common use of these parameters, but they are often useful in other
situations. For example, GLPACKROWLENGTH may be set to twice the
width of the image to select every other line of an image in an
application using interlacing.
Ten of the twenty storage parameters affect how pixel data is returned to
client memory, and are therefore significant for glReadPixels,
glGetTexImage, glGetColorTableSGI, glGetConvolutionFilterEXT,
glGetPolygonStipple, glGetSeparableFilterEXT, glGetHistogramEXT, and
glGetMinmaxEXT commands. These parameters are as follows:
Page 2
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
GLPACKSWAPBYTES
If true, byte swapping is performed as the data is written to
client memory. For pixels that aren't packed, byte ordering
for multibyte color components, depth components, color
indices, or stencil indices is reversed. That is, if a four-
byte component is made up of bytes b , b , b , b , it is stored
0 1 2 3
in memory as b , b , b , b . In the case of the packed pixel
3 2 1 0
types, byte swapping is performed before the elements are
extracted from each pixel.
GLPACKLSBFIRST
If true, bits are ordered within a byte from least significant
to most significant; otherwise, the first bit in each byte is
the most significant one. This parameter is significant for
bitmap data only.
GLPACKROWLENGTH
If greater than zero, GLPACKROWLENGTH defines the number of
pixels in a row. If the first pixel of a row is placed at
location p in memory, then the location of the first pixel of
the next row is obtained by skipping
i = a * ceiling(s*w / a)
bytes, where s is the size in bytes of a pixel (equal to the
number of components in a pixel multiplied by the size in bytes
of a component for non-packed pixel types, or to the size in
bytes of a complete pixel for packed pixel types), w is the
number of pixels in a row (as specified with GLPACKROWLENGTH
if it is greater than zero, the width argument to the pixel
routine otherwise), and a is the value of GLPACKALIGNMENT.
If a<s, then it is as if a=s. In the case of 1-bit values, the
location of the next row is obtained by skipping
i = 8 * a * ceiling(s*w / 8*a)
bytes.
The word component in this description refers to the nonindex
values red, green, blue, alpha, and depth. Storage format
GLRGB, for example, has three components per pixel: first
red, then green, and finally blue.
GLPACKIMAGEHEIGHTEXT
If greater than zero, GLPACKIMAGEHEIGHTEXT defines the
number of rows in an image. If the first pixel of an image is
placed at location p in memory, then the location of the first
pixel of the next image is obtained by skipping
j=ih
elements, where i is the offset from the beginning of one row
Page 3
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
in an image to the beginning of the next row in the image (as
described in the GLPACKROWLENGTH section) and h is the
height of the image. h is equal the value specified with
GLPACKIMAGEHEIGHTEXT if this value is greater than zero and
is equal to the height argument to the pixel routine otherwise.
If the routine has no height argument and the height was not
specified with GLPACKIMAGEHEIGHTEXT (or was specified as
zero), h is the height of the data to be returned.
GLPACKIMAGEDEPTHSGIS
If greater than zero, GLPACKIMAGEDEPTHSGIS defines the
number of images in a volume. If the first pixel of a volume
is placed at location p in memory, then the location of the
first pixel of the next volume is obtained by skipping
k=jd
bytes, where j is the offset from the beginning of one image to
the beginning of the next image (as described in the
GLPACKIMAGEHEIGHTEXT section) and d is the depth of the
image. d is equal to the value specified with
GLPACKIMAGEDEPTHSGIS if this value is greater than zero and
is equal to the depth argument to the pixel routine otherwise.
If the routine has no depth argument and the depth was not
specified with GLPACKIMAGEDEPTHSGIS (or was specified as
zero), d is the depth of the data to be returned.
GLPACKSKIPPIXELS and GLPACKSKIPROWS
These values are provided mainly as a convenience to the
programmer; except when 1-bit per pixel data is being returned,
they provide no functionality that cannot be duplicated simply
by incrementing the pointer passed to the command which is
writing pixel data to client memory. For multi-bit data types,
setting GLPACKSKIPPIXELS to l is equivalent to incrementing
the pointer just once by sl bytes, where s is the number of
bytes in each pixel (as described above in the
GLPACKROWLENGTH section). Setting GLPACKSKIPROWS to m is
equivalent to incrementing the pointer just once by im bytes,
where i is the number of bytes per row, as computed above in
the GLPACKROWLENGTH section.
When 1-bit (GLBITMAP) data is being written to client memory,
setting GLPACKSKIPPIXELS to l is equivalent to incrementing
the pointer just once by floor(l/8) bytes. For each row of the
image, the data returned will begin at bit l%8 of the byte,
where 0 is the most significant bit. Other bits will be left
unchanged.
Note that the adjustment to the pointer takes place just once,
before the start of the pixel transfer; specifying a value of
one for GLPACKSKIPROWS does not cause every other row of the
image to be skipped.
Page 4
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
GLPACKSKIPIMAGESEXT
Setting GLPACKSKIPIMAGESEXT to n is equivalent to
incrementing the pointer passed to the command just once by jn
bytes, where j is the number of bytes per image, as computed
above in the GLPACKIMAGEHEIGHTEXT section. The offset
specified by GLPACKSKIPIMAGESEXT is applied only to data of
three or more dimensions. The offset is applied in addition to
the offsets specified by GLPACKSKIPPIXELS and
GLPACKSKIPROWS as described above.
GLPACKSKIPVOLUMESSGIS
Setting GLPACKSKIPVOLUMESSGIS to o is equivalent to
incrementing the pointer passed to the command just once by ko
bytes, where k is the number of bytes per volume, as computed
in the GLPACKIMAGEDEPTHSGIS section. The offset specified
by GLPACKSKIPVOLUMESSGIS is applied only to data of four or
more dimensions.
GLPACKALIGNMENT
Specifies the alignment requirements for the start of each
pixel row in memory. The allowable values are 1 (byte-
alignment), 2 (rows aligned to even-numbered bytes), 4 (word
alignment), and 8 (rows start on double-word boundaries).
The other ten of the twenty storage parameters affect how pixel data is
read from client memory. They are as follows:
GLUNPACKSWAPBYTES
If true, byte ordering for multibyte color components, depth
components, color indices, or stencil indices is reversed. That is,
if a four-byte component is made up of bytes b , b , b , b , it is
0 1 2 3
taken from memory as b , b , b , b if GLUNPACKSWAPBYTES is true.
3 2 1 0
GLUNPACKSWAPBYTES has no effect on the memory order of components
within a pixel, only on the order of bytes within components or
indices. For example, the three components of a GLRGB format pixel
are always stored with red first, green second, and blue third,
regardless of the value of GLUNPACKSWAPBYTES.
GLUNPACKLSBFIRST
If true, bits are ordered within a byte from least significant to
most significant; otherwise, the first bit in each byte is the most
significant one. This is significant for bitmap data only.
GLUNPACKROWLENGTH
If greater than zero, GLUNPACKROWLENGTH defines the number of
pixels in a row. If the first pixel of a row is placed at location
p in memory, then the location of the first pixel of the next row is
obtained by skipping
i = a * ceiling(s*w / a)
bytes, where s is the size in bytes of a pixel (equal to the number
Page 5
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
of components in a pixel multiplied by the size in bytes of a
component for non-packed pixel types, or to the size in bytes of a
complete pixel for packed pixel types), w is the number of pixels in
a row (as specified with GLUNPACKROWLENGTH if it is greater than
zero, the width argument to the pixel routine otherwise), and a is
the value of GLUNPACKALIGNMENT. If a<s, then it is as if a=s. In
the case of 1-bit values, the location of the next row is obtained
by skipping
i = 8 * a * ceiling(s*w / 8*a)
bytes.
The word component in this description refers to the nonindex values
red, green, blue, alpha, and depth. Storage format GLRGB, for
example, has three components per pixel: first red, then green, and
finally blue.
GLUNPACKIMAGEHEIGHTEXT
If greater than zero, GLUNPACKIMAGEHEIGHTEXT defines the number
of rows in an image. If the first pixel of an image is placed at
location p in memory, then the location of the first pixel of the
next image is obtained by skipping
j=ih
elements, where i is the offset from the beginning of one row in an
image to the beginning of the next row in the image (as described in
the GLUNPACKROWLENGTH section) and h is the height of the image.
h is equal the value specified with GLPACKIMAGEHEIGHTEXT if this
value is greater than zero and is equal to the height argument to
the pixel routine otherwise. If the routine has no height argument
and the height was not specified with GLPACKIMAGEHEIGHTEXT (or
was specified as zero), h is the height of the data to be
downloaded.
GLUNPACKIMAGEDEPTHSGIS
If greater than zero, GLUNPACKIMAGEDEPTHSGIS defines the number
of images in a volume. If the first pixel of a volume is placed at
location p in memory, then the location of the first pixel of the
next volume is obtained by skipping
k=jd
bytes, where j is the offset from the beginning of one image to the
beginning of the next image (as described in the
GLUNPACKIMAGEHEIGHTEXT section) and d is the depth of the image.
d is equal to the value specified with GLUNPACKIMAGEDEPTHSGIS if
this value is greater than zero and is equal to the depth argument
to the pixel routine otherwise. If the routine has no depth
argument and the depth was not specified with
GLPACKIMAGEDEPTHSGIS (or was specified as zero), d is the depth
Page 6
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
of the data to be downloaded.
GLUNPACKSKIPPIXELS and GLUNPACKSKIPROWS
These values are provided mainly as a convenience to the programmer;
except when 1-bit per pixel data is being specified, they provide no
functionality that cannot be duplicated simply by incrementing the
pointer p passed to the command which is reading pixel data from
client memory. For multi-bit data types, setting
GLUNPACKSKIPPIXELS to l is equivalent to incrementing the pointer
just once by sl bytes, where s is the number of bytes in each pixel
(as described above in the GLUNPACKROWLENGTH section). Setting
GLUNPACKSKIPROWS to m is equivalent to incrementing the pointer
just once by im bytes, where i is the number of bytes per row, as
computed above in the GLUNPACKROWLENGTH section.
When 1-bit (GLBITMAP) data is being read, setting
GLUNPACKSKIPPIXELS to l is equivalent to incrementing the pointer
just once by floor(l/8) bytes. For each row of the image, the image
data read will begin at bit l%8 of the byte, where 0 is the most
significant bit. Other bits of the byte will be ignored.
Note that the adjustment to the pointer takes place just once,
before the start of the pixel transfer; specifying a value of one
for GLUNPACKSKIPROWS does not cause every other row of the image
to be skipped.
GLUNPACKSKIPIMAGESEXT
Setting GLUNPACKSKIPIMAGESEXT to n is equivalent to incrementing
the pointer passed to the routine just once by jn bytes, where j is
the number of bytes per image, as computed above in the
GLUNPACKIMAGEHEIGHTEXT section. The offset specified by
GLUNPACKSKIPIMAGESEXT is applied only to data of three or more
dimensions. The offset is applied in addition to the offsets
specified by GLUNPACKSKIPPIXELS and GLUNPACKSKIPROWS as
described above.
GLUNPACKSKIPVOLUMESSGIS
Setting GLUNPACKSKIPVOLUMESSGIS to o is equivalent to
incrementing the pointer passed just once by ko bytes, where k is
the number of bytes per volume, as computed in the
GLUNPACKIMAGEDEPTHSGIS section. The offset specified by
GLUNPACKSKIPVOLUMESSGIS is applied only to data of four or more
dimensions. The offset is applied in addition to the offsets
specified by GLUNPACKSKIPPIXELS, GLUNPACKSKIPROWS, and
GLUNPACKSKIPIMAGESEXT as described above.
GLUNPACKALIGNMENT
Specifies the alignment requirements for the start of each pixel row
in memory. The allowable values are 1 (byte-alignment), 2 (rows
aligned to even-numbered bytes), 4 (word alignment), and 8 (rows
start on double-word boundaries).
Page 7
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
The following table gives the type, initial value, and range of valid
values for each of the storage parameters that can be set with
glPixelStore.
pname type initial value valid range
_____________________________________________________________________
GLPACKSWAPBYTES Boolean false true or false
GLPACKLSBFIRST Boolean false true or false
GLPACKROWLENGTH integer 0 [0,oo)
GLPACKSKIPROWS integer 0 [0,oo)
GLPACKSKIPPIXELS integer 0 [0,oo)
GLPACKALIGNMENT integer 4 1, 2, 4, or 8
GLPACKIMAGEHEIGHTEXT integer 0 [0,oo)
GLPACKIMAGEDEPTHSGIS integer 0 [0,oo)
GLPACKSKIPIMAGESEXT integer 0 [0,oo)
GLPACKSKIPVOLUMESSGIS integer 0 [0,oo)
_____________________________________________________________________
GLUNPACKSWAPBYTES Boolean false true or false
GLUNPACKLSBFIRST Boolean false true or false
GLUNPACKROWLENGTH integer 0 [0,oo)
GLUNPACKSKIPROWS integer 0 [0,oo)
GLUNPACKSKIPPIXELS integer 0 [0,oo)
GLUNPACKALIGNMENT integer 4 1, 2, 4, or 8
GLUNPACKIMAGEHEIGHTEXT integer 0 [0,oo)
GLUNPACKIMAGEDEPTHSGIS integer 0 [0,oo)
GLUNPACKSKIPIMAGESEXT integer 0 [0,oo)
GLUNPACKSKIPVOLUMESSGIS integer 0 [0,oo)
glPixelStoref can be used to set any pixel store parameter. If the
parameter type is Boolean, then if param is 0.0, the parameter is false;
otherwise it is set to true. If pname is a integer type parameter, param
is rounded to the nearest integer.
Likewise, glPixelStorei can also be used to set any of the pixel store
parameters. Boolean parameters are set to false if param is 0 and true
otherwise.
NOTES
The pixel storage modes in effect when commands which read pixel data
from client memory (glDrawPixels, glTexImage1D etc) are placed in a
display list control the interpretation of memory data. The pixel
storage modes in effect when a display list is executed are not
significant.
ERRORS
GLINVALIDENUM is generated if pname is not an accepted value.
GLINVALIDVALUE is generated if a negative row length, pixel skip, row
skip, image height, image skip, image depth, or volume skip value is
specified, or if alignment is specified as other than 1, 2, 4, or 8.
Page 8
glPixelStore(3G) OpenGL Reference glPixelStore(3G)
GLINVALIDOPERATION is generated if glPixelStore is executed between the
execution of glBegin and the corresponding execution of glEnd.
ASSOCIATED GETS
glGet with argument GLPACKSWAPBYTES
glGet with argument GLPACKLSBFIRST
glGet with argument GLPACKROWLENGTH
glGet with argument GLPACKSKIPROWS
glGet with argument GLPACKSKIPPIXELS
glGet with argument GLPACKALIGNMENT
glGet with argument GLPACKIMAGEHEIGHTEXT
glGet with argument GLPACKIMAGEDEPTHSGIS
glGet with argument GLPACKSKIPIMAGESEXT
glGet with argument GLPACKSKIPVOLUMESSGIS
glGet with argument GLUNPACKSWAPBYTES
glGet with argument GLUNPACKLSBFIRST
glGet with argument GLUNPACKROWLENGTH
glGet with argument GLUNPACKSKIPROWS
glGet with argument GLUNPACKSKIPPIXELS
glGet with argument GLUNPACKALIGNMENT
glGet with argument GLUNPACKIMAGEHEIGHTEXT
glGet with argument GLUNPACKIMAGEDEPTHSGIS
glGet with argument GLUNPACKSKIPIMAGESEXT
glGet with argument GLUNPACKSKIPVOLUMESSGIS
SEE ALSO
glBitmap, glColorTableSGI, glConvolutionFilter1DEXT,
glConvolutionFilter2DEXT, glDrawPixels, glPixelMap, glPixelTransfer,
glPixelZoom, glPolygonStipple, glReadPixels, glSeparableFilter2DEXT,
glTexImage1D, glTexImage2D, glTexImage3DEXT, glTexImage4DSGIS,
glTexSubImage1DEXT, glTexSubImage2DEXT, glTexSubImage3DEXT,
glTexSubImage4DSGIS
Page 9