pixmod(3G)
pixmod - specify pixel transfer mode parameters
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
NAME pixmod - 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, 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. DESCRIPTION pixmod 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. 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. 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. 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. 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 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. 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.