czclear(3G)

NAME
     czclear - clears the color bitplanes and the z-buffer simultaneously

C SPECIFICATION
     void czclear(unsigned long cval, long zval)

PARAMETERS
     cval   expects the color to which you want to clear the color bitplanes.

     zval   expects the depth value to which you want to clear the z-buffer.

DESCRIPTION
     czclear sets the color bitplanes in the area of the viewport to cval, and
     the z buffer bitplanes in the area of the viewport to zval.  Multiple
     color bitplane buffers can be cleared simultaneously using the backbuffer
     and frontbuffer commands.  The screen mask, when it is set to a subregion
     of the viewport, bounds the cleared region.  Most other drawing modes,
     including alpha function, blend function, logical operation, polygon fill
     pattern, stenciling, texture mapping, writemask, zwritemask, and z
     buffering, have no effect on the operation of czclear.  The current color
     does not change.

     Because only the normal framebuffer includes a z buffer, czclear should
     be called only while draw mode is NORMALDRAW.

     In RGB mode, the cval parameter expects a packed integer of the same
     format used by cpack, namely 0xaabbggrr, where rr is the red value, bb
     the blue value, gg the green value, and aa is the alpha value.  In color
     map mode this parameter expects an index into the current color map, so
     only up to 12 of the least-significant bits are significant.

     The valid range of the zval parameter depends on the graphics hardware.
     When multisample is enabled, and multisample buffers exist in the current
     framebuffer configuration in the current drawmode, the minimum is the
     value returned by getgconfig(GC_MS_ZMIN) and the maximum is the value
     returned by getgconfig(GC_MS_ZMAX).  Otherwise, the minimum is the value
     returned by getgconfig(GC_ZMIN) and the maximum is the value returned by
     getgconfig(GC_ZMAX).  It is unaffected by the state of the GLC_ZRANGEMAP
     compatibility mode (see glcompat).

     After czclear executes, the graphics position is undefined.

SEE ALSO
     afunction, blendfunction, clear, cpack, getgdesc, glcompat, logicop,
     scrmask, setpattern, stencil, texbind, wmpack, writemask, zbuffer,
     zclear, zfunction

NOTES
     Whenever you need to clear both the z-buffer and the color bitplanes to
     constant values at the same time, use czclear.  A simultaneous clear will
     take place if circumstances allow it.  There is never a penalty in
     calling czclear over calling clear and zclear sequentially.
     IRIS-4D GT and GTX models can do a simultaneous clear only under the
     following circumstances:

     o    In RGB mode, the 24 least significant bits of cval (red, green, and
          blue) must be identical to the 24 least significant bits of zval.

     o    In color map mode, the 12 least significant bits of cval must be
          identical to the 12 least significant bits of zval.

     IRIS-4D VGX models always clear color and z bitplanes banks sequentially,
     regardless of the values of cval and zval.

     On the Personal Iris, XS, XS24, XZ, Elan and Extreme, you can speed up
     czclear by as much as a factor of four for common values of zval if you
     call zfunction in conjunction with it such that one of the following
     conditions are met:

                   _____________________________________________
                          zval        |        zfunction
                   _____________________________________________
                    getgdesc(GD_ZMIN)   ZF_GREATER or ZF_GEQUAL
                    getgdesc(GD_ZMAX)   ZF_LESS or ZF_LEQUAL
                   _____________________________________________
                   |



                                                                |





     Iris Indigo, Indy, and XL systems have a 32-bit zbuffer so use
     getgdesc(GD_ZMAX) to get the maximum z value and getgdesc(GD_ZMIN) to get
     the minimum z value.

     For performance reasons, Elan, XS, and XS24 products do not physically
     clear the z-buffer when calling czclear.  On these systems, the LSB of
     the z-buffer is used as a flag bit to signal that the z-buffer has been
     cleared.  The 23 remaining bits are used for the z comparison.  In order
     to physically clear the z-buffer, first call zfunction(ZF_ALWAYS), then
     draw a polygon whose z coordinates map to the desired z value.  To avoid
     updating the framebuffer, call wmpack(0) before drawing.  Restore the
     writemask and z function afterwards.

BUGS
     IRIS-4D G models always clear their z-buffers to GD_ZMAX, regardless of
     the value passed to czclear.