gl.PixelTransfer(pname, param)
gl.PixelTransfer()
sets pixel transfer modes that affect the operation of subsequent gl.CopyPixels(),
gl.CopyTexImage(), gl.CopyTexSubImage(), gl.DrawPixels(),
gl.ReadPixels(), or also GL's gl.TexImage(), gl.TexImage1D(),
gl.TexImage2D(), gl.TexSubImage(), gl.TexSubImage1D(),
and gl.TexSubImage2D() commands. The algorithms that are specified by pixel transfer modes operate on
pixels after they are read from the frame buffer (gl.CopyPixels(), gl.CopyTexImage(),
gl.CopyTexSubImage(), gl.ReadPixels()) or in case they are unpacked from client memory
(gl.DrawPixels(), gl.TexImage(), gl.TexImage1D(),
gl.TexImage2D(), gl.TexSubImage(), gl.TexSubImage1D(),
and gl.TexSubImage2D()). Pixel transfer operations happen in the same order, and in the same manner,
regardless of the command that resulted in the pixel operation. Pixel storage modes (See gl.PixelStore for details.) control
the unpacking of pixels being read from client memory, and the packing of pixels being written back into client memory.
Pixel transfer operations handle four fundamental pixel types: color, color index, depth, and stencil. Color pixels consist of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0 represents zero intensity and 1 represents full intensity. Color indices comprise a single fixed-point value, with unspecified precision to the right of the binary point. Depth pixels comprise a single floating-point value, with unspecified mantissa and exponent sizes, scaled such that 0.0 represents the minimum depth buffer value, and 1.0 represents the maximum depth buffer value. Finally, stencil pixels comprise a single fixed-point value, with unspecified precision to the right of the binary point.
The pixel transfer operations performed on the four basic pixel types are as follows:
#GL_RED_SCALE
, then added to #GL_RED_BIAS
; the green component is multiplied by #GL_GREEN_SCALE
, then added to
#GL_GREEN_BIAS
; the blue component is multiplied by #GL_BLUE_SCALE
, then added to #GL_BLUE_BIAS
; and the alpha component is
multiplied by #GL_ALPHA_SCALE
, then added to #GL_ALPHA_BIAS
. After all four color components are scaled and biased, each is
clamped to the range [0, 1]. All color, scale, and bias values are specified with gl.PixelTransfer()
. If #GL_MAP_COLOR
is true,
each color component is scaled by the size of the corresponding color-to-color map, then replaced by the contents of that map
indexed by the scaled component. That is, the red component is scaled by #GL_PIXEL_MAP_R_TO_R_SIZE
, then replaced by the contents
of #GL_PIXEL_MAP_R_TO_R
indexed by itself. The green component is scaled by #GL_PIXEL_MAP_G_TO_G_SIZE
, then replaced by the
contents of #GL_PIXEL_MAP_G_TO_G
indexed by itself. The blue component is scaled by #GL_PIXEL_MAP_B_TO_B_SIZE
, then replaced
by the contents of #GL_PIXEL_MAP_B_TO_B
indexed by itself. And the alpha component is scaled by #GL_PIXEL_MAP_A_TO_A_SIZE
,
then replaced by the contents of #GL_PIXEL_MAP_A_TO_A
indexed by itself. All components taken from the maps are then clamped
to the range [0, 1]. #GL_MAP_COLOR
is specified with gl.PixelTransfer()
. The contents of the various maps are specified with
gl.PixelMap().
#GL_INDEX_SHIFT
bits; any bits beyond the number of fraction bits carried by the fixed-point
index are filled with zeros. If #GL_INDEX_SHIFT
is negative, the shift is to the right, again zero filled. Then #GL_INDEX_OFFSET
is added to the index. #GL_INDEX_SHIFT
and #GL_INDEX_OFFSET
are specified with gl.PixelTransfer()
.
From this point, operation diverges depending on the required format of the resulting pixels. If the resulting pixels are to be
written to a color index buffer, or if they are being read back to client memory in #GL_COLOR_INDEX
format, the pixels continue
to be treated as indices. If #GL_MAP_COLOR
is true, each index is masked by 2^n - 1, where n is #GL_PIXEL_MAP_I_TO_I_SIZE
, then
replaced by the contents of #GL_PIXEL_MAP_I_TO_I
indexed by the masked value. #GL_MAP_COLOR
is specified with gl.PixelTransfer()
.
The contents of the index map is specified with glPixelMap.
If the resulting pixels are to be written to an RGBA color buffer, or if they are read back to client memory in a format other
than #GL_COLOR_INDEX
, the pixels are converted from indices to colors by referencing the four maps #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
. Before being dereferenced, the index is masked by 2^n - 1, where n is #GL_PIXEL_MAP_I_TO_R_SIZE
for the red map, #GL_PIXEL_MAP_I_TO_G_SIZE
for the green map, #GL_PIXEL_MAP_I_TO_B_SIZE
for the blue map, and #GL_PIXEL_MAP_I_TO_A_SIZE
for
the alpha map. All components taken from the maps are then clamped to the range [0, 1]. The contents of the four maps is specified
with gl.PixelMap().
#GL_DEPTH_SCALE
, added to #GL_DEPTH_BIAS
, then clamped to the range [0, 1].
#GL_INDEX_SHIFT
bits just as a color index is, then added to #GL_INDEX_OFFSET
. If #GL_MAP_STENCIL
is true,
each index is masked by 2^n - 1, where n is #GL_PIXEL_MAP_S_TO_S_SIZE
, then replaced by the contents of #GL_PIXEL_MAP_S_TO_S
indexed by the masked value.
Please consult an OpenGL reference manual for more information.
pname
is set to#GL_INVALID_ENUM
is generated if pname
is not an accepted value.
#GL_INVALID_OPERATION
is generated if gl.PixelTransfer()
is executed between the execution of gl.Begin() and the corresponding execution of gl.End().
#GL_MAP_COLOR
gl.Get() with argument #GL_MAP_STENCIL
gl.Get() with argument #GL_INDEX_SHIFT
gl.Get() with argument #GL_INDEX_OFFSET
gl.Get() with argument #GL_RED_SCALE
gl.Get() with argument #GL_RED_BIAS
gl.Get() with argument #GL_GREEN_SCALE
gl.Get() with argument #GL_GREEN_BIAS
gl.Get() with argument #GL_BLUE_SCALE
gl.Get() with argument #GL_BLUE_BIAS
gl.Get() with argument #GL_ALPHA_SCALE
gl.Get() with argument #GL_ALPHA_BIAS
gl.Get() with argument #GL_DEPTH_SCALE
gl.Get() with argument #GL_DEPTH_BIAS