stencil(3G)							   stencil(3G)

NAME    [Toc]    [Back]

     stencil - alter the operating parameters of the stencil

C SPECIFICATION    [Toc]    [Back]

     void stencil(enable, ref, func, mask, fail, pass, zpass)
     long enable;
     unsigned long ref;
     long func;
     unsigned long mask;
     long fail,	pass, zpass;

PARAMETERS    [Toc]    [Back]

     enable   expects either TRUE or FALSE, enabling or	disabling stencil
	      operation.  When stencil operation is disabled (the default),
	      the values of the	subsequent six parameters are ignored,

     ref      expects a	reference value	used by	the stencil compare function.

     func     expects one of eight flags specifying the	stencil	comparison
	      function.	 These flags are SF_NEVER, SF_LESS, SF_EQUAL,
	      SF_LEQUAL, SF_GREATER, SF_NOTEQUAL, SF_GEQUAL, and SF_ALWAYS.

     mask     expects a	mask specifying	which stencil bitplanes	are
	      significant during the comparison	operation.

     fail     expects one of six flags indicating which	stencil	operation
	      should be	performed should the stencil test fail.	 The values
	      are ST_KEEP, ST_ZERO, ST_REPLACE,	ST_INCR, ST_DECR, and
	      ST_INVERT.

     pass     expects one of six flags indicating which	stencil	operation
	      should be	performed should the stencil test pass,	and the	zbuffer
 test (if z-buffering is enabled) fail.  The values	are
	      ST_KEEP, ST_ZERO,	ST_REPLACE, ST_INCR, ST_DECR, and ST_INVERT.

     zpass    expects one of six flags indicating which	stencil	operation
	      should be	performed should the stencil and z-buffer tests	pass.
	      Its value	is not significant when	the z-buffer is	not enabled.
	      The values are ST_KEEP, ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR,
	      and ST_INVERT.

DESCRIPTION    [Toc]    [Back]

     stencil operates as a superior z-buffer test with a different algorithm.
     When stencil is enabled, each pixel write first tests the stencil
     bitplanes.	 Both the color	and z-buffer bitplane writes, as well as the
     write of the stencil bitplanes, are conditioned by	the stencil test.
     stencil operation can be enabled only if stencil bitplanes	are present
     (see stensize).  Stencil bitplanes	are present only in the	normal
     framebuffer, so stencil should be called only while draw mode is
     NORMALDRAW.





									Page 1






stencil(3G)							   stencil(3G)



     When the z-buffer is enabled, three test cases are	distinguished:

     fail     Stencil test fails.

     pass     Stencil test passes, but z-buffer	test fails.

     zpass    Stencil test passes, and z-buffer	test passes.

     (When the z-buffer	is not enabled,	only cases fail	and pass are
     considered.)  In all three	cases the stencil bitplanes are	updated	with a
     potentially new value.  This value	is a function of the case.  The	user
     specifies,	for each case, which of	six possible values will be used:

     ST_KEEP	   Keep	the current value (no change).

     ST_ZERO	   Replace with	zero.

     ST_REPLACE	   Replace with	the reference value.

     ST_INCR	   Increment by	one (clamp to max).

     ST_DECR	   Decrement by	one (clamp to zero).

     ST_INVERT	   Invert all bits.

     Arguments fail, pass, and zpass are each specified	as one of ST_KEEP,
     ST_ZERO, ST_REPLACE, ST_INCR, ST_DECR, and	ST_INVERT.

     ref is the	reference value	used by	the function that determines whether
     the stencil test passes or	fails.	func specifies the comparison between
     ref and the current stencil plane value.  This comparison function	is
     specified with the	flags:

     SF_NEVER	    Never pass.

     SF_LESS	    Pass if ref	is less	than stencil.

     SF_LEQUAL	    Pass if ref	is less	than or	equal to stencil.

     SF_EQUAL	    Pass if ref	is equal to stencil.

     SF_GREATER	    Pass if ref	is greater than	stencil.

     SF_GEQUAL	    Pass if ref	is greater than	or equal to stencil.

     SF_NOTEQUAL    Pass if ref	is not equal to	stencil.

     SF_ALWAYS	    Always pass.

     The stencil bitplanes are treated as an unsigned integer of planes	bits,
     where planes is the value passed to stensize to allocate the stencil
     buffer.



									Page 2






stencil(3G)							   stencil(3G)



     mask is a field that specifies which stencil bitplanes are	to be
     considered	by the test.  It does not affect which bitplanes are updated.

     If	the z-buffer is	enabled, color and depth fields	are drawn only in the
     zpass case	(both the stencil and depth tests pass).  If the z-buffer is
     not enabled, color	is drawn only in the pass case.	 The zpass case	is
     ignored.

SEE ALSO    [Toc]    [Back]

     drawmode, polymode, sclear, stensize, swritemask, zbuffer

NOTES    [Toc]    [Back]

     IRIS-4D G,	GT, and	GTX models, as well as the Personal Iris, Iris Indy,
     Iris Indigo Entry,	and Indigo XL, do not support stencil.	Use getgdesc
     to	determine whether stencil is supported.

     stencil is	supported only in the normal framebuffer, and is therefore
     effective only while draw mode is NORMALDRAW.

BUGS    [Toc]    [Back]

     IRIS-4D VGX models	do not support stencil operation when afunction	is
     enabled.


									PPPPaaaaggggeeee 3333