1GLPIXELSTORE(3G) GLPIXELSTORE(3G)
2
6 glPixelStoref, glPixelStorei - set pixel storage modes
7
10 void glPixelStoref( GLenum pname,
11 GLfloat param )
12 void glPixelStorei( GLenum pname,
13 GLint param )
14 delim $$
16
18 pname Specifies the symbolic name of the parameter to be set. Six
19 values affect the packing of pixel data into memory:
20 GL_PACK_SWAP_BYTES, GL_PACK_LSB_FIRST, GL_PACK_ROW_LENGTH,
21 GL_PACK_IMAGE_HEIGHT, GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS,
22 GL_PACK_SKIP_IMAGES, and GL_PACK_ALIGNMENT. Six more affect the
23 unpacking of pixel data from memory: GL_UNPACK_SWAP_BYTES,
24 GL_UNPACK_LSB_FIRST, GL_UNPACK_ROW_LENGTH,
25 GL_UNPACK_IMAGE_HEIGHT, GL_UNPACK_SKIP_PIXELS,
26 GL_UNPACK_SKIP_ROWS, GL_UNPACK_SKIP_IMAGES, and
27 GL_UNPACK_ALIGNMENT.
28 param Specifies the value that pname is set to.
30
32 glPixelStore sets pixel storage modes that affect the operation of sub‐
33 sequent glDrawPixels and glReadPixels as well as the unpacking of poly‐
34 gon stipple patterns (see glPolygonStipple), bitmaps (see glBitmap),
35 texture patterns (see glTexImage1D, glTexImage2D, glTexImage3D,
36 glTexSubImage1D, glTexSubImage2D, glTexSubImage3D). Additionally, if
37 the GL_ARB_imaging extension is supported, pixle storage modes affect
38 convlution filters (see glConvolutionFilter1D, glConvolutionFilter2D,
39 and glSeparableFilter2D, color table (see glColorTable, and
40 glColorSubTable, and unpacking histogram (See glHistogram), and minmax
41 (See glMinmax) data.
42 pname is a symbolic constant indicating the parameter to be set, and
44 param is the new value. Six of the twelve storage parameters affect
45 how pixel data is returned to client memory. They are as follows:
46 GL_PACK_SWAP_BYTES
48 If true, byte ordering for multibyte color components, depth
49 components, color indices, or stencil indices is reversed.
50 That is, if a four-byte component consists of bytes $b sub
51 0$, $b sub 1$, $b sub 2$, $b sub 3$, it is stored in memory
52 as $b sub 3$, $b sub 2$, $b sub 1$, $b sub 0$ if
53 GL_PACK_SWAP_BYTES is true. GL_PACK_SWAP_BYTES has no effect
54 on the memory order of components within a pixel, only on the
55 order of bytes within components or indices. For example,
56 the three components of a GL_RGB pixel are always stored
57 with red first, green second, and blue third, regardless of
58 the value of GL_PACK_SWAP_BYTES.
59 GL_PACK_LSB_FIRST
61 If true, bits are ordered within a byte from least signifi‐
62 cant to most significant; otherwise, the first bit in each
63 byte is the most significant one. This parameter is signifi‐
64 cant for bitmap data only.
65 GL_PACK_ROW_LENGTH
67 If greater than 0, GL_PACK_ROW_LENGTH defines the number of
68 pixels in a row. If the first pixel of a row is placed at
69 location $p$ in memory, then the location of the first pixel
70 of the next row is obtained by skipping
71 $k ~=~~ left { ^ lpile { n l above {a over s left ceiling {
73 s n l } over a right ceiling}} ~~ lpile {s ~>=~ a above s ~<~
74 a }$
75 components or indices, where $n$ is the number of components
77 or indices in a pixel, $l$ is the number of pixels in a row
78 (GL_PACK_ROW_LENGTH if it is greater than 0, the $width$
79 argument to the pixel routine otherwise), $a$ is the value of
80 GL_PACK_ALIGNMENT, and $s$ is the size, in bytes, of a single
81 component (if $ a < s$, then it is as if $a ~=~ s$). In the
82 case of 1-bit values, the location of the next row is
83 obtained by skipping
84 $k ~=~ 8 a left ceiling { n l } over { 8 a } ^ right ceiling$
86 components or indices.
88 The word component in this description refers to the nonindex
90 values red, green, blue, alpha, and depth. Storage GL_RGB,
91 for example, has three components per pixel: first red, then
92 green, and finally blue.
93 GL_PACK_IMAGE_HEIGHT
95 If greater than 0, GL_PACK_IMAGE_HEIGHT defines the number of
96 pixels in an image three-dimensional texture volume. Where
97 ``image'' is defined by all pixels sharing the same third
98 dimension index. If the first pixel of a row is placed at
99 location $p$ in memory, then the location of the first pixel
100 of the next row is obtained by skipping
101 $k ~=~~ left { ~ lpile { n l h above {a over s left ceiling
103 { s n l h }
104 over a ^ right ceiling}} ~~ lpile {s ~>=~ a above s ~<~ a
105 }$
106 components or indices, where $n$ is the number of components
108 or indices in a pixel, $l$ is the number of pixels in a row
109 (GL_PACK_ROW_LENGTH if it is greater than 0, the $width$
110 argument to glTexImage3d otherwise), $h$ is the number of
111 rows in a pixel image (GL_PACK_IMAGE_HEIGHT if it is greater
112 than 0, the $height$ argument to the glTexImage3D routine
113 otherwise), $a$ is the value of GL_PACK_ALIGNMENT, and $s$ is
114 the size, in bytes, of a single component (if $ a < s$, then
115 it is as if $a = s$).
116 The word component in this description refers to the nonindex
118 values red, green, blue, alpha, and depth. Storage GL_RGB,
119 for example, has three components per pixel: first red, then
120 green, and finally blue.
121 GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, and GL_PACK_SKIP_IMAGES
123 These values are provided as a convenience to the programmer;
124 they provide no functionality that cannot be duplicated sim‐
125 ply by incrementing the pointer passed to glReadPixels. Set‐
126 ting GL_PACK_SKIP_PIXELS to $i$ is equivalent to incrementing
127 the pointer by $i n$ components or indices, where $n$ is the
128 number of components or indices in each pixel. Setting
129 GL_PACK_SKIP_ROWS to $j$ is equivalent to incrementing the
130 pointer by $j m$ components or indices, where $m$ is the num‐
131 ber of components or indices per row, as just computed in the
132 GL_PACK_ROW_LENGTH section. Setting GL_PACK_SKIP_IMAGES to
133 $k$ is equivalent to incrementing the pointer by $k p$, where
134 $p$ is the number of components or indices per image, as com‐
135 puted in the GL_PACK_IMAGE_HEIGHT section.
136 GL_PACK_ALIGNMENT
138 Specifies the alignment requirements for the start of each
139 pixel row in memory. The allowable values are 1 (byte-align‐
140 ment), 2 (rows aligned to even-numbered bytes), 4 (word-
141 alignment), and 8 (rows start on double-word boundaries).
142 The other six of the twelve storage parameters affect how pixel data is
144 read from client memory. These values are significant for
145 glDrawPixels, glTexImage1D, glTexImage2D, glTexImage3D,
146 glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glBitmap, and
147 glPolygonStipple.
148 Additionally, if the GL_ARB_imaging extension is supported,
150 glColorTable, glColorSubTable, glConvolutionFilter1D,
151 glConvolutionFilter2D, and glSeparableFilter2D. They are as follows:
152 GL_UNPACK_SWAP_BYTES
154 If true, byte ordering for multibyte color components, depth
155 components, color indices, or stencil indices is reversed. That
156 is, if a four-byte component consists of bytes $b sub 0$, $b sub
157 1$, $b sub 2$, $b sub 3$, it is taken from memory as $b sub 3$,
158 $b sub 2$, $b sub 1$, $b sub 0$ if GL_UNPACK_SWAP_BYTES is true.
159 GL_UNPACK_SWAP_BYTES has no effect on the memory order of compo‐
160 nents within a pixel, only on the order of bytes within compo‐
161 nents or indices. For example, the three components of a GL_RGB
162 pixel are always stored with red first, green second, and blue
163 third, regardless of the value of GL_UNPACK_SWAP_BYTES.
164 GL_UNPACK_LSB_FIRST
166 If true, bits are ordered within a byte from least significant
167 to most significant; otherwise, the first bit in each byte is
168 the most significant one. This is relevant only for bitmap
169 data.
170 GL_UNPACK_ROW_LENGTH
172 If greater than 0, GL_UNPACK_ROW_LENGTH defines the number of
173 pixels in a row. If the first pixel of a row is placed at loca‐
174 tion $p$ in memory, then the location of the first pixel of the
175 next row is obtained by skipping
176 $k ~=~~ left { ~ lpile { n l above {a over s left ceiling { s n
178 l }
179 over a ^ right ceiling}} ~~ lpile {s ~>=~ a above s ~<~ a }$
180 components or indices, where $n$ is the number of components or
182 indices in a pixel, $l$ is the number of pixels in a row (‐
183 GL_UNPACK_ROW_LENGTH if it is greater than 0, the $width$ argu‐
184 ment to the pixel routine otherwise), $a$ is the value of
185 GL_UNPACK_ALIGNMENT, and $s$ is the size, in bytes, of a single
186 component (if $ a < s$, then it is as if $a = s$). In the case
187 of 1-bit values, the location of the next row is obtained by
188 skipping
189 $k ~=~ 8 a left ceiling { n l } over { 8 a } right ceiling$
191 components or indices.
193 The word component in this description refers to the nonindex
195 values red, green, blue, alpha, and depth. Storage GL_RGB, for
196 example, has three components per pixel: first red, then green,
197 and finally blue.
198 GL_UNPACK_IMAGE_HEIGHT
200 If greater than 0, GL_UNPACK_IMAGE_HEIGHT defines the number of
201 pixels in an image of a three-dimensional texture volume. Where
202 ``image'' is defined by all pixel sharing the same third dimen‐
203 sion index. If the first pixel of a row is placed at location
204 $p$ in memory, then the location of the first pixel of the next
205 row is obtained by skipping
206 $k ~=~~ left {~ lpile { n l h above {a over s left ceiling { s
208 n l h }
209 over a ^ right ceiling}} ~~ lpile {s ~ >=~ a above s ~<~ a }$
210 components or indices, where $n$ is the number of components or
212 indices in a pixel, $l$ is the number of pixels in a row (‐
213 GL_UNPACK_ROW_LENGTH if it is greater than 0, the $width$ argu‐
214 ment to glTexImage3D otherwise), $h$ is the number of rows in an
215 image (GL_UNPACK_IMAGE_HEIGHT if it is greater than 0, the
216 $height$ argument to glTexImage3D otherwise), $a$ is the value
217 of GL_UNPACK_ALIGNMENT, and $s$ is the size, in bytes, of a sin‐
218 gle component (if $ a < s$, then it is as if $a ~=~ s$).
219 The word component in this description refers to the nonindex
221 values red, green, blue, alpha, and depth. Storage GL_RGB, for
222 example, has three components per pixel: first red, then green,
223 and finally blue.
224 GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS
226 These values are provided as a convenience to the programmer;
227 they provide no functionality that cannot be duplicated by
228 incrementing the pointer passed to glDrawPixels, glTexImage1D,
229 glTexImage2D, glTexSubImage1D, glTexSubImage2D, glBitmap, or
230 glPolygonStipple. Setting GL_UNPACK_SKIP_PIXELS to $i$ is
231 equivalent to incrementing the pointer by $i n$ components or
232 indices, where $n$ is the number of components or indices in
233 each pixel. Setting GL_UNPACK_SKIP_ROWS to $j$ is equivalent to
234 incrementing the pointer by $j k$ components or indices, where
235 $k$ is the number of components or indices per row, as just com‐
236 puted in the GL_UNPACK_ROW_LENGTH section.
237 GL_UNPACK_ALIGNMENT
239 Specifies the alignment requirements for the start of each pixel
240 row in memory. The allowable values are 1 (byte-alignment), 2
241 (rows aligned to even-numbered bytes), 4 (word-alignment), and 8
242 (rows start on double-word boundaries).
243 The following table gives the type, initial value, and range of valid
245 values for each storage parameter that can be set with glPixelStore.
246 ─────────────────────────────────────────────────────────────────
250 pname Type Initial Value Valid Range
251 ─────────────────────────────────────────────────────────────────
252 GL_PACK_SWAP_BYTES boolean false true or false
253 GL_PACK_LSB_FIRST boolean false true or false
254 GL_PACK_ROW_LENGTH integer 0 [0,∞)
255 GL_PACK_IMAGE_HEIGHT integer 0 [0, ∞)
256 GL_PACK_SKIP_ROWS integer 0 [0,∞)
257 GL_PACK_SKIP_PIXELS integer 0 [0,∞)
258 GL_PACK_SKIP_IMAGES integer 0 [0,∞)
259 GL_PACK_ALIGNMENT integer 4 1, 2, 4, or 8
260 ─────────────────────────────────────────────────────────────────
261 GL_UNPACK_SWAP_BYTES boolean false true or false
262 GL_UNPACK_LSB_FIRST boolean false true or false
263 GL_UNPACK_ROW_LENGTH integer 0 [0,∞)
264 GL_UNPACK_IMAGE_HEIGHT integer 0 [0,∞)
265 GL_UNPACK_SKIP_ROWS integer 0 [0,∞)
266 GL_UNPACK_SKIP_PIXELS integer 0 [0,∞)
267 GL_UNPACK_SKIP_IMAGES integer 0 [0,∞)
268 GL_UNPACK_ALIGNMENT integer 4 1, 2, 4, or 8
269 ─────────────────────────────────────────────────────────────────
270 glPixelStoref can be used to set any pixel store parameter. If the
273 parameter type is boolean, then if param is 0, the parameter is false;
274 otherwise it is set to true. If pname is a integer type parameter,
275 param is rounded to the nearest integer.
276 Likewise, glPixelStorei can also be used to set any of the pixel store
278 parameters. Boolean parameters are set to false if param is 0 and true
279 otherwise.
280
282 The pixel storage modes in effect when glDrawPixels, glReadPixels,
283 glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D,
284 glTexSubImage2D, glTexSubImage3D, glBitmap, or glPolygonStipple is
285 placed in a display list control the interpretation of memory data.
286 Likewise, if the GL_ARB_imaging extension is supported, the pixel stor‐
287 age modes in effect when glColorTable, glColorSubTable,
288 glConvolutionFilter1D, glConvolutionFilter2D, of glSeparableFilter2D is
289 placed in a display list control the interpretation of memory data.
290 The pixel storage modes in effect when a display list is executed are
291 not significant.
292 Pixel storage modes are client state and must be pushed and restored
294 using
295 glPushClientAttrib and glPopClientAttrib.
296
298 GL_INVALID_ENUM is generated if pname is not an accepted value.
299 GL_INVALID_VALUE is generated if a negative row length, pixel skip, or
301 row skip value is specified, or if alignment is specified as other than
302 1, 2, 4, or 8.
303 GL_INVALID_OPERATION is generated if glPixelStore is executed between
305 the execution of glBegin and the corresponding execution of glEnd.
306
308 glGet with argument GL_PACK_SWAP_BYTES
309 glGet with argument GL_PACK_LSB_FIRST
310 glGet with argument GL_PACK_ROW_LENGTH
311 glGet with argument GL_PACK_IMAGE_HEIGHT
312 glGet with argument GL_PACK_SKIP_ROWS
313 glGet with argument GL_PACK_SKIP_PIXELS
314 glGet with argument GL_PACK_SKIP_IMAGES
315 glGet with argument GL_PACK_ALIGNMENT
316 glGet with argument GL_UNPACK_SWAP_BYTES
317 glGet with argument GL_UNPACK_LSB_FIRST
318 glGet with argument GL_UNPACK_ROW_LENGTH
319 glGet with argument GL_UNPACK_IMAGE_HEIGHT
320 glGet with argument GL_UNPACK_SKIP_ROWS
321 glGet with argument GL_UNPACK_SKIP_PIXELS
322 glGet with argument GL_UNPACK_SKIP_IMAGES
323 glGet with argument GL_UNPACK_ALIGNMENT
324
326 glBitmap(3G), glColorTable(3G), glColorSubTable(3G),
327 glConvolutionFilter1D(3G), glConvolutionFilter2D(3G),
328 glSeparableFilter2D(3G), glDrawPixels(3G), glHistogram(3G),
329 glMinmax(3G), glPixelMap(3G), glPixelTransfer(3G), glPixelZoom(3G),
330 glPolygonStipple(3G), glPushClientAttrib(3G), glReadPixels(3G),
331 glTexImage1D(3G), glTexImage2D(3G), glTexImage3D(3G),
332 glTexSubImage1D(3G), glTexSubImage2D(3G), glTexSubImage3D(3G)
333 GLPIXELSTORE(3G)