gl.DrawPixelsRaw(width, height, format, type, pixels)
gl.DrawPixelsRaw() reads pixel data from memory and writes it into the frame buffer relative to the current
raster position, provided that the raster position is valid. Use gl.RasterPos() to
set the current raster position; use gl.Get() with argument #GL_CURRENT_RASTER_POSITION_VALID
to determine if the specified raster position is valid, and gl.Get() with argument #GL_CURRENT_RASTER_POSITION
to query the raster position.
Several parameters define the encoding of pixel data in memory and control the processing of the pixel
data before it is placed in the frame buffer. These parameters are set with four commands: gl.PixelStore(),
gl.PixelTransfer(), gl.PixelMap(), and gl.PixelZoom().
This reference page describes the effects on gl.DrawPixelsRaw() of many, but not all, of the parameters
specified by these four commands.
Data is read from pixels as a sequence of signed or unsigned bytes, signed or unsigned shorts, signed or unsigned
integers, or single-precision floating-point values, depending on type which can be #GL_UNSIGNED_BYTE, #GL_BYTE, #GL_BITMAP,
#GL_UNSIGNED_SHORT, #GL_SHORT, #GL_UNSIGNED_INT, #GL_INT, or #GL_FLOAT. Each of these bytes, shorts, integers, or floating-point
values is interpreted as one color or depth component, or one index, depending on format. Indices are always treated
individually. Color components are treated as groups of one, two, three, or four values, again based on format. Both
individual indices and groups of components are referred to as pixels. If type is #GL_BITMAP, the data must be unsigned
bytes, and format must be either #GL_COLOR_INDEX or #GL_STENCIL_INDEX. Each unsigned byte is treated as eight 1-bit pixels,
with bit ordering determined by #GL_UNPACK_LSB_FIRST (See gl.PixelStore for details.).
width * height pixels are read from memory, starting at location pixels. By default, these pixels are taken from
adjacent memory locations, except that after all width pixels are read, the read pointer is advanced to the next
four-byte boundary. The four-byte row alignment is specified by gl.PixelStore() with argument
#GL_UNPACK_ALIGNMENT, and it can be set to one, two, four, or eight bytes. Other pixel store parameters specify
different read pointer advancements, both before the first pixel is read and after all width pixels are read.
See gl.PixelStore for details.
The width * height pixels that are read from memory are each operated on in the same way, based on the values
of several parameters specified by gl.PixelTransfer() and gl.PixelMap().
The details of these operations, as well as the target buffer into which the pixels are drawn, are specific to the
format of the pixels, as specified by format. format can assume one of 13 symbolic values:
#GL_COLOR_INDEX
Each fixed-point index is then shifted left by #GL_INDEX_SHIFT bits and added to #GL_INDEX_OFFSET. If #GL_INDEX_SHIFT
is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result.
If the GL is in RGBA mode, the resulting index is converted to an RGBA pixel with the help of the #GL_PIXEL_MAP_I_TO_R,
#GL_PIXEL_MAP_I_TO_G, #GL_PIXEL_MAP_I_TO_B, and #GL_PIXEL_MAP_I_TO_A tables. If the GL is in color index mode, and
if #GL_MAP_COLOR is true, the index is replaced with the value that it references in lookup table #GL_PIXEL_MAP_I_TO_I.
Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2^b-1,
where b is the number of bits in a color index buffer.
The GL then converts the resulting indices or RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that
xn = xr + n % width yn = yr + n / width |
where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
#GL_STENCIL_INDEX
Each fixed-point index is then shifted left by #GL_INDEX_SHIFT bits, and added to #GL_INDEX_OFFSET. If #GL_INDEX_SHIFT
is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the
result. If #GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table #GL_PIXEL_MAP_S_TO_S.
Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2^b-1,
where b is the number of bits in the stencil buffer. The resulting stencil indices are then written to the stencil
buffer such that the nth index is written to location
xn = xr + n % width yn = yr + n / width |
where (xr,yr) is the current raster position. Only the pixel ownership test, the scissor test, and the stencil writemask affect these write operations.
#GL_DEPTH_COMPONENT#GL_DEPTH_SCALE and added
to #GL_DEPTH_BIAS. The result is clamped to the range [0,1].
The GL then converts the resulting depth components to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that
xn = xr + n % width yn = yr + n / width |
where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
#GL_RGBA#GL_RGBA, the red component is first, followed by green, followed by blue, followed by alpha.
Floating-point values are converted directly to an internal floating-point format with unspecified precision. The resulting
floating-point color values are then multiplied by #GL_c_SCALE and added to #GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA
for the respective color components. The results are clamped to the range [0,1].
If #GL_MAP_COLOR is true, each color component is scaled by the size of lookup table #GL_PIXEL_MAP_c_TO_c, then replaced by
the value that it references in that table. c is R, G, B, or A respectively.
The GL then converts the resulting RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that
xn = xr + n % width yn = yr + n / width |
where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
#GL_RED
#GL_GREEN
#GL_BLUE
#GL_ALPHA
#GL_RGB
#GL_LUMINANCE
#GL_LUMINANCE_ALPHAThe rasterization described so far assumes pixel zoom factors of 1. If gl.PixelZoom() is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (xr,yr) is the current raster position, and a given pixel is in the nth column and mth row of the pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at
(xr + zoomx_n, yr + zoomy_m) |
and
(xr + zoomx_(n + 1), yr + zoomy_(m + 1)) |
where zoomx is the value of #GL_ZOOM_X and zoomy is the value of #GL_ZOOM_Y.
Please note that this command operates directly with memory pointers. There is also a version which works with tables instead of memory pointers, but this is slower of course. See gl.DrawPixels for details. See Working with pointers for details on how to use memory pointers with Hollywood.
Please consult an OpenGL reference manual for more information.
#GL_INVALID_ENUM is generated if format or type is not one of the accepted values.
#GL_INVALID_ENUM is generated if type is #GL_BITMAP and format is not either #GL_COLOR_INDEX or #GL_STENCIL_INDEX.
#GL_INVALID_VALUE is generated if either width or height is negative.
#GL_INVALID_OPERATION is generated if format is #GL_STENCIL_INDEX and there is no stencil buffer.
#GL_INVALID_OPERATION is generated if format is #GL_RED, #GL_GREEN, #GL_BLUE, #GL_ALPHA, #GL_RGB, #GL_RGBA, #GL_LUMINANCE, or #GL_LUMINANCE_ALPHA, and the GL is in color index mode.
#GL_INVALID_OPERATION is generated if gl.DrawPixelsRaw() is executed between the execution of gl.Begin() and the corresponding execution of gl.End() .
#GL_CURRENT_RASTER_POSITION
gl.Get() with argument #GL_CURRENT_RASTER_POSITION_VALID