NAME
glPixelStoref, glPixelStorei
- set pixel storage modes
C SPECIFICATION
void ggllPPiixxeellSSttoorreeff(
GLenum _p_n_a_m_e,
GLfloat _p_a_r_a_m )
void ggllPPiixxeellSSttoorreeii(
GLenum _p_n_a_m_e,
GLint _p_a_r_a_m )
delim $$
PARAMETERS
-
_p_n_a_m_e
-
Specifies the symbolic name of the parameter to be set.
Six values affect the packing of pixel data into memory:
GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS,
GGLL__PPAACCKK__LLSSBB__FFIIRRSSTT,
GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH,
GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT,
GGLL__PPAACCKK__SSKKIIPP__PPIIXXEELLSS,
GGLL__PPAACCKK__SSKKIIPP__RROOWWSS,
GGLL__PPAACCKK__SSKKIIPP__IIMMAAGGEESS, and
GGLL__PPAACCKK__AALLIIGGNNMMEENNTT.
Six more affect the unpacking of pixel data _f_r_o_m memory:
GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS,
GGLL__UUNNPPAACCKK__LLSSBB__FFIIRRSSTT,
GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH,
GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT,
GGLL__UUNNPPAACCKK__SSKKIIPP__PPIIXXEELLSS,
GGLL__UUNNPPAACCKK__SSKKIIPP__RROOWWSS,
GGLL__UUNNPPAACCKK__SSKKIIPP__IIMMAAGGEESS, and
GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT.
-
_p_a_r_a_m
-
Specifies the value that _p_n_a_m_e is set to.
DESCRIPTION
ggllPPiixxeellSSttoorree sets pixel storage modes that affect the operation of subsequent
ggllDDrraawwPPiixxeellss and ggllRReeaaddPPiixxeellss as well as the unpacking of
polygon stipple patterns (see ggllPPoollyyggoonnSSttiippppllee), bitmaps (see
ggllBBiittmmaapp), texture patterns (see ggllTTeexxIImmaaggee11DD,
ggllTTeexxIImmaaggee22DD, ggllTTeexxIImmaaggee33DD, ggllTTeexxSSuubbIImmaaggee11DD,
ggllTTeexxSSuubbIImmaaggee22DD, ggllTTeexxSSuubbIImmaaggee33DD).
Additionally, if the GGLL__AARRBB__iimmaaggiinngg extension is supported, pixle
storage modes affect convlution filters
(see ggllCCoonnvvoolluuttiioonnFFiilltteerr11DD, ggllCCoonnvvoolluuttiioonnFFiilltteerr22DD, and
ggllSSeeppaarraabblleeFFiilltteerr22DD, color table (see ggllCCoolloorrTTaabbllee, and
ggllCCoolloorrSSuubbTTaabbllee, and unpacking histogram (See ggllHHiissttooggrraamm),
and minmax (See ggllMMiinnmmaaxx) data.
_p_n_a_m_e is a symbolic constant indicating the parameter to be set, and
_p_a_r_a_m is the new value. Six of the twelve storage parameters affect
how pixel data is returned to client memory.
They are as follows:
-
GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS
-
If true,
byte ordering for multibyte color components,
depth components,
color indices,
or stencil indices
is reversed.
That is,
if a four-byte component consists of bytes
$b sub 0$,
$b sub 1$,
$b sub 2$,
$b sub 3$,
it is stored in memory as
$b sub 3$,
$b sub 2$,
$b sub 1$,
$b sub 0$
if GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS is true.
GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS 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 GGLL__RRGGBB pixel are always stored with
red first,
green second,
and blue third,
regardless of the value of GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS.
-
GGLL__PPAACCKK__LLSSBB__FFIIRRSSTT
-
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.
-
GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH
-
If greater than 0,
GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH 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
$k ~=~~ left { ^ lpile { n l above {a over s left ceiling { s n l } over a right ceiling}} ~~ lpile {s ~>=~ a above s ~<~ a }$
components or indices,
where $n$ is the number of components or indices in a pixel,
$l$ is the number of pixels in a row
(GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH if it is greater than 0,
the $width$ argument to the pixel routine otherwise),
$a$ is the value of GGLL__PPAACCKK__AALLIIGGNNMMEENNTT, 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
$k ~=~ 8 a left ceiling { n l } over { 8 a } ^ right ceiling$
components or indices.
-
The word _c_o_m_p_o_n_e_n_t in this description refers to the nonindex values
-
red,
green,
blue,
alpha,
and depth.
Storage GGLL__RRGGBB,
for example,
has three components per pixel:
first red,
then green,
and finally blue.
-
GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT
-
If greater than 0,
GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT defines the number of pixels in an image
three-dimensional texture volume.
Where ``image'' 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
$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 }$
components or indices, where $n$ is the number of components or indices
in a pixel, $l$ is the number of pixels in a row
(GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH if it is greater than 0, the
$width$ argument to ggllTTeexxIImmaaggee33dd otherwise), $h$ is the number of
rows in a pixel image (GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT if it is greater than
0, the $height$ argument to the ggllTTeexxIImmaaggee33DD routine otherwise),
$a$ is the value of
GGLL__PPAACCKK__AALLIIGGNNMMEENNTT, and $s$ is the size, in bytes, of a single
component (if $ a < s$, then it is as if $a = s$).
-
The word _c_o_m_p_o_n_e_n_t in this description refers to the nonindex values
-
red,
green,
blue,
alpha,
and depth.
Storage GGLL__RRGGBB,
for example,
has three components per pixel:
first red,
then green,
and finally blue.
-
GGLL__PPAACCKK__SSKKIIPP__PPIIXXEELLSS, GGLL__PPAACCKK__SSKKIIPP__RROOWWSS, and GGLL__PPAACCKK__SSKKIIPP__IIMMAAGGEESS
-
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 ggllRReeaaddPPiixxeellss.
Setting GGLL__PPAACCKK__SSKKIIPP__PPIIXXEELLSS 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 GGLL__PPAACCKK__SSKKIIPP__RROOWWSS 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 GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH section.
Setting GGLL__PPAACCKK__SSKKIIPP__IIMMAAGGEESS 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 GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT section.
-
GGLL__PPAACCKK__AALLIIGGNNMMEENNTT
-
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 six of the twelve storage parameters affect how pixel data is
read from client memory.
These values are significant for ggllDDrraawwPPiixxeellss,
ggllTTeexxIImmaaggee11DD,
ggllTTeexxIImmaaggee22DD,
ggllTTeexxIImmaaggee33DD,
ggllTTeexxSSuubbIImmaaggee11DD,
ggllTTeexxSSuubbIImmaaggee22DD,
ggllTTeexxSSuubbIImmaaggee33DD,
ggllBBiittmmaapp, and
ggllPPoollyyggoonnSSttiippppllee.
Additionally, if the GGLL__AARRBB__iimmaaggiinngg extension is supported,
ggllCCoolloorrTTaabbllee,
ggllCCoolloorrSSuubbTTaabbllee,
ggllCCoonnvvoolluuttiioonnFFiilltteerr11DD,
ggllCCoonnvvoolluuttiioonnFFiilltteerr22DD, and
ggllSSeeppaarraabblleeFFiilltteerr22DD.
They are as follows:
-
GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS
-
If true,
byte ordering for multibyte color components,
depth components,
color indices,
or stencil indices
is reversed.
That is,
if a four-byte component consists of bytes
$b sub 0$,
$b sub 1$,
$b sub 2$,
$b sub 3$,
it is taken from memory as
$b sub 3$,
$b sub 2$,
$b sub 1$,
$b sub 0$
if GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS is true.
GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS 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 GGLL__RRGGBB pixel are always stored with
red first,
green second,
and blue third,
regardless of the value of GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS.
-
GGLL__UUNNPPAACCKK__LLSSBB__FFIIRRSSTT
-
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 relevant only for bitmap data.
-
GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH
-
If greater than 0,
GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH 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
$k ~=~~ left { ~ lpile { n l above {a over s left ceiling { s n l }
over a ^ right ceiling}} ~~ lpile {s ~>=~ a above s ~<~ a }$
components or indices,
where $n$ is the number of components or indices in a pixel,
$l$ is the number of pixels in a row
(GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH if it is greater than 0,
the $width$ argument to the pixel routine otherwise),
$a$ is the value of GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT, 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
$k ~=~ 8 a left ceiling { n l } over { 8 a } right ceiling$
components or indices.
-
The word _c_o_m_p_o_n_e_n_t in this description refers to the nonindex values
-
red,
green,
blue,
alpha,
and depth.
Storage GGLL__RRGGBB,
for example,
has three components per pixel:
first red,
then green,
and finally blue.
-
GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT
-
If greater than 0,
GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT defines the number of pixels in an image of
a three-dimensional texture volume. Where ``image'' 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
$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 }$
components or indices,
where $n$ is the number of components or indices in a pixel,
$l$ is the number of pixels in a row
(GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH if it is greater than 0,
the $width$ argument to ggllTTeexxIImmaaggee33DD otherwise),
$h$ is the number of rows in an image (GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT if
it is greater than 0, the $height$ argument to ggllTTeexxIImmaaggee33DD otherwise),
$a$ is the value of GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT, and
$s$ is the size, in bytes, of a single component
(if $ a < s$, then it is as if $a ~=~ s$).
-
The word _c_o_m_p_o_n_e_n_t in this description refers to the nonindex values
-
red,
green,
blue,
alpha,
and depth.
Storage GGLL__RRGGBB,
for example,
has three components per pixel:
first red,
then green,
and finally blue.
-
GGLL__UUNNPPAACCKK__SSKKIIPP__PPIIXXEELLSS and GGLL__UUNNPPAACCKK__SSKKIIPP__RROOWWSS
-
These values are provided as a convenience to the programmer;
they provide no functionality that cannot be duplicated by
incrementing the pointer passed to
ggllDDrraawwPPiixxeellss,
ggllTTeexxIImmaaggee11DD,
ggllTTeexxIImmaaggee22DD,
ggllTTeexxSSuubbIImmaaggee11DD,
ggllTTeexxSSuubbIImmaaggee22DD,
ggllBBiittmmaapp, or
ggllPPoollyyggoonnSSttiippppllee.
Setting GGLL__UUNNPPAACCKK__SSKKIIPP__PPIIXXEELLSS 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 GGLL__UUNNPPAACCKK__SSKKIIPP__RROOWWSS 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 GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH section.
-
GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT
-
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 following table gives the type,
initial value,
and range of valid values for each storage parameter
that can be set with ggllPPiixxeellSSttoorree.
center tab(:) delim($$) ;
lb cb cb cb
l c c c.
_
_p_n_a_m_e:Type:Initial Value:Valid Range
_
GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS:boolean:false:true or false
GGLL__PPAACCKK__LLSSBB__FFIIRRSSTT:boolean:false:true or false
GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH:integer:0:[0,)
GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT:integer:0:[0, )
GGLL__PPAACCKK__SSKKIIPP__RROOWWSS:integer:0:[0,)
GGLL__PPAACCKK__SSKKIIPP__PPIIXXEELLSS:integer:0:[0,)
GGLL__PPAACCKK__SSKKIIPP__IIMMAAGGEESS:integer:0:[0,)
GGLL__PPAACCKK__AALLIIGGNNMMEENNTT:integer:4:1, 2, 4, or 8
_
GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS:boolean:false:true or false
GGLL__UUNNPPAACCKK__LLSSBB__FFIIRRSSTT:boolean:false:true or false
GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH:integer:0:[0,)
GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT:integer:0:[0,)
GGLL__UUNNPPAACCKK__SSKKIIPP__RROOWWSS:integer:0:[0,)
GGLL__UUNNPPAACCKK__SSKKIIPP__PPIIXXEELLSS:integer:0:[0,)
GGLL__UUNNPPAACCKK__SSKKIIPP__IIMMAAGGEESS:integer:0:[0,)
GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT:integer:4:1, 2, 4, or 8
_
ggllPPiixxeellSSttoorreeff can be used to set any pixel store parameter.
If the parameter type is boolean,
then if _p_a_r_a_m is 0,
the parameter is false;
otherwise it is set to true.
If _p_n_a_m_e is a integer type parameter,
_p_a_r_a_m is rounded to the nearest integer.
Likewise, ggllPPiixxeellSSttoorreeii can also be used to set any of the
pixel store parameters.
Boolean parameters are set to false if _p_a_r_a_m is 0 and true otherwise.
NOTES
The pixel storage modes in effect when
ggllDDrraawwPPiixxeellss,
ggllRReeaaddPPiixxeellss,
ggllTTeexxIImmaaggee11DD,
ggllTTeexxIImmaaggee22DD,
ggllTTeexxIImmaaggee33DD,
ggllTTeexxSSuubbIImmaaggee11DD,
ggllTTeexxSSuubbIImmaaggee22DD,
ggllTTeexxSSuubbIImmaaggee33DD,
ggllBBiittmmaapp,
or ggllPPoollyyggoonnSSttiippppllee is placed in a display list control the interpretation
of memory data.
Likewise, if the GGLL__AARRBB__iimmaaggiinngg extension is supported, the pixel
storage modes in effect when
ggllCCoolloorrTTaabbllee,
ggllCCoolloorrSSuubbTTaabbllee,
ggllCCoonnvvoolluuttiioonnFFiilltteerr11DD,
ggllCCoonnvvoolluuttiioonnFFiilltteerr22DD, of
ggllSSeeppaarraabblleeFFiilltteerr22DD is 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.
Pixel storage modes are client state and must be pushed and restored
using
ggllPPuusshhCClliieennttAAttttrriibb and ggllPPooppCClliieennttAAttttrriibb.
ERRORS
GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _p_n_a_m_e is not an accepted value.
GGLL__IINNVVAALLIIDD__VVAALLUUEE 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.
GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllPPiixxeellSSttoorree
is executed between the execution of ggllBBeeggiinn
and the corresponding execution of ggllEEnndd.
ASSOCIATED GETS
ggllGGeett with argument GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS
ggllGGeett with argument GGLL__PPAACCKK__LLSSBB__FFIIRRSSTT
ggllGGeett with argument GGLL__PPAACCKK__RROOWW__LLEENNGGTTHH
ggllGGeett with argument GGLL__PPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT
ggllGGeett with argument GGLL__PPAACCKK__SSKKIIPP__RROOWWSS
ggllGGeett with argument GGLL__PPAACCKK__SSKKIIPP__PPIIXXEELLSS
ggllGGeett with argument GGLL__PPAACCKK__SSKKIIPP__IIMMAAGGEESS
ggllGGeett with argument GGLL__PPAACCKK__AALLIIGGNNMMEENNTT
ggllGGeett with argument GGLL__UUNNPPAACCKK__SSWWAAPP__BBYYTTEESS
ggllGGeett with argument GGLL__UUNNPPAACCKK__LLSSBB__FFIIRRSSTT
ggllGGeett with argument GGLL__UUNNPPAACCKK__RROOWW__LLEENNGGTTHH
ggllGGeett with argument GGLL__UUNNPPAACCKK__IIMMAAGGEE__HHEEIIGGHHTT
ggllGGeett with argument GGLL__UUNNPPAACCKK__SSKKIIPP__RROOWWSS
ggllGGeett with argument GGLL__UUNNPPAACCKK__SSKKIIPP__PPIIXXEELLSS
ggllGGeett with argument GGLL__UUNNPPAACCKK__SSKKIIPP__IIMMAAGGEESS
ggllGGeett with argument GGLL__UUNNPPAACCKK__AALLIIGGNNMMEENNTT
SEE ALSO
ggllBBiittmmaapp((33GG)),
ggllCCoolloorrTTaabbllee((33GG)),
ggllCCoolloorrSSuubbTTaabbllee((33GG)),
ggllCCoonnvvoolluuttiioonnFFiilltteerr11DD((33GG)),
ggllCCoonnvvoolluuttiioonnFFiilltteerr22DD((33GG)),
ggllSSeeppaarraabblleeFFiilltteerr22DD((33GG)),
ggllDDrraawwPPiixxeellss((33GG)),
ggllHHiissttooggrraamm((33GG)),
ggllMMiinnmmaaxx((33GG)),
ggllPPiixxeellMMaapp((33GG)),
ggllPPiixxeellTTrraannssffeerr((33GG)),
ggllPPiixxeellZZoooomm((33GG)),
ggllPPoollyyggoonnSSttiippppllee((33GG)),
ggllPPuusshhCClliieennttAAttttrriibb((33GG)),
ggllRReeaaddPPiixxeellss((33GG)),
ggllTTeexxIImmaaggee11DD((33GG)),
ggllTTeexxIImmaaggee22DD((33GG)),
ggllTTeexxIImmaaggee33DD((33GG)),
ggllTTeexxSSuubbIImmaaggee11DD((33GG)),
ggllTTeexxSSuubbIImmaaggee22DD((33GG)),
ggllTTeexxSSuubbIImmaaggee33DD((33GG))