*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> standard/pixmode (3)              
Title
Content
Arch
Section
 

Contents


pixmode(3G)							   pixmode(3G)


NAME    [Toc]    [Back]

     pixmode - specify pixel transfer mode parameters

C SPECIFICATION    [Toc]    [Back]

     void pixmode(long mode, long value)

PARAMETERS    [Toc]    [Back]

     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 leastsignificant
 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-tobottom (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-toleft (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 nonnegative
 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.

DESCRIPTION    [Toc]    [Back]

     pixmode 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    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     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-toframebuffer
 transfers (rectcopy). They both default to a value of zero.

     Alternate Fill Directions    [Toc]    [Back]





									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, bottomto-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    [Toc]    [Back]

     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    [Toc]    [Back]

      
      
     lrectread,	lrectwrite, rectcopy, rectzoom,	stencil

NOTES    [Toc]    [Back]

     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    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 8888
[ Back ]
 Similar pages
Name OS Title
glpixelmap IRIX set up pixel transfer maps
glPixelTransfer Tru64 set pixel transfer modes
glpixeltransfer IRIX set pixel transfer modes
glPixelMap Tru64 set up pixel transfer maps
glPixelMapfv Tru64 set up pixel transfer maps
glPixelMapuiv Tru64 set up pixel transfer maps
glPixelMapusv Tru64 set up pixel transfer maps
glPixelTransferf Tru64 set pixel transfer modes
glPixelTransferi Tru64 set pixel transfer modes
pixelmap IRIX define pixel transfer LUTs
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service