pixmode(3G)pixmode(3G)NAMEpixmode - specify pixel transfer mode parameters
C SPECIFICATION
void pixmode(long mode, long value)
PARAMETERS
mode One of the symbolic constants:
(parameters that affect read, write, and copy transfers)
PM_SHIFT, default value: 0. Number of bit positions that pixel
data are to be shifted. Positive shifts are left for write and
copy, right for read. Valid values: 0, +-1, +-4, +-8, +-12, +-
16, +-24
PM_EXPAND, default value: 0. Enable (1) or disable (0) expansion
of single-bit pixel data to one of two 32-bit pixel values.
Valid values: 0, 1
PM_C0, default value: 0. Expansion value (32-bit packed color)
chosen when the single-bit pixel being expanded is zero. Valid
values: any 32-bit value
PM_C1, default value: 0. Expansion value (32-bit packed color)
chosen when the single-bit pixel being expanded is one. Valid
values: any 32-bit value
PM_ADD24, default value: 0. Amount to be added to the least-
significant 24 bits of the pixel (signed value). Valid values: a
32-bit signed value in the range -0x800000 through 0x7fffff
Although this value is specified as a 32-bit integer, the sign
bit MUST be smeared across all 32 bits. Thus -0x800000 specifies
the minimum value; and 0x800000 is out of range at the positive
end.
PM_TTOB, default value: 0. Specifies that fill (for write and
copy transfers) and read (for read transfers) must be top-to-
bottom (1) or bottom-to-top (0). Valid values: 0, 1 (see NOTES
below)
PM_RTOL, default value: 0. Specifies that fill (for write and
copy transfers) and read (for read transfers) is to be right-to-
left (1) or left-to-right (0). Valid values: 0, 1
PM_INPUT_FORMAT, PM_OUTPUT_FORMAT, default values: PM_ABGR. If in
RGBmode, specifies the pixel color component format; if in cmode,
has no effect. The format specifies the number and order of color
components. May be one of: PM_ABGR, PM_BGR, PM_RGBA, PM_RGB,
PM_LUMINANCE, PM_LUMINANCEA, PM_ALPHA. If PM_LUMINANCE or
Page 1
pixmode(3G)pixmode(3G)
PM_LUMINANCEA is selected as the PM_OUTPUT_FORMAT, all of the
other features of pixmode will be ignored except for
PM_INPUT_TYPE, PM_OUTPUT_TYPE, PM_OFFSET, and PM_STRIDE.
PM_INPUT_TYPE, default values: PM_UNSIGNED_BYTE. Specifies the
type of pixel color components. May be one of: PM_BITMAP,
PM_BYTE, PM_UNSIGNED_BYTE, PM_SHORT_12, PM_UNSIGNED_SHORT_12,
PM_SHORT, PM_UNSIGNED_SHORT, PM_INT, PM_UNSIGNED_INT, PM_FLOAT.
PM_OUTPUT_TYPE, default values: PM_UNSIGNED_BYTE. Specifies the
type of pixel color components. May be one of: PM_BITMAP,
PM_UNSIGNED_BYTE, PM_UNSIGNED_SHORT_12, PM_UNSIGNED_SHORT,
PM_UNSIGNED_INT, PM_FLOAT.
(parameters that affect read and write transfers only)
PM_SIZE, default value: 32. Number of bits per pixel. Used for
packing during reads and writes. Valid values: 1, 4, 8, 12, 16,
24, 32, 64 (see NOTES below)
Although size specification is for the entire pixel, there is no
mechanism for specifying reduced RGBA component sizes (such as
12-bit RGB with 4 bits per component) except as in NOTES below.
PM_OFFSET, default value: 0. Number of bits of the first CPU
word of each scanline that are to be ignored. Valid values: 0
through 31
PM_STRIDE, default value: 0. Number of 32-bit CPU words per
scanline in the original image (not just the portion that is
being transferred by this command). Valid values: any non-
negative integer
(parameters that affect write and copy transfers only)
PM_ZDATA, default value: 0. Indicates (1) that pixel data are to
be treated as Z data rather than color data (0). Destination is
the Z-buffer. Writes are conditional if zbuffering is on. Valid
values: 0, 1
value Integer value assigned to mode.
DESCRIPTIONpixmode allows a variety of pixel transfer options to be selected. These
options are available only for pixel transfer commands that operate on
32-bit data: lrectread, lrectwrite, and rectcopy. Pixel transfer commands
that operate on 8-bit data (readRGB, writeRGB) and on 16-bit data
(readpixels, writepixels, rectread, rectwrite) do not support pixmode
capabilities. Note that lrectread, lrectwrite, and rectcopy are valid in
both color map and RGB modes.
Page 2
pixmode(3G)pixmode(3G)
Padding in CPU Memory
Transfer commands lrectread and lrectwrite operate on pixel data
structures in CPU memory. These data structures contain data organized
in row-major format, each row corresponding to one scanline of pixel
data. Adjacent pixels are packed next to each other with no padding,
regardless of the pixel size. Thus in many cases pixels straddle the
32-bit word boundaries. It is always the case, however, that each scan
line comprises an integer number of whole 32-bit words. If the pixel
data do not exactly fill these words, the last word is padded with
(undefined) data.
Addresses passed to lrectread and lrectwrite must be long word aligned.
If not, an error message is generated and no action is taken.
Packing in CPU Memory
Transfer commands lrectread and lrectwrite operate on pixel data that are
packed tightly into CPU memory. Adjacent pixels, regardless of their
size, are stored with no bit padding between them. Pixel size, and thus
packing, is specified by PM_SIZE. The default value of this parameter is
32, meaning that 32-bit pixels are packed into 32-bit CPU memory words.
Although the MIPS processor is a big-endian machine, its bit numbering is
little-endian. Pixel data are packed consistent with the byte numbering
scheme (big-endian), ignoring the bit numbering. Thus, 12-bit packed
pixels are taken as follows (by lrectwrite) from the first 32-bit word of
a CPU data structure:
first CPU word
byte number 0 1 2 3
bit number 33222222 22221111 111111
10987654 32109876 54321098 76543210
first unpacked pixel 11
10987654 3210
second unpacked pixel 11
1098 76543210
third unpacked pixel 11
10987654 ...
When being written, unpacked pixels are padded to the left with zeros to
make their size equal to the size of the framebuffer target region (12
bits total in color map mode, 24 bits total when writing Z values, 32
bits total in RGB mode). The least significant bit of the unpacked pixel
becomes the least significant bit of the framebuffer pixel it replaces.
Page 3
pixmode(3G)pixmode(3G)
Note that big-endian packing makes 8 and 16 bit packing equivalent to
character and short arrays. Remember, however, that the address passed
to lrectwrite or lrectread must be long-word aligned.
Packings of 1, 4, 8, 12, 16, 24, and 32 bits per pixel are supported.
Setting PM_SIZE to a value other than one of these results in an error
message, and leaves the current size unchanged.
Order of Pixel Operations
In addition to packing and unpacking, pixel streams are operated on in a
variety of other ways. These operations occur in a consistent order,
regardless of whether the stream is being written, read, or copied.
write unpack->shift->expand->add24->zoom->fbpack
copy format->shift->expand->add24->zoom->fbpack
read format->shift->expand->add24 ->pack
Note that pixel data are unpacked only when being transferred from CPU
memory to the framebuffer. Unpacking occurs prior to any other
operation. Likewise, pixel data are packed only when being transferred
to CPU memory. Packing occurs after all other operations have been
completed. Because copy operations neither pack nor unpack pixel data,
the rectcopy command ignores the value of PM_SIZE.
Framebuffer Format
Each IRIS framebuffer is always configured in one of two fundamental
ways: color map or RGB. In the RGB configuration 3 or 4 color components
(red, green, blue, and optionally alpha) are stored at each pixel
location. Each component is stored with a maximum of 8 bits of
precision, resulting in a packed 32-bit pixel with the following format:
33222222 22221111 111111
10987654 32109876 54321098 76543210
aaaaaaaa bbbbbbbb gggggggg rrrrrrrr
76543210 76543210 76543210 76543210
Some IRIS framebuffers store fewer than 8 bits per color component while
in RGB mode. These framebuffers, however, emulate all the behavior of
full 32-bit framebuffers. Thus the first operation in both the copy and
read streams (above) is format: converting the framebuffer-format data to
the 8-bit per component RGBA format that all subsequent operations
execute with. Likewise, the final operation in both the write and copy
streams (above) is fbpack: converting the 8-bit per component RGBA data
back to the hardware-specific storage format. Both the format and the
fbpack operation are null operations if the hardware supports full 32-bit
RGBA data.
Page 4
pixmode(3G)pixmode(3G)
In its color map configuration a single color index, from 1 to 12 bits,
is stored at each pixel location:
33222222 22221111 111111
10987654 32109876 54321098 76543210
iiii iiiiiiii
11
1098 76543210
Pixel Shifting
Pixels taken from the framebuffer (lrectread, rectcopy) or unpacked from
CPU memory (lrectwrite) are first rotated either left or right by an
amount up to 24 bit positions. Unpacked pixels and pixel values to be
packed are padded left and right by zeros during the shift operation.
The resulting 32-bit pixel values therefore include ones only in the
region that was filled with legitimate pre-shifted data. Copied pixels
may not be padded with zeros; thus a writemask may be required to
eliminate unwanted bits.
Pixel shifting is enabled by setting PM_SHIFT to a non-zero value.
Positive values in the range 1-24 specify left shifts while writing or
copying, right shifts while reading. Negative values in the range -1
through -24 specify right shifts while writing or copying, left shifts
while reading.
The default shift value is zero (i.e. shifting disabled). Other accepted
values are plus and minus 1, 4, 8, 12, 16, and 24.
Because pixels are always converted to the formats described above before
they are shifted, shift operations are largely independent of the
hardware framebuffer storage format.
Pixel Expansion
Single bit pixels can be expanded to one of two full 32-bit color values,
based on their binary value. This expansion is enabled by setting
PM_EXPAND to 1 (the default disabled value is 0). When expansion is
enabled, zero value pixels are replaced by the packed color PM_C0, and
one value pixels are replaced by PM_C1. Bits 11-0 of PM_C0 and PM_C1
specify color index values when in color map mode.
Pixel expansion is actually controlled by bit zero of the incoming pixel
(regardless of the size of the incoming pixel). Because pixel shifting
precedes pixel expansion, any bit of the incoming pixel can be selected
to control pixel expansion.
Page 5
pixmode(3G)pixmode(3G)
There are no constraints on the values of PM_C0 or PM_C1.
Pixel Addition
The pixel addition stage treats the lower 24 bits of each incoming pixel
as a signed integer value. It adds a signed 24-bit constant to this
field of the pixel, leaving the upper 8 bits unchanged. The result of
the addition is clamped to the range -223 through 223 - 1. While this
addition is most useful when writing or copying depth data, it is enabled
during all transfers. Thus PM_ADD24 is typically changed from its
default zero value only while depth transfers are being done (See
"Drawing Z Data" below). Pixel addition can also be used to offset the
range of a color map image.
Rectangle within Rectangle in CPU Memory
Variables PM_OFFSET and PM_STRIDE support transfer operation on
rectangular pixels regions that reside within larger regions in CPU
memory. PM_OFFSET, set to a value in the range 0-31, specifies the
number of significant bits of the first CPU word that are ignored at the
start of each scanline transfer. For example, an lrectwrite transfer of
12-bit packed pixel data with PM_OFFSET set to 12 results in the
following pixel extraction:
first CPU word of each scanline
byte number 0 1 2 3
bit number 33222222 22221111 111111
10987654 32109876 54321098 76543210
first unpacked pixel 11
1098 76543210
second unpacked pixel 11
10987654 ...
Pixel unpacking continues tightly throughout all the CPU words that
define a single scanline. After the last CPU word that defines a
scanline has been transferred, the CPU read pointer is advanced to the
32-bit word at location (first + PM_STRIDE). PM_OFFSET pixels of this
word are skipped, then this scanline is transferred to the graphics
engine. The PM_STRIDE value of zero is exceptional, causing the CPU read
pointer to be advanced to the 32-bit word that immediately follows the
last word of each scanline.
PM_OFFSET and PM_STRIDE, like PM_SIZE, are ignored by framebuffer-to-
framebuffer transfers (rectcopy). They both default to a value of zero.
Alternate Fill Directions
Page 6
pixmode(3G)pixmode(3G)
During read, copy, and write pixel operations pixels are always
transferred in row-major order. By default scanlines are read or written
left-to-right, starting with the bottom scanline and working up.
Parameters PM_RTOL and PM_TTOB allow the horizontal and vertical
read/fill directions to be reversed, but do not change the fundamental
row-major scan order. PM_RTOL specifies right-to-left traversal/fill
when set to one, left-to-right when set to its default value of zero.
PM_TTOB specifies top-to-bottom traversal/fill when set to one, bottom-
to-top when set to its default value of zero.
These parameters can be used to properly deal with CPU data formats that
differ from the default IRIS pixel order. They also can be used to
generate image reflections about either the X or Y screen axes. (see
notes.)
Fill direction does not affect the location of the destination rectangle
(i.e. the destination rectangle is always specified by its lower-left
pixel, regardless of its traversal/fill direction).
Drawing Z Data
Normally pixel data are treated as colors. Zbuffer mode must be false
during lrectwrite and rectcopy of color values, because there are no
source Z values to do the buffer compares with. Setting PM_ZDATA to 1.0,
however, instructs the GL to treat incoming pixel values as Z values, and
to treat source color as undefined. When drawing pixels with PM_ZDATA
enabled, the system automatically insures that no changes are made to
color bitplanes, regardless of the current color write mask. When
PM_ZDATA and zbuffer are both enabled, pixel values will be conditionally
written into the z-buffer in the usual manner, and the color buffer will
be unaffected.
Z-buffered images are drawn by doing two transfers, first of the Z values
(with PM_ZDATA enabled and stencil set based on the outcome of the Z
comparison) and then of the color values (with PM_ZDATA disabled, drawn
conditionally based on the stencil value).
It is not necessary (or correct) to enable zdraw mode while doing pixel
transfers with PM_ZDATA enabled.
SEE ALSO
lrectread, lrectwrite, rectcopy, rectzoom, stencil
NOTES
The Personal Iris, XS, XS24, Elan, XZ and Extreme systems do not support
pixmode during rectcopy. IRIS-4D G, GT, GTX, Personal Iris, Indigo
Entry, Indy, and XL models do not support PM_ZDATA mode. The Personal
Iris does not support pixmode when reading pixels and supports PM_SIZE
for values 8, 16, and 32 only. The Personal Iris, Indigo Entry, Indy,
and XL support PM_OFFSET for values that are multiples of PM_SIZE only.
When reading pixels, XS, XS24, Elan, XZ and Extreme systems do not
support PM_OFFSET not equal to 0. On XS, XS24, Elan, XZ and Extreme
Page 7
pixmode(3G)pixmode(3G)
systems, you get better pixel fill rate (both write and read) if you
specify PM_TTOB (top-to-bottom) as the direction of fill.
For writing interlaced fields of video data to the frame buffer, Indy and
XL systems write every other scan line, bottom-to-top, when PM_TTOB is 2,
and every other scan line, top-to-bottom, when PM_TTOB is 3.
Indy and XL systems support a 3-3-2 pixel format in a byte (rightmost
three bits red, next three bits green, and next two bits blue) for
PM_SIZE of 9. Indigo Entry systems support a 3-3-2 pixel format in a
byte (rightmost three bits red, next two bits blue, and next three bits
green) for PM_SIZE of 8.
PM_SIZE,64 is implemented on RealityEngine models only. Each 64-bit
pixel contains four 16-bit color components for red (rightmost), green,
blue, and alpha (leftmost). Only the upper 12 bits of each component are
significant. The lower 4 bits are returned as zero.
PM_OUTPUT_FORMAT, PM_OUTPUT_TYPE, PM_INPUT_FORMAT, PM_INPUT_TYPE are
implemented on RealityEngine models only.
BUGS
On the Personal Iris, when using PM_SIZE with values 8 or 16, the width
of the rectangle drawn must be a multiple of 4 for 8-bit packed writes,
and a multiple of 2 for 16-bit packed writes.
On the IRIS-4D RealityEngine model PM_SIZE of 24 is not supported in
color map mode. PM_SIZE of 32 in conjunction with a non zero PM_OFFSET is
not supported as well in color map mode.
Page 8
