pixmod(3G)pixmod(3G)NAMEpixmod - specify pixel transfer mode parameters
FORTRAN SPECIFICATION
subroutine pixmod(mode, value)
integer*4 mode, value
PARAMETERS
mode One of the symbolic constants:
(parameters that affect read, write, and copy transfers)
PMSHIF, 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
PMEXPA, 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
PMC0, 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
PMC1, 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
PMADD2, 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.
PMTTOB, 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)
PMRTOL, 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: PMABGR, PMBGR, PMRGBA, PMRGB, PMLUMI,
Page 1
pixmod(3G)pixmod(3G)
PMLUMA, PMALPH. If PMLUMI or PMLUMA is selected as the PMOFMT,
all of the other features of pixmod will be ignored except for
PMITYP, PMOTYP, PMOFFS, and PMSTRI.
PMITP, default values: PMUNSI. Specifies the type of pixel color
components. May be one of: PMBITM, PMBYTE, PMUNSI, PMSH12,
PMUS12, PMSHOR, PMUSHT, PMINT, PMUINT, PMFLOA.
PMOTP, default values: PMUNSI. Specifies the type of pixel color
components. May be one of: PMBITM, PMUNSI, PMSH12, PMUSSHT,
PMUINT, PMFLOA.
(parameters that affect read and write transfers only)
PMSIZE, 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.
PMOFFS, default value: 0. Number of bits of the first CPU word
of each scanline that are to be ignored. Valid values: 0 through
31
PMSTRI, 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)
PMZDAT, 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.
DESCRIPTIONpixmod 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: lrectr, lrectw, and rectco. Pixel transfer commands that
operate on 8-bit data (readRG, writeR) and on 16-bit data (readpi,
writep, rectre, rectwr) do not support pixmod capabilities. Note that
lrectr, lrectw, and rectco are valid in both color map and RGB modes.
Page 2
pixmod(3G)pixmod(3G)
Padding in CPU Memory
Transfer commands lrectr and lrectw 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 lrectr and lrectw must be long word aligned. If not,
an error message is generated and no action is taken.
Packing in CPU Memory
Transfer commands lrectr and lrectw 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 PMSIZE. 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 lrectw) 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
pixmod(3G)pixmod(3G)
Note that big-endian packing makes 8 and 16 bit packing equivalent to
integer*1 and integer*2 arrays. Remember, however, that the address
passed to lrectw or lrectr must be long-word aligned.
Packings of 1, 4, 8, 12, 16, 24, and 32 bits per pixel are supported.
Setting PMSIZE 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 PMSIZE.
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
pixmod(3G)pixmod(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 (lrectr, rectco) or unpacked from CPU
memory (lrectw) 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 PMSHIF 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 PMEXPA
to 1 (the default disabled value is 0). When expansion is enabled, zero
value pixels are replaced by the packed color PMC0, and one value pixels
are replaced by PMC1. Bits 11-0 of PMC0 and PMC1 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.
There are no constraints on the values of PMC0 or PMC1.
Page 5
pixmod(3G)pixmod(3G)
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 PMADD2 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 PMOFFS and PMSTRI support transfer operation on rectangular
pixels regions that reside within larger regions in CPU memory. PMOFFS,
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 lrectw transfer of 12-bit packed pixel data
with PMOFFS 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 + PMSTRI). PMOFFS pixels of this word are
skipped, then this scanline is transferred to the graphics engine. The
PMSTRI 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.
PMOFFS and PMSTRI, like PMSIZE, are ignored by framebuffer-to-framebuffer
transfers (rectco). They both default to a value of zero.
Alternate Fill Directions
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 PMRTOL and PMTTOB allow the horizontal and vertical read/fill
Page 6
pixmod(3G)pixmod(3G)
directions to be reversed, but do not change the fundamental row-major
scan order. PMRTOL specifies right-to-left traversal/fill when set to
one, left-to-right when set to its default value of zero. PMTTOB
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 lrectw and rectco of color values, because there are no source Z
values to do the buffer compares with. Setting PMZDAT 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 PMZDAT enabled, the
system automatically insures that no changes are made to color bitplanes,
regardless of the current color write mask. When PMZDAT and zbuffe 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 PMZDAT enabled and stencil set based on the outcome of the Z
comparison) and then of the color values (with PMZDAT disabled, drawn
conditionally based on the stencil value).
It is not necessary (or correct) to enable zdraw mode while doing pixel
transfers with PMZDAT enabled.
SEE ALSO
lrectr, lrectw, rectco, rectzo, stenci
NOTES
The Personal Iris, XS, XS24, Elan, XZ and Extreme systems do not support
pixmod during rectco. 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 pixmod when reading pixels and supports PMSIZE for values 8,
16, and 32 only. The Personal Iris, Indigo Entry, Indy, and XL support
PMOFFS for values that are multiples of PMSIZE only. When reading
pixels, XS, XS24, Elan, XZ and Extreme systems do not support PMOFFS not
equal to 0. On XS, XS24, Elan, XZ and Extreme systems, you get better
pixel fill rate (both write and read) if you specify PMTTOB (top-to-
bottom) as the direction of fill.
Page 7
pixmod(3G)pixmod(3G)
For writing interlaced fields of video data to the frame buffer, Indy and
XL systems write every other scan line, bottom-to-top, when PMTTOB is 2,
and every other scan line, top-to-bottom, when PMTTOB 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 PMSIZE
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 PMSIZE of 8.
PMSIZE,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.
PMOFT, PMOTP, PMIFT, PMITP are implemented on RealityEngine models only.
BUGS
On the Personal Iris, when using PMSIZE 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 PMSIZE of 24 is not supported in color
map mode. PMSIZE of 32 in conjunction with a non zero PMOFFS is not
supported as well in color map mode.
Page 8
