1GLDRAWPIXELS(3G) OpenGL Manual GLDRAWPIXELS(3G)
2
6 glDrawPixels - write a block of pixels to the frame buffer
7
9 void glDrawPixels(GLsizei width, GLsizei height, GLenum format,
10 GLenum type, const GLvoid * data);
11
13 width, height
14 Specify the dimensions of the pixel rectangle to be written into
15 the frame buffer.
16 format
18 Specifies the format of the pixel data. Symbolic constants
19 GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RGB,
20 GL_BGR, GL_RGBA, GL_BGRA, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA,
21 GL_LUMINANCE, and GL_LUMINANCE_ALPHA are accepted.
22 type
24 Specifies the data type for data. Symbolic constants
25 GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT,
26 GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2,
27 GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5,
28 GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
29 GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1,
30 GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
31 GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and
32 GL_UNSIGNED_INT_2_10_10_10_REV are accepted.
33 data
35 Specifies a pointer to the pixel data.
36
38 glDrawPixels reads pixel data from memory and writes it into the frame
39 buffer relative to the current raster position, provided that the
40 raster position is valid. Use glRasterPos() or glWindowPos() to set the
41 current raster position; use glGet() with argument
42 GL_CURRENT_RASTER_POSITION_VALID to determine if the specified raster
43 position is valid, and glGet() with argument GL_CURRENT_RASTER_POSITION
44 to query the raster position.
45 Several parameters define the encoding of pixel data in memory and
47 control the processing of the pixel data before it is placed in the
48 frame buffer. These parameters are set with four commands:
49 glPixelStore(), glPixelTransfer(), glPixelMap(), and glPixelZoom().
50 This reference page describes the effects on glDrawPixels of many, but
51 not all, of the parameters specified by these four commands.
52 Data is read from data as a sequence of signed or unsigned bytes,
54 signed or unsigned shorts, signed or unsigned integers, or
55 single-precision floating-point values, depending on type. When type is
56 one of GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
57 GL_UNSIGNED_INT, GL_INT, or GL_FLOAT each of these bytes, shorts,
58 integers, or floating-point values is interpreted as one color or depth
59 component, or one index, depending on format. When type is one of
60 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_SHORT_5_6_5,
61 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_5_5_5_1,
62 GL_UNSIGNED_INT_8_8_8_8, or GL_UNSIGNED_INT_10_10_10_2, each unsigned
63 value is interpreted as containing all the components for a single
64 pixel, with the color components arranged according to format. When
65 type is one of GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5_REV,
66 GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_1_5_5_5_REV,
67 GL_UNSIGNED_INT_8_8_8_8_REV, or GL_UNSIGNED_INT_2_10_10_10_REV, each
68 unsigned value is interpreted as containing all color components,
69 specified by format, for a single pixel in a reversed order. Indices
70 are always treated individually. Color components are treated as groups
71 of one, two, three, or four values, again based on format. Both
72 individual indices and groups of components are referred to as pixels.
73 If type is GL_BITMAP, the data must be unsigned bytes, and format must
74 be either GL_COLOR_INDEX or GL_STENCIL_INDEX. Each unsigned byte is
75 treated as eight 1-bit pixels, with bit ordering determined by
76 GL_UNPACK_LSB_FIRST (see glPixelStore()).
77 width × height pixels are read from memory, starting at location data.
79 By default, these pixels are taken from adjacent memory locations,
80 except that after all width pixels are read, the read pointer is
81 advanced to the next four-byte boundary. The four-byte row alignment is
82 specified by glPixelStore() with argument GL_UNPACK_ALIGNMENT, and it
83 can be set to one, two, four, or eight bytes. Other pixel store
84 parameters specify different read pointer advancements, both before the
85 first pixel is read and after all width pixels are read. See the
86 glPixelStore() reference page for details on these options.
87 If a non-zero named buffer object is bound to the
89 GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer()) while a block of
90 pixels is specified, data is treated as a byte offset into the buffer
91 object's data store.
92 The width × height pixels that are read from memory are each operated
94 on in the same way, based on the values of several parameters specified
95 by glPixelTransfer() and glPixelMap(). The details of these operations,
96 as well as the target buffer into which the pixels are drawn, are
97 specific to the format of the pixels, as specified by format. format
98 can assume one of 13 symbolic values:
99 GL_COLOR_INDEX
101 Each pixel is a single value, a color index. It is converted to
102 fixed-point format, with an unspecified number of bits to the right
103 of the binary point, regardless of the memory data type.
104 Floating-point values convert to true fixed-point values. Signed
105 and unsigned integer data is converted with all fraction bits set
106 to 0. Bitmap data convert to either 0 or 1.
107 Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits
109 and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the
110 shift is to the right. In either case, zero bits fill otherwise
111 unspecified bit locations in the result.
112 If the GL is in RGBA mode, the resulting index is converted to an
114 RGBA pixel with the help of the GL_PIXEL_MAP_I_TO_R,
115 GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A
116 tables. If the GL is in color index mode, and if GL_MAP_COLOR is
117 true, the index is replaced with the value that it references in
118 lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of
119 the index is done or not, the integer part of the index is then
120 ANDed with 2 b - 1, where b is the number of bits in a color index
121 buffer.
122 The GL then converts the resulting indices or RGBA colors to
124 fragments by attaching the current raster position z coordinate and
125 texture coordinates to each pixel, then assigning x and y window
126 coordinates to the nth fragment such that x n = x r + n % width y n
127 = y r + n width .sp where x r y r is the current raster position.
128 These pixel fragments are then treated just like the fragments
129 generated by rasterizing points, lines, or polygons. Texture
130 mapping, fog, and all the fragment operations are applied before
131 the fragments are written to the frame buffer.
132 GL_STENCIL_INDEX
134 Each pixel is a single value, a stencil index. It is converted to
135 fixed-point format, with an unspecified number of bits to the right
136 of the binary point, regardless of the memory data type.
137 Floating-point values convert to true fixed-point values. Signed
138 and unsigned integer data is converted with all fraction bits set
139 to 0. Bitmap data convert to either 0 or 1.
140 Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits,
142 and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the
143 shift is to the right. In either case, zero bits fill otherwise
144 unspecified bit locations in the result. If GL_MAP_STENCIL is true,
145 the index is replaced with the value that it references in lookup
146 table GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement of the
147 index is done or not, the integer part of the index is then ANDed
148 with 2 b - 1, where b is the number of bits in the stencil buffer.
149 The resulting stencil indices are then written to the stencil
150 buffer such that the nth index is written to location
151 x n = x r + n % width y n = y r + n width
153 where x r y r is the current raster position. Only the pixel
155 ownership test, the scissor test, and the stencil writemask affect
156 these write operations.
157 GL_DEPTH_COMPONENT
159 Each pixel is a single-depth component. Floating-point data is
160 converted directly to an internal floating-point format with
161 unspecified precision. Signed integer data is mapped linearly to
162 the internal floating-point format such that the most positive
163 representable integer value maps to 1.0, and the most negative
164 representable value maps to -1.0. Unsigned integer data is mapped
165 similarly: the largest integer value maps to 1.0, and 0 maps to
166 0.0. The resulting floating-point depth value is then multiplied by
167 GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to
168 the range 0 1.
169 The GL then converts the resulting depth components to fragments by
171 attaching the current raster position color or color index and
172 texture coordinates to each pixel, then assigning x and y window
173 coordinates to the nth fragment such that
174 x n = x r + n % width y n = y r + n width
176 where x r y r is the current raster position. These pixel fragments
178 are then treated just like the fragments generated by rasterizing
179 points, lines, or polygons. Texture mapping, fog, and all the
180 fragment operations are applied before the fragments are written to
181 the frame buffer.
182 GL_RGBA
184 GL_BGRA
186 Each pixel is a four-component group: For GL_RGBA, the red
187 component is first, followed by green, followed by blue, followed
188 by alpha; for GL_BGRA the order is blue, green, red and then alpha.
189 Floating-point values are converted directly to an internal
190 floating-point format with unspecified precision. Signed integer
191 values are mapped linearly to the internal floating-point format
192 such that the most positive representable integer value maps to
193 1.0, and the most negative representable value maps to -1.0. (Note
194 that this mapping does not convert 0 precisely to 0.0.) Unsigned
195 integer data is mapped similarly: The largest integer value maps to
196 1.0, and 0 maps to 0.0. The resulting floating-point color values
197 are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c
198 is RED, GREEN, BLUE, and ALPHA for the respective color components.
199 The results are clamped to the range 0 1.
200 If GL_MAP_COLOR is true, each color component is scaled by the size
202 of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value
203 that it references in that table. c is R, G, B, or A respectively.
204 The GL then converts the resulting RGBA colors to fragments by
206 attaching the current raster position z coordinate and texture
207 coordinates to each pixel, then assigning x and y window
208 coordinates to the nth fragment such that
209 x n = x r + n % width y n = y r + n width
211 where x r y r is the current raster position. These pixel fragments
213 are then treated just like the fragments generated by rasterizing
214 points, lines, or polygons. Texture mapping, fog, and all the
215 fragment operations are applied before the fragments are written to
216 the frame buffer.
217 GL_RED
219 Each pixel is a single red component. This component is converted
220 to the internal floating-point format in the same way the red
221 component of an RGBA pixel is. It is then converted to an RGBA
222 pixel with green and blue set to 0, and alpha set to 1. After this
223 conversion, the pixel is treated as if it had been read as an RGBA
224 pixel.
225 GL_GREEN
227 Each pixel is a single green component. This component is converted
228 to the internal floating-point format in the same way the green
229 component of an RGBA pixel is. It is then converted to an RGBA
230 pixel with red and blue set to 0, and alpha set to 1. After this
231 conversion, the pixel is treated as if it had been read as an RGBA
232 pixel.
233 GL_BLUE
235 Each pixel is a single blue component. This component is converted
236 to the internal floating-point format in the same way the blue
237 component of an RGBA pixel is. It is then converted to an RGBA
238 pixel with red and green set to 0, and alpha set to 1. After this
239 conversion, the pixel is treated as if it had been read as an RGBA
240 pixel.
241 GL_ALPHA
243 Each pixel is a single alpha component. This component is converted
244 to the internal floating-point format in the same way the alpha
245 component of an RGBA pixel is. It is then converted to an RGBA
246 pixel with red, green, and blue set to 0. After this conversion,
247 the pixel is treated as if it had been read as an RGBA pixel.
248 GL_RGB
250 GL_BGR
252 Each pixel is a three-component group: red first, followed by
253 green, followed by blue; for GL_BGR, the first component is blue,
254 followed by green and then red. Each component is converted to the
255 internal floating-point format in the same way the red, green, and
256 blue components of an RGBA pixel are. The color triple is converted
257 to an RGBA pixel with alpha set to 1. After this conversion, the
258 pixel is treated as if it had been read as an RGBA pixel.
259 GL_LUMINANCE
261 Each pixel is a single luminance component. This component is
262 converted to the internal floating-point format in the same way the
263 red component of an RGBA pixel is. It is then converted to an RGBA
264 pixel with red, green, and blue set to the converted luminance
265 value, and alpha set to 1. After this conversion, the pixel is
266 treated as if it had been read as an RGBA pixel.
267 GL_LUMINANCE_ALPHA
269 Each pixel is a two-component group: luminance first, followed by
270 alpha. The two components are converted to the internal
271 floating-point format in the same way the red component of an RGBA
272 pixel is. They are then converted to an RGBA pixel with red, green,
273 and blue set to the converted luminance value, and alpha set to the
274 converted alpha value. After this conversion, the pixel is treated
275 as if it had been read as an RGBA pixel.
276 The following table summarizes the meaning of the valid constants for
278 the type parameter:
279 ┌─────────────────────────────────────────────┬───────────────────────────────────────────────────────┐
281 │ │ │
282 │ Type │ Corresponding │
283 │ │ Type │
284 │ │ │
285 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
286 │GL_UNSIGNED_BYTE │ unsigned 8-bit integer │
287 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
288 │GL_BYTE │ signed 8-bit integer │
289 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
290 │GL_BITMAP │ single bits in unsigned 8-bit integers │
291 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
292 │GL_UNSIGNED_SHORT │ unsigned 16-bit integer │
293 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
294 │GL_SHORT │ signed 16-bit integer │
295 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
296 │GL_UNSIGNED_INT │ unsigned 32-bit integer │
297 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
298 │GL_INT │ 32-bit integer │
299 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
300 │GL_FLOAT │ single-precision floating-point │
301 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
302 │GL_UNSIGNED_BYTE_3_3_2 │ unsigned 8-bit integer │
303 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
304 │GL_UNSIGNED_BYTE_2_3_3_REV │ unsigned 8-bit integer with reversed component │
305 │ │ ordering │
306 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
307 │GL_UNSIGNED_SHORT_5_6_5 │ unsigned 16-bit integer │
308 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
309 │GL_UNSIGNED_SHORT_5_6_5_REV │ unsigned 16-bit integer with reversed component │
310 │ │ ordering │
311 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
312 │GL_UNSIGNED_SHORT_4_4_4_4 │ unsigned 16-bit integer │
313 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
314 │GL_UNSIGNED_SHORT_4_4_4_4_REV │ unsigned 16-bit integer with reversed component │
315 │ │ ordering │
316 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
317 │GL_UNSIGNED_SHORT_5_5_5_1 │ unsigned 16-bit integer │
318 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
319 │GL_UNSIGNED_SHORT_1_5_5_5_REV │ unsigned 16-bit integer with reversed component │
320 │ │ ordering │
321 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
322 │GL_UNSIGNED_INT_8_8_8_8 │ unsigned 32-bit integer │
323 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
324 │GL_UNSIGNED_INT_8_8_8_8_REV │ unsigned 32-bit integer with reversed component │
325 │ │ ordering │
326 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
327 │GL_UNSIGNED_INT_10_10_10_2 │ unsigned 32-bit integer │
328 ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
329 │GL_UNSIGNED_INT_2_10_10_10_REV │ unsigned 32-bit integer with reversed component │
330 │ │ ordering │
331 └─────────────────────────────────────────────┴───────────────────────────────────────────────────────┘
332 The rasterization described so far assumes pixel zoom factors of 1. If
334 glPixelZoom() is used to change the x and y pixel zoom factors, pixels
335 are converted to fragments as follows. If x r y r is the current raster
336 position, and a given pixel is in the nth column and mth row of the
337 pixel rectangle, then fragments are generated for pixels whose centers
338 are in the rectangle with corners at
339 x r + zoom x n y r + zoom y m
341 where zoom x is the value of GL_ZOOM_X and zoom y is the value of
343 GL_ZOOM_Y.
344
346 GL_BGR and GL_BGRA are only valid for format if the GL version is 1.2
347 or greater.
348 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
350 GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV,
351 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
352 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
353 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
354 GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV are only
355 valid for type if the GL version is 1.2 or greater.
356
358 GL_INVALID_ENUM is generated if format or type is not one of the
359 accepted values.
360 GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not
362 either GL_COLOR_INDEX or GL_STENCIL_INDEX.
363 GL_INVALID_VALUE is generated if either width or height is negative.
365 GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and
367 there is no stencil buffer.
368 GL_INVALID_OPERATION is generated if format is GL_RED, GL_GREEN,
370 GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_LUMINANCE, or
371 GL_LUMINANCE_ALPHA, and the GL is in color index mode.
372 GL_INVALID_OPERATION is generated if format is one of
374 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
375 GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format is
376 not GL_RGB.
377 GL_INVALID_OPERATION is generated if format is one of
379 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
380 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
381 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
382 GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and
383 format is neither GL_RGBA nor GL_BGRA.
384 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
386 bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object's data
387 store is currently mapped.
388 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
390 bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be
391 unpacked from the buffer object such that the memory reads required
392 would exceed the data store size.
393 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
395 bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly
396 divisible into the number of bytes needed to store in memory a datum
397 indicated by type.
398 GL_INVALID_OPERATION is generated if glDrawPixels is executed between
400 the execution of glBegin() and the corresponding execution of glEnd().
401
403 glGet() with argument GL_CURRENT_RASTER_POSITION
404 glGet() with argument GL_CURRENT_RASTER_POSITION_VALID
406 glGet() with argument GL_PIXEL_UNPACK_BUFFER_BINDING
408
410 glAlphaFunc(), glBlendFunc(), glCopyPixels(), glDepthFunc(),
411 glLogicOp(), glPixelMap(), glPixelStore(), glPixelTransfer(),
412 glPixelZoom(), glRasterPos(), glReadPixels(), glScissor(),
413 glStencilFunc(), glWindowPos()
414
416 Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
417 under the SGI Free Software B License. For details, see
418 http://oss.sgi.com/projects/FreeB/.
419
421 opengl.org
422opengl.org 07/13/2018 GLDRAWPIXELS(3G)