afunction(3G)

NAME
     afunction - specify alpha test function

C SPECIFICATION
     void afunction(ref, func)
     long ref, func;

PARAMETERS
     ref    expects a reference value with which to compare source alpha at
            each pixel.  This value should be in the range 0 through 255.

     func   is a symbolic constant taken from the list below.  It identifies
            the alpha comparison function:  AF_NEVER, AF_LESS, AF_EQUAL,
            AF_LEQUAL, AF_GREATER, AF_NOTEQUAL, AF_GEQUAL, and AF_ALWAYS.
            AF_ALWAYS is the default.

DESCRIPTION
     afunction makes the drawing of pixels conditional on the relationship of
     the incoming alpha value with a reference constant value.  It is
     typically used to avoid updating either the color or the z bitplanes of a
     framebuffer pixel when the incoming pixel is completely transparent.
     Arguments ref and func specify the conditions under which the pixel will
     be drawn.  The incoming (source) alpha value is compared against ref with
     function func.  This comparison function is specified with the symbolic
     constants:

     AF_NEVER       Never pass.

     AF_LESS        Pass if alpha is less than ref.

     AF_EQUAL       Pass if alpha is equal to ref.

     AF_LEQUAL      Pass if alpha is less than or equal to ref.

     AF_GREATER     Pass if alpha is greater than ref.

     AF_GEQUAL      Pass if alpha is greater than or equal to ref.

     AF_NOTEQUAL    Pass if alpha is not equal to ref.

     AF_ALWAYS      Always pass.

     If the comparison passes, the incoming pixel is drawn (conditional on
     subsequent other tests like z-buffer).

     afunction can be called with arguments 0,AF_NOTEQUAL to defeat drawing of
     completely transparent pixels.  This assumes that incoming alpha is
     proportional to pixel coverage, as it is when either pointsmooth or
     linesmooth is being used.
     afunction testing follows scan conversion and texture mapping but
     precedes all other pixel tests.  Thus, if the test fails, color, zbuffer
     and stencil contents will not be modified.

     afunction operates on all pixel writes, including those resulting from
     the scan conversion of points, lines, and polygons, and from pixel write
     and copy operations. afunction does not affect screen clear operation,
     however.

SEE ALSO
     blendfunction

NOTES
     IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support
     afunction.  Use getgdesc to determine what support is available for
     afunction.

BUGS
     On IRIS-4D VGX, XS, XS24, XZ, Elan and Extreme models, afunction cannot
     be enabled while stencil is being used.  Also on these models, only
     AF_NOTEQUAL with ref equal to 0 and AF_ALWAYS are supported.