'\" t
.\"     Title: glPixelStore
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 03/08/2011
.\"    Manual: OpenGL 3.3
.\"    Source: OpenGL 3.3
.\"  Language: English
.\"
.TH "GLPIXELSTORE" "3G" "03/08/2011" "OpenGL 3.3" "OpenGL 3\&.3"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glPixelStore \- set pixel storage modes
.SH "C SPECIFICATION"
.HP \w'void\ glPixelStoref('u
.BI "void glPixelStoref(GLenum\ " "pname" ", GLfloat\ " "param" ");"
.HP \w'void\ glPixelStorei('u
.BI "void glPixelStorei(GLenum\ " "pname" ", GLint\ " "param" ");"
.SH "PARAMETERS"
.PP
\fIpname\fR
.RS 4
Specifies the symbolic name of the parameter to be set\&. Six values affect the packing of pixel data into memory:
\fBGL_PACK_SWAP_BYTES\fR,
\fBGL_PACK_LSB_FIRST\fR,
\fBGL_PACK_ROW_LENGTH\fR,
\fBGL_PACK_IMAGE_HEIGHT\fR,
\fBGL_PACK_SKIP_PIXELS\fR,
\fBGL_PACK_SKIP_ROWS\fR,
\fBGL_PACK_SKIP_IMAGES\fR, and
\fBGL_PACK_ALIGNMENT\fR\&. Six more affect the unpacking of pixel data
\fIfrom\fR
memory:
\fBGL_UNPACK_SWAP_BYTES\fR,
\fBGL_UNPACK_LSB_FIRST\fR,
\fBGL_UNPACK_ROW_LENGTH\fR,
\fBGL_UNPACK_IMAGE_HEIGHT\fR,
\fBGL_UNPACK_SKIP_PIXELS\fR,
\fBGL_UNPACK_SKIP_ROWS\fR,
\fBGL_UNPACK_SKIP_IMAGES\fR, and
\fBGL_UNPACK_ALIGNMENT\fR\&.
.RE
.PP
\fIparam\fR
.RS 4
Specifies the value that
\fIpname\fR
is set to\&.
.RE
.SH "DESCRIPTION"
.PP

\fBglPixelStore\fR
sets pixel storage modes that affect the operation of subsequent
\fBglReadPixels\fR()
as well as the unpacking of texture patterns (see
\fBglTexImage1D\fR(),
\fBglTexImage2D\fR(),
\fBglTexImage3D\fR(),
\fBglTexSubImage1D\fR(),
\fBglTexSubImage2D\fR(),
\fBglTexSubImage3D\fR())\&.
.PP

\fIpname\fR
is a symbolic constant indicating the parameter to be set, and
\fIparam\fR
is the new value\&. Six of the twelve storage parameters affect how pixel data is returned to client memory\&. They are as follows:
.PP
\fBGL_PACK_SWAP_BYTES\fR
.RS 4
If true, byte ordering for multibyte color components, depth components, or stencil indices is reversed\&. That is, if a four\-byte component consists of bytes
b 0,
b 1,
b 2,
b 3, it is stored in memory as
b 3,
b 2,
b 1,
b 0
if
\fBGL_PACK_SWAP_BYTES\fR
is true\&.
\fBGL_PACK_SWAP_BYTES\fR
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
\fBGL_RGB\fR
format pixel are always stored with red first, green second, and blue third, regardless of the value of
\fBGL_PACK_SWAP_BYTES\fR\&.
.RE
.PP
\fBGL_PACK_LSB_FIRST\fR
.RS 4
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\&.
.RE
.PP
\fBGL_PACK_ROW_LENGTH\fR
.RS 4
If greater than 0,
\fBGL_PACK_ROW_LENGTH\fR
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
.sp

k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a
.sp
components or indices, where
n
is the number of components or indices in a pixel,
l
is the number of pixels in a row (\fBGL_PACK_ROW_LENGTH\fR
if it is greater than 0, the
width
argument to the pixel routine otherwise),
a
is the value of
\fBGL_PACK_ALIGNMENT\fR, and
s
is the size, in bytes, of a single component (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
.sp

k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a
.sp
components or indices\&.
.sp
The word
\fIcomponent\fR
in this description refers to the nonindex values red, green, blue, alpha, and depth\&. Storage format
\fBGL_RGB\fR, for example, has three components per pixel: first red, then green, and finally blue\&.
.RE
.PP
\fBGL_PACK_IMAGE_HEIGHT\fR
.RS 4
If greater than 0,
\fBGL_PACK_IMAGE_HEIGHT\fR
defines the number of pixels in an image three\-dimensional texture volume, where ``image\*(Aq\*(Aq is defined by all pixels sharing the same third dimension index\&. 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
.sp

k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a
.sp
components or indices, where
n
is the number of components or indices in a pixel,
l
is the number of pixels in a row (\fBGL_PACK_ROW_LENGTH\fR
if it is greater than 0, the
width
argument to
\fBglTexImage3D\fR()
otherwise),
h
is the number of rows in a pixel image (\fBGL_PACK_IMAGE_HEIGHT\fR
if it is greater than 0, the
height
argument to the
\fBglTexImage3D\fR()
routine otherwise),
a
is the value of
\fBGL_PACK_ALIGNMENT\fR, and
s
is the size, in bytes, of a single component (if
a < s, then it is as if
a = s)\&.
.sp
The word
\fIcomponent\fR
in this description refers to the nonindex values red, green, blue, alpha, and depth\&. Storage format
\fBGL_RGB\fR, for example, has three components per pixel: first red, then green, and finally blue\&.
.RE
.PP
\fBGL_PACK_SKIP_PIXELS\fR, \fBGL_PACK_SKIP_ROWS\fR, and \fBGL_PACK_SKIP_IMAGES\fR
.RS 4
These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated simply by incrementing the pointer passed to
\fBglReadPixels\fR()\&. Setting
\fBGL_PACK_SKIP_PIXELS\fR
to
i
is equivalent to incrementing the pointer by
i ⁢ n
components or indices, where
n
is the number of components or indices in each pixel\&. Setting
\fBGL_PACK_SKIP_ROWS\fR
to
j
is equivalent to incrementing the pointer by
j ⁢ m
components or indices, where
m
is the number of components or indices per row, as just computed in the
\fBGL_PACK_ROW_LENGTH\fR
section\&. Setting
\fBGL_PACK_SKIP_IMAGES\fR
to
k
is equivalent to incrementing the pointer by
k ⁢ p, where
p
is the number of components or indices per image, as computed in the
\fBGL_PACK_IMAGE_HEIGHT\fR
section\&.
.RE
.PP
\fBGL_PACK_ALIGNMENT\fR
.RS 4
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)\&.
.RE
.PP
The other six of the twelve storage parameters affect how pixel data is read from client memory\&. These values are significant for
\fBglTexImage1D\fR(),
\fBglTexImage2D\fR(),
\fBglTexImage3D\fR(),
\fBglTexSubImage1D\fR(),
\fBglTexSubImage2D\fR(), and
\fBglTexSubImage3D\fR()
.PP
They are as follows:
.PP
\fBGL_UNPACK_SWAP_BYTES\fR
.RS 4
If true, byte ordering for multibyte color components, depth components, or stencil indices is reversed\&. That is, if a four\-byte component consists of bytes
b 0,
b 1,
b 2,
b 3, it is taken from memory as
b 3,
b 2,
b 1,
b 0
if
\fBGL_UNPACK_SWAP_BYTES\fR
is true\&.
\fBGL_UNPACK_SWAP_BYTES\fR
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
\fBGL_RGB\fR
format pixel are always stored with red first, green second, and blue third, regardless of the value of
\fBGL_UNPACK_SWAP_BYTES\fR\&.
.RE
.PP
\fBGL_UNPACK_LSB_FIRST\fR
.RS 4
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\&.
.RE
.PP
\fBGL_UNPACK_ROW_LENGTH\fR
.RS 4
If greater than 0,
\fBGL_UNPACK_ROW_LENGTH\fR
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
.sp

k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a
.sp
components or indices, where
n
is the number of components or indices in a pixel,
l
is the number of pixels in a row (\fBGL_UNPACK_ROW_LENGTH\fR
if it is greater than 0, the
width
argument to the pixel routine otherwise),
a
is the value of
\fBGL_UNPACK_ALIGNMENT\fR, and
s
is the size, in bytes, of a single component (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
.sp

k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a
.sp
components or indices\&.
.sp
The word
\fIcomponent\fR
in this description refers to the nonindex values red, green, blue, alpha, and depth\&. Storage format
\fBGL_RGB\fR, for example, has three components per pixel: first red, then green, and finally blue\&.
.RE
.PP
\fBGL_UNPACK_IMAGE_HEIGHT\fR
.RS 4
If greater than 0,
\fBGL_UNPACK_IMAGE_HEIGHT\fR
defines the number of pixels in an image of a three\-dimensional texture volume\&. Where ``image\*(Aq\*(Aq is defined by all pixel sharing the same third dimension index\&. 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
.sp

k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a
.sp
components or indices, where
n
is the number of components or indices in a pixel,
l
is the number of pixels in a row (\fBGL_UNPACK_ROW_LENGTH\fR
if it is greater than 0, the
width
argument to
\fBglTexImage3D\fR()
otherwise),
h
is the number of rows in an image (\fBGL_UNPACK_IMAGE_HEIGHT\fR
if it is greater than 0, the
height
argument to
\fBglTexImage3D\fR()
otherwise),
a
is the value of
\fBGL_UNPACK_ALIGNMENT\fR, and
s
is the size, in bytes, of a single component (if
a < s, then it is as if
a = s)\&.
.sp
The word
\fIcomponent\fR
in this description refers to the nonindex values red, green, blue, alpha, and depth\&. Storage format
\fBGL_RGB\fR, for example, has three components per pixel: first red, then green, and finally blue\&.
.RE
.PP
\fBGL_UNPACK_SKIP_PIXELS\fR and \fBGL_UNPACK_SKIP_ROWS\fR
.RS 4
These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated by incrementing the pointer passed to
\fBglTexImage1D\fR(),
\fBglTexImage2D\fR(),
\fBglTexSubImage1D\fR()
or
\fBglTexSubImage2D\fR()\&. Setting
\fBGL_UNPACK_SKIP_PIXELS\fR
to
i
is equivalent to incrementing the pointer by
i ⁢ n
components or indices, where
n
is the number of components or indices in each pixel\&. Setting
\fBGL_UNPACK_SKIP_ROWS\fR
to
j
is equivalent to incrementing the pointer by
j ⁢ k
components or indices, where
k
is the number of components or indices per row, as just computed in the
\fBGL_UNPACK_ROW_LENGTH\fR
section\&.
.RE
.PP
\fBGL_UNPACK_ALIGNMENT\fR
.RS 4
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)\&.
.RE
.PP
The following table gives the type, initial value, and range of valid values for each storage parameter that can be set with
\fBglPixelStore\fR\&.
.PP
.TS
allbox tab(:);
lB cB cB cB.
T{
\fB
                        \fR\fB\fIpname\fR\fR\fB
                        \fR
T}:T{
\fB
                        Type
                        \fR
T}:T{
\fB
                        Initial Value
                        \fR
T}:T{
\fB
                        Valid Range
                        \fR
T}
.T&
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c
l c c c.
T{
\fBGL_PACK_SWAP_BYTES\fR
T}:T{
boolean
T}:T{
false
T}:T{
true or false
T}
T{
\fBGL_PACK_LSB_FIRST\fR
T}:T{
boolean
T}:T{
false
T}:T{
true or false
T}
T{
\fBGL_PACK_ROW_LENGTH\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_PACK_IMAGE_HEIGHT\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_PACK_SKIP_ROWS\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_PACK_SKIP_PIXELS\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_PACK_SKIP_IMAGES\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_PACK_ALIGNMENT\fR
T}:T{
integer
T}:T{
4
T}:T{
1, 2, 4, or 8
T}
T{
\fBGL_UNPACK_SWAP_BYTES\fR
T}:T{
boolean
T}:T{
false
T}:T{
true or false
T}
T{
\fBGL_UNPACK_LSB_FIRST\fR
T}:T{
boolean
T}:T{
false
T}:T{
true or false
T}
T{
\fBGL_UNPACK_ROW_LENGTH\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_UNPACK_IMAGE_HEIGHT\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_UNPACK_SKIP_ROWS\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_UNPACK_SKIP_PIXELS\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_UNPACK_SKIP_IMAGES\fR
T}:T{
integer
T}:T{
0
T}:T{
0
T}
T{
\fBGL_UNPACK_ALIGNMENT\fR
T}:T{
integer
T}:T{
4
T}:T{
1, 2, 4, or 8
T}
.TE
.sp 1
.PP

\fBglPixelStoref\fR
can be used to set any pixel store parameter\&. If the parameter type is boolean, then if
\fIparam\fR
is 0, the parameter is false; otherwise it is set to true\&. If
\fIpname\fR
is a integer type parameter,
\fIparam\fR
is rounded to the nearest integer\&.
.PP
Likewise,
\fBglPixelStorei\fR
can also be used to set any of the pixel store parameters\&. Boolean parameters are set to false if
\fIparam\fR
is 0 and true otherwise\&.
.SH "ERRORS"
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fIpname\fR
is not an accepted value\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if a negative row length, pixel skip, or row skip value is specified, or if alignment is specified as other than 1, 2, 4, or 8\&.
.SH "ASSOCIATED GETS"
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_SWAP_BYTES\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_LSB_FIRST\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_ROW_LENGTH\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_IMAGE_HEIGHT\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_SKIP_ROWS\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_SKIP_PIXELS\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_SKIP_IMAGES\fR
.PP

\fBglGet\fR()
with argument
\fBGL_PACK_ALIGNMENT\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_SWAP_BYTES\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_LSB_FIRST\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_ROW_LENGTH\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_IMAGE_HEIGHT\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_SKIP_ROWS\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_SKIP_PIXELS\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_SKIP_IMAGES\fR
.PP

\fBglGet\fR()
with argument
\fBGL_UNPACK_ALIGNMENT\fR
.SH "SEE ALSO"
.PP

\fBglReadPixels\fR(),
\fBglTexImage1D\fR(),
\fBglTexImage2D\fR(),
\fBglTexImage3D\fR(),
\fBglTexSubImage1D\fR(),
\fBglTexSubImage2D\fR(),
\fBglTexSubImage3D\fR()
.SH "COPYRIGHT"
.PP
Copyright
\(co
1991\-2006 Silicon Graphics, Inc\&. This document is licensed under the SGI Free Software B License\&. For details, see
\m[blue]\fBhttp://oss\&.sgi\&.com/projects/FreeB/\fR\m[]\&.