1GLDRAWPIXELS(3G)                 OpenGL Manual                GLDRAWPIXELS(3G)
2
3
4

NAME

6       glDrawPixels - write a block of pixels to the frame buffer
7

C SPECIFICATION

9       void glDrawPixels(GLsizei width, GLsizei height, GLenum format,
10                         GLenum type, const GLvoid * data);
11

PARAMETERS

13       width, height
14           Specify the dimensions of the pixel rectangle to be written into
15           the frame buffer.
16
17       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
23       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
34       data
35           Specifies a pointer to the pixel data.
36

DESCRIPTION

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
46       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
53       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
78       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
88       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
93       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
100       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
108           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
113           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
123           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 % widthy 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
133       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
141           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
152           x n = x r + n % widthy n = y r + n width
153
154           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
158       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
170           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
175           x n = x r + n % widthy n = y r + n width
176
177           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
183       GL_RGBA
184
185       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
201           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
205           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
210           x n = x r + n % widthy n = y r + n width
211
212           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
218       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
226       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
234       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
242       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
249       GL_RGB
250
251       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
260       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
268       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
277       The following table summarizes the meaning of the valid constants for
278       the type parameter:
279
280       ┌─────────────────────────────────────────────┬───────────────────────────────────────────────────────┐
281       │                                             │                                                       │
282Type Corresponding 
283       │                                             │ Type                                                  
284       │                                             │                                                       │
285       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
286GL_UNSIGNED_BYTE                             │ unsigned 8-bit integer                                │
287       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
288GL_BYTE                                      │ signed 8-bit integer                                  │
289       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
290GL_BITMAP                                    │ single bits in unsigned 8-bit integers                │
291       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
292GL_UNSIGNED_SHORT                            │ unsigned 16-bit integer                               │
293       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
294GL_SHORT                                     │ signed 16-bit integer                                 │
295       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
296GL_UNSIGNED_INT                              │ unsigned 32-bit integer                               │
297       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
298GL_INT                                       │ 32-bit integer                                        │
299       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
300GL_FLOAT                                     │ single-precision floating-point                       │
301       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
302GL_UNSIGNED_BYTE_3_3_2                       │ unsigned 8-bit integer                                │
303       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
304GL_UNSIGNED_BYTE_2_3_3_REV                   │ unsigned 8-bit integer with reversed component        │
305       │                                             │ ordering                                              │
306       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
307GL_UNSIGNED_SHORT_5_6_5                      │ unsigned 16-bit integer                               │
308       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
309GL_UNSIGNED_SHORT_5_6_5_REV                  │ unsigned 16-bit integer with reversed component       │
310       │                                             │ ordering                                              │
311       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
312GL_UNSIGNED_SHORT_4_4_4_4                    │ unsigned 16-bit integer                               │
313       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
314GL_UNSIGNED_SHORT_4_4_4_4_REV                │ unsigned 16-bit integer with reversed component       │
315       │                                             │ ordering                                              │
316       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
317GL_UNSIGNED_SHORT_5_5_5_1                    │ unsigned 16-bit integer                               │
318       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
319GL_UNSIGNED_SHORT_1_5_5_5_REV                │ unsigned 16-bit integer with reversed component       │
320       │                                             │ ordering                                              │
321       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
322GL_UNSIGNED_INT_8_8_8_8                      │ unsigned 32-bit integer                               │
323       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
324GL_UNSIGNED_INT_8_8_8_8_REV                  │ unsigned 32-bit integer with reversed component       │
325       │                                             │ ordering                                              │
326       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
327GL_UNSIGNED_INT_10_10_10_2                   │ unsigned 32-bit integer                               │
328       ├─────────────────────────────────────────────┼───────────────────────────────────────────────────────┤
329GL_UNSIGNED_INT_2_10_10_10_REV               │ unsigned 32-bit integer with reversed component       │
330       │                                             │ ordering                                              │
331       └─────────────────────────────────────────────┴───────────────────────────────────────────────────────┘
332
333       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
340       x r + zoom x ⁢ n y r + zoom y ⁢ m.PP x r + zoom x ⁡ n + 1 y r + zoom y
341       ⁡ m + 1
342
343       where zoom x is the value of GL_ZOOM_X and zoom y is the value of
344       GL_ZOOM_Y.
345

NOTES

347       GL_BGR and GL_BGRA are only valid for format if the GL version is 1.2
348       or greater.
349
350       GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
351       GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV,
352       GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
353       GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
354       GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
355       GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV are only
356       valid for type if the GL version is 1.2 or greater.
357

ERRORS

359       GL_INVALID_ENUM is generated if format or type is not one of the
360       accepted values.
361
362       GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not
363       either GL_COLOR_INDEX or GL_STENCIL_INDEX.
364
365       GL_INVALID_VALUE is generated if either width or height is negative.
366
367       GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and
368       there is no stencil buffer.
369
370       GL_INVALID_OPERATION is generated if format is GL_RED, GL_GREEN,
371       GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_LUMINANCE, or
372       GL_LUMINANCE_ALPHA, and the GL is in color index mode.
373
374       GL_INVALID_OPERATION is generated if format is one of
375       GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
376       GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format is
377       not GL_RGB.
378
379       GL_INVALID_OPERATION is generated if format is one of
380       GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
381       GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
382       GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
383       GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and
384       format is neither GL_RGBA nor GL_BGRA.
385
386       GL_INVALID_OPERATION is generated if a non-zero buffer object name is
387       bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object's data
388       store is currently mapped.
389
390       GL_INVALID_OPERATION is generated if a non-zero buffer object name is
391       bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be
392       unpacked from the buffer object such that the memory reads required
393       would exceed the data store size.
394
395       GL_INVALID_OPERATION is generated if a non-zero buffer object name is
396       bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly
397       divisible into the number of bytes needed to store in memory a datum
398       indicated by type.
399
400       GL_INVALID_OPERATION is generated if glDrawPixels is executed between
401       the execution of glBegin() and the corresponding execution of glEnd().
402

ASSOCIATED GETS

404       glGet() with argument GL_CURRENT_RASTER_POSITION
405
406       glGet() with argument GL_CURRENT_RASTER_POSITION_VALID
407
408       glGet() with argument GL_PIXEL_UNPACK_BUFFER_BINDING
409

SEE ALSO

411       glAlphaFunc(), glBlendFunc(), glCopyPixels(), glDepthFunc(),
412       glLogicOp(), glPixelMap(), glPixelStore(), glPixelTransfer(),
413       glPixelZoom(), glRasterPos(), glReadPixels(), glScissor(),
414       glStencilFunc(), glWindowPos()
415
417       Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
418       under the SGI Free Software B License. For details, see
419       http://oss.sgi.com/projects/FreeB/.
420

AUTHORS

422       opengl.org
423
424
425
426opengl.org                        06/10/2014                  GLDRAWPIXELS(3G)
Impressum