glPixelStorei(3g)

1GLPIXELSTORE(3G)                [FIXME: manual]               GLPIXELSTORE(3G)
2
3
4

NAME

6       glPixelStore - set pixel storage modes
7

C SPECIFICATION

9       void glPixelStoref(GLenum pname, GLfloat param);
10
11       void glPixelStorei(GLenum pname, GLint param);
12

PARAMETERS

14       pname
15           Specifies the symbolic name of the parameter to be set. Six values
16           affect the packing of pixel data into memory: GL_PACK_SWAP_BYTES,
17           GL_PACK_LSB_FIRST, GL_PACK_ROW_LENGTH, GL_PACK_IMAGE_HEIGHT,
18           GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, GL_PACK_SKIP_IMAGES, and
19           GL_PACK_ALIGNMENT. Six more affect the unpacking of pixel data from
20           memory: GL_UNPACK_SWAP_BYTES, GL_UNPACK_LSB_FIRST,
21           GL_UNPACK_ROW_LENGTH, GL_UNPACK_IMAGE_HEIGHT,
22           GL_UNPACK_SKIP_PIXELS, GL_UNPACK_SKIP_ROWS, GL_UNPACK_SKIP_IMAGES,
23           and GL_UNPACK_ALIGNMENT.
24
25       param
26           Specifies the value that pname is set to.
27

DESCRIPTION

29       glPixelStore sets pixel storage modes that affect the operation of
30       subsequent glReadPixels() as well as the unpacking of texture patterns
31       (see glTexImage1D(), glTexImage2D(), glTexImage3D(), glTexSubImage1D(),
32       glTexSubImage2D(), glTexSubImage3D()), glCompressedTexImage1D(),
33       glCompressedTexImage2D(), glCompressedTexImage3D(),
34       glCompressedTexSubImage1D(), glCompressedTexSubImage2D() or
35       glCompressedTexSubImage1D().
36
37       pname is a symbolic constant indicating the parameter to be set, and
38       param is the new value. Six of the twelve storage parameters affect how
39       pixel data is returned to client memory. They are as follows:
40
41       GL_PACK_SWAP_BYTES
42           If true, byte ordering for multibyte color components, depth
43           components, or stencil indices is reversed. That is, if a four-byte
44           component consists of bytes b 0, b 1, b 2, b 3, it is stored in
45           memory as b 3, b 2, b 1, b 0 if GL_PACK_SWAP_BYTES is true.
46           GL_PACK_SWAP_BYTES has no effect on the memory order of components
47           within a pixel, only on the order of bytes within components or
48           indices. For example, the three components of a GL_RGB format pixel
49           are always stored with red first, green second, and blue third,
50           regardless of the value of GL_PACK_SWAP_BYTES.
51
52       GL_PACK_LSB_FIRST
53           If true, bits are ordered within a byte from least significant to
54           most significant; otherwise, the first bit in each byte is the most
55           significant one.
56
57       GL_PACK_ROW_LENGTH
58           If greater than 0, GL_PACK_ROW_LENGTH defines the number of pixels
59           in a row. If the first pixel of a row is placed at location p in
60           memory, then the location of the first pixel of the next row is
61           obtained by skipping
62
63           k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a
64
65           components or indices, where n is the number of components or
66           indices in a pixel, l is the number of pixels in a row
67           (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to
68           the pixel routine otherwise), a is the value of GL_PACK_ALIGNMENT,
69           and s is the size, in bytes, of a single component (if a < s, then
70           it is as if a = s). In the case of 1-bit values, the location of
71           the next row is obtained by skipping
72
73           k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a
74
75           components or indices.
76
77           The word component in this description refers to the nonindex
78           values red, green, blue, alpha, and depth. Storage format GL_RGB,
79           for example, has three components per pixel: first red, then green,
80           and finally blue.
81
82       GL_PACK_IMAGE_HEIGHT
83           If greater than 0, GL_PACK_IMAGE_HEIGHT defines the number of
84           pixels in an image three-dimensional texture volume, where
85           ``image'' is defined by all pixels sharing the same third dimension
86           index. If the first pixel of a row is placed at location p in
87           memory, then the location of the first pixel of the next row is
88           obtained by skipping
89
90           k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a
91
92           components or indices, where n is the number of components or
93           indices in a pixel, l is the number of pixels in a row
94           (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to
95           glTexImage3D() otherwise), h is the number of rows in a pixel image
96           (GL_PACK_IMAGE_HEIGHT if it is greater than 0, the height argument
97           to the glTexImage3D() routine otherwise), a is the value of
98           GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single
99           component (if a < s, then it is as if a = s).
100
101           The word component in this description refers to the nonindex
102           values red, green, blue, alpha, and depth. Storage format GL_RGB,
103           for example, has three components per pixel: first red, then green,
104           and finally blue.
105
106       GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, and GL_PACK_SKIP_IMAGES
107           These values are provided as a convenience to the programmer; they
108           provide no functionality that cannot be duplicated simply by
109           incrementing the pointer passed to glReadPixels(). Setting
110           GL_PACK_SKIP_PIXELS to i is equivalent to incrementing the pointer
111           by i ⁢ n components or indices, where n is the number of components
112           or indices in each pixel. Setting GL_PACK_SKIP_ROWS to j is
113           equivalent to incrementing the pointer by j ⁢ m components or
114           indices, where m is the number of components or indices per row, as
115           just computed in the GL_PACK_ROW_LENGTH section. Setting
116           GL_PACK_SKIP_IMAGES to k is equivalent to incrementing the pointer
117           by k ⁢ p, where p is the number of components or indices per image,
118           as computed in the GL_PACK_IMAGE_HEIGHT section.
119
120       GL_PACK_ALIGNMENT
121           Specifies the alignment requirements for the start of each pixel
122           row in memory. The allowable values are 1 (byte-alignment), 2 (rows
123           aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows
124           start on double-word boundaries).
125
126       The other six of the twelve storage parameters affect how pixel data is
127       read from client memory. These values are significant for
128       glTexImage1D(), glTexImage2D(), glTexImage3D(), glTexSubImage1D(),
129       glTexSubImage2D(), and glTexSubImage3D()
130
131       They are as follows:
132
133       GL_UNPACK_SWAP_BYTES
134           If true, byte ordering for multibyte color components, depth
135           components, or stencil indices is reversed. That is, if a four-byte
136           component consists of bytes b 0, b 1, b 2, b 3, it is taken from
137           memory as b 3, b 2, b 1, b 0 if GL_UNPACK_SWAP_BYTES is true.
138           GL_UNPACK_SWAP_BYTES has no effect on the memory order of
139           components within a pixel, only on the order of bytes within
140           components or indices. For example, the three components of a
141           GL_RGB format pixel are always stored with red first, green second,
142           and blue third, regardless of the value of GL_UNPACK_SWAP_BYTES.
143
144       GL_UNPACK_LSB_FIRST
145           If true, bits are ordered within a byte from least significant to
146           most significant; otherwise, the first bit in each byte is the most
147           significant one.
148
149       GL_UNPACK_ROW_LENGTH
150           If greater than 0, GL_UNPACK_ROW_LENGTH defines the number of
151           pixels in a row. If the first pixel of a row is placed at location
152           p in memory, then the location of the first pixel of the next row
153           is obtained by skipping
154
155           k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a
156
157           components or indices, where n is the number of components or
158           indices in a pixel, l is the number of pixels in a row
159           (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument
160           to the pixel routine otherwise), a is the value of
161           GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single
162           component (if a < s, then it is as if a = s). In the case of 1-bit
163           values, the location of the next row is obtained by skipping
164
165           k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a
166
167           components or indices.
168
169           The word component in this description refers to the nonindex
170           values red, green, blue, alpha, and depth. Storage format GL_RGB,
171           for example, has three components per pixel: first red, then green,
172           and finally blue.
173
174       GL_UNPACK_IMAGE_HEIGHT
175           If greater than 0, GL_UNPACK_IMAGE_HEIGHT defines the number of
176           pixels in an image of a three-dimensional texture volume. Where
177           ``image'' is defined by all pixel sharing the same third dimension
178           index. If the first pixel of a row is placed at location p in
179           memory, then the location of the first pixel of the next row is
180           obtained by skipping
181
182           k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a
183
184           components or indices, where n is the number of components or
185           indices in a pixel, l is the number of pixels in a row
186           (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument
187           to glTexImage3D() otherwise), h is the number of rows in an image
188           (GL_UNPACK_IMAGE_HEIGHT if it is greater than 0, the height
189           argument to glTexImage3D() otherwise), a is the value of
190           GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single
191           component (if a < s, then it is as if a = s).
192
193           The word component in this description refers to the nonindex
194           values red, green, blue, alpha, and depth. Storage format GL_RGB,
195           for example, has three components per pixel: first red, then green,
196           and finally blue.
197
198       GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS
199           These values are provided as a convenience to the programmer; they
200           provide no functionality that cannot be duplicated by incrementing
201           the pointer passed to glTexImage1D(), glTexImage2D(),
202           glTexSubImage1D() or glTexSubImage2D(). Setting
203           GL_UNPACK_SKIP_PIXELS to i is equivalent to incrementing the
204           pointer by i ⁢ n components or indices, where n is the number of
205           components or indices in each pixel. Setting GL_UNPACK_SKIP_ROWS to
206           j is equivalent to incrementing the pointer by j ⁢ k components or
207           indices, where k is the number of components or indices per row, as
208           just computed in the GL_UNPACK_ROW_LENGTH section.
209
210       GL_UNPACK_ALIGNMENT
211           Specifies the alignment requirements for the start of each pixel
212           row in memory. The allowable values are 1 (byte-alignment), 2 (rows
213           aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows
214           start on double-word boundaries).
215
216       The following table gives the type, initial value, and range of valid
217       values for each storage parameter that can be set with glPixelStore.
218
219       ┌───────────────────────┬─────────┬────────────────┬───────────────────────────────────┐
220       │ pname                 │   Type  │  Initial Value │            Valid Range            │
221       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
222       │GL_PACK_SWAP_BYTES     │ boolean │     false      │           true or false           │
223       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
224       │GL_PACK_LSB_FIRST      │ boolean │     false      │           true or false           │
225       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
226       │GL_PACK_ROW_LENGTH     │ integer │       0        │ 0                                 │
227       │                       │         │                │                                 ∞ │
228       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
229       │GL_PACK_IMAGE_HEIGHT   │ integer │       0        │ 0                                 │
230       │                       │         │                │                                 ∞ │
231       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
232       │GL_PACK_SKIP_ROWS      │ integer │       0        │ 0                                 │
233       │                       │         │                │                                 ∞ │
234       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
235       │GL_PACK_SKIP_PIXELS    │ integer │       0        │ 0                                 │
236       │                       │         │                │                                 ∞ │
237       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
238       │GL_PACK_SKIP_IMAGES    │ integer │       0        │ 0                                 │
239       │                       │         │                │                                 ∞ │
240       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
241       │GL_PACK_ALIGNMENT      │ integer │       4        │           1, 2, 4, or 8           │
242       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
243       │GL_UNPACK_SWAP_BYTES   │ boolean │     false      │           true or false           │
244       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
245       │GL_UNPACK_LSB_FIRST    │ boolean │     false      │           true or false           │
246       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
247       │GL_UNPACK_ROW_LENGTH   │ integer │       0        │ 0                                 │
248       │                       │         │                │                                 ∞ │
249       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
250       │GL_UNPACK_IMAGE_HEIGHT │ integer │       0        │ 0                                 │
251       │                       │         │                │                                 ∞ │
252       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
253       │GL_UNPACK_SKIP_ROWS    │ integer │       0        │ 0                                 │
254       │                       │         │                │                                 ∞ │
255       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
256       │GL_UNPACK_SKIP_PIXELS  │ integer │       0        │ 0                                 │
257       │                       │         │                │                                 ∞ │
258       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
259       │GL_UNPACK_SKIP_IMAGES  │ integer │       0        │ 0                                 │
260       │                       │         │                │                                 ∞ │
261       ├───────────────────────┼─────────┼────────────────┼───────────────────────────────────┤
262       │GL_UNPACK_ALIGNMENT    │ integer │       4        │           1, 2, 4, or 8           │
263       └───────────────────────┴─────────┴────────────────┴───────────────────────────────────┘
264
265       glPixelStoref can be used to set any pixel store parameter. If the
266       parameter type is boolean, then if param is 0, the parameter is false;
267       otherwise it is set to true. If pname is a integer type parameter,
268       param is rounded to the nearest integer.
269
270       Likewise, glPixelStorei can also be used to set any of the pixel store
271       parameters. Boolean parameters are set to false if param is 0 and true
272       otherwise.
273

ERRORS

275       GL_INVALID_ENUM is generated if pname is not an accepted value.
276
277       GL_INVALID_VALUE is generated if a negative row length, pixel skip, or
278       row skip value is specified, or if alignment is specified as other than
279       1, 2, 4, or 8.
280

ASSOCIATED GETS

282       glGet() with argument GL_PACK_SWAP_BYTES
283
284       glGet() with argument GL_PACK_LSB_FIRST
285
286       glGet() with argument GL_PACK_ROW_LENGTH
287
288       glGet() with argument GL_PACK_IMAGE_HEIGHT
289
290       glGet() with argument GL_PACK_SKIP_ROWS
291
292       glGet() with argument GL_PACK_SKIP_PIXELS
293
294       glGet() with argument GL_PACK_SKIP_IMAGES
295
296       glGet() with argument GL_PACK_ALIGNMENT
297
298       glGet() with argument GL_UNPACK_SWAP_BYTES
299
300       glGet() with argument GL_UNPACK_LSB_FIRST
301
302       glGet() with argument GL_UNPACK_ROW_LENGTH
303
304       glGet() with argument GL_UNPACK_IMAGE_HEIGHT
305
306       glGet() with argument GL_UNPACK_SKIP_ROWS
307
308       glGet() with argument GL_UNPACK_SKIP_PIXELS
309
310       glGet() with argument GL_UNPACK_SKIP_IMAGES
311
312       glGet() with argument GL_UNPACK_ALIGNMENT
313

VERSION SUPPORT

315       ┌──────────────┬───────────────────────────────────────────────────────────────────────┐
316       │              │                OpenGL Version                                         │
317       ├──────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
318       │Function      │ 2.0 │ 2.1 │ 3.0 │ 3.1 │ 3.2 │ 3.3 │ 4.0 │ 4.1 │ 4.2 │ 4.3 │ 4.4 │ 4.5 │
319       │/             │     │     │     │     │     │     │     │     │     │     │     │     │
320       │Feature       │     │     │     │     │     │     │     │     │     │     │     │     │
321       │Name          │     │     │     │     │     │     │     │     │     │     │     │     │
322       ├──────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
323       │glPixelStoref │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
324       ├──────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
325       │glPixelStorei │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
326       └──────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
327

COPYRIGHT

336       Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014
337       Khronos Group. This document is licensed under the SGI Free Software B
338       License. For details, see http://oss.sgi.com/projects/FreeB/.
339

COPYRIGHT

341       Copyright © 1991-2006 Silicon Graphics, Inc.
342       Copyright © 2010-2014 Khronos Group
343
344
345
346[FIXME: source]                   07/13/2018                  GLPIXELSTORE(3G)