glPixelTransferf,
glPixelTransferi
[New
- Windows 95, OEM Service Release 2]
The glPixelTransferf
and glPixelTransferi functions set pixel transfer modes.
void glPixelTransferf(
|
GLenum pname, |
|
|
GLfloat param |
|
|
); |
|
void glPixelTransferi(
|
GLenum pname, |
|
|
GLint param |
|
|
); |
|
Parameters
pname
The symbolic
name of the pixel transfer parameter to be set. The following table gives the
type, initial value, and range of valid values for each of the pixel transfer
parameters that are set with glPixelTransfer.
|
Pname |
Type |
Initial Value |
Valid Range |
|
GL_MAP_COLOR |
Boolean |
false |
true/false |
|
GL_MAP_STENCIL |
Boolean |
false |
true/false |
|
GL_INDEX_SHIFT |
integer |
0 |
( -
,) |
|
GL_INDEX_OFFSET |
integer |
0 |
( -
,) |
|
GL_RED_SCALE |
float |
1.0 |
( -
,) |
|
GL_GREEN_SCALE |
float |
1.0 |
( -
,) |
|
GL_BLUE_SCALE |
float |
1.0 |
( -
,) |
|
GL_ALPHA_SCALE |
float |
1.0 |
( -
,) |
|
GL_DEPTH_SCALE |
float |
1.0 |
( -
,) |
|
GL_RED_BIAS |
float |
0.0 |
( -
,) |
|
GL_GREEN_BIAS |
float |
0.0 |
( -
,) |
|
GL_BLUE_BIAS |
float |
0.0 |
( -
,) |
|
GL_ALPHA_BIAS |
float |
0.0 |
( -
,) |
|
GL_DEPTH_BIAS |
float |
0.0 |
( -
,) |
param
The value
that pname is set to.
Remarks
The glPixelTransfer
function sets pixel transfer modes that affect the operation of subsequent glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, and glTexImage2D commands. The algorithms
that are specified by pixel transfer modes operate on pixels after they are
read from the frame buffer (glReadPixels and glCopyPixels) or
unpacked from client memory (glDrawPixels, glTexImage1D, and glTexImage2D).
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 (glPixelStore)
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 are made up of four
floating-point values with unspecified mantissa and exponent sizes, scaled such
that 0.0 represents zero intensity and 1.0 represents full intensity. Color
indexes 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:
Color
Each of the
four color components is multiplied by a scale factor, and then added to a bias
factor. That is, the red component is multiplied by GL_RED_SCALE, and then
added to GL_RED_BIAS; the green component is multiplied by GL_GREEN_SCALE, and
then added to GL_GREEN_BIAS; the blue component is multiplied by GL_BLUE_SCALE,
and then added to GL_BLUE_BIAS; and the alpha component is multiplied by
GL_ALPHA_SCALE, and 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 glPixelTransfer.
If
GL_MAP_COLOR is true, each color component is scaled by the size of the
corresponding color-to-color map, and 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, and 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, and 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,
and then replaced by the contents of GL_PIXEL_MAP_B_TO_B indexed by itself. The
alpha component is scaled by GL_PIXEL_MAP_A_TO_A_SIZE, and 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 glPixelTransfer.
The contents of the various maps are specified with glPixelMap.
Color
index
Each color
index is shifted left by GL_INDEX_SHIFT bits, filling with zeros any bits
beyond the number of fraction bits carried by the fixed-point index. If
GL_INDEX_SHIFT is negative, the shift is to the right, again zero filled.
GL_INDEX_OFFSET is then added to the index. GL_INDEX_SHIFT and GL_INDEX_OFFSET
are specified with glPixelTransfer.
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 indexes. If GL_MAP_COLOR is true, then each
index is masked by 2^n - 1,
where n is GL_PIXEL_MAP_I_TO_I_SIZE, and then replaced by the contents
of GL_PIXEL_MAP_I_TO_I indexed by the masked value. GL_MAP_COLOR is specified
with glPixelTransfer. The contents of the index map are specified with glPixelMap.
If the
resulting pixels are to be written to an RGBA color buffer, or if they are
being read back to client memory in a format other than GL_COLOR_INDEX, the
pixels are converted from indexes 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 2n - 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 are specified with glPixelMap.
Depth
Each depth
value is multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and then clamped
to the range [0,1].
Stencil
Each index is
shifted GL_INDEX_SHIFT bits just as a color index is, and 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.
The
glPixelTransferf function can be used to set any pixel transfer parameter.
If the parameter type is Boolean, 0.0 implies false and any other value implies
true. If pname is an integer parameter, param is rounded to the
nearest integer.
Likewise, glPixelTransferi
can also be used to set any of the pixel transfer parameters. Boolean
parameters are set to false if param is 0 and true otherwise. The param
parameter is converted to floating point before being assigned to real-valued
parameters.
If a glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, or glTexImage2D command is placed in a
display list (see glNewList
and glCallList),
the pixel transfer mode settings in effect when the display list is executed
are the ones that are used. They may be different from the settings when the
command was compiled into the display list.
The following
functions retrieve information related to glPixelTransfer:
glGet
with argument GL_MAP_COLOR
glGet with
argument GL_MAP_STENCIL
glGet with
argument GL_INDEX_SHIFT
glGet with
argument GL_INDEX_OFFSET
glGet with
argument GL_RED_SCALE
glGet with
argument GL_RED_BIAS
glGet with
argument GL_GREEN_SCALE
glGet with
argument GL_GREEN_BIAS
glGet with
argument GL_BLUE_SCALE
glGet with
argument GL_BLUE_BIAS
glGet with
argument GL_ALPHA_SCALE
glGet with
argument GL_ALPHA_BIAS
glGet with
argument GL_DEPTH_SCALE
glGet with
argument GL_DEPTH_BIAS
Error Codes
The following
are the error codes generated and their conditions.
|
Error
Code |
Condition |
|
GL_INVALID_ENUM
|
pname was not an accepted value. |
|
GL_INVALID_OPERATION
|
glPixelTransfer was called between a call to glBegin and the
corresponding call to glEnd. |
See Also