.TH gDPSetAlphaCompare 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gDPSetAlphaCompare, gsDPSetAlphaCompare
\- set alpha compare mode for conditional write to framebuffer.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gDPSetAlphaCompare(Gfx *gdl, unsigned int mode)

gsDPSetAlphaCompare(unsigned int mode)

\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I mode
\f3G_AC_NONE, G_AC_THRESHOLD, G_AC_DITHER.\fP
.SH DESCRIPTION
\f3G_AC_NONE\fP mode will disable alpha compare checking.
.PP
\f3G_AC_THRESHOLD\fP mode will conditionally update the framebuffer if the pipeline pixel alpha is greater than the blend color alpha.
This is typically used to cut out transparent regions of a texture map to give complex outlined objects.
This is more efficient than rendering translucent surfaces and writing the actual transparent regions.
.PP
\f3G_AC_DITHER\fP mode will conditionally update the framebuffer if the 
pipeline pixel alpha is greater than a random dither value.
Using this with an alpha gradient on a surface can give a nice 
particle fade out result.
.PP
You should use the Render Mode \f3G_RM_TEX_EDGE\fP when
enabling alpha compare in \f3G_CYC_1CYCLE\fP or \f3G_CYC_2CYCLE\fP pipeline
mode.  This is because you must get the alpha of the pixel on the coverage
path in order for the compare to work and this mode prevents reading of the 
color framebuffer.
.PP
\f3G_AC_THRESHOLD\fP and \f3G_AC_DITHER\fP modes can also be used when the 
pipeline is in \f3G_CYC_COPY\fP mode. Because normal alpha blending is 
disabled in copy mode, this is the only way to achieve transparency in
copy mode.  For 16-bit RGBA (5/5/5/1) frame buffers, the alpha bit acts as a
write enable, i.e. no compare with the blend alpha is performed.  For 8-bit
CI frame buffers, the blend alpha compare is enabled.  Copy mode can not be
used for 32-bit RGBA framebuffers.
.SH NOTE
If using antialiasing rendering modes,
\f3G_AC_THRESHOLD\fP can only threshhold against blend color alpha=0.
.SH SEE ALSO
.IR gDPSetBlendColor (3P)