NAME

xgl_gcache_polygon − builds a Gcache of a general polygon

SYNOPSIS

#include <xgl/xgl.h>

voidxgl_gcache_polygon (
Xgl_gcachegcache,
Xgl_ctxctx,
Xgl_facet_typefacet_type,
Xgl_facet∗facet,
Xgl_bbox∗bbox,
Xgl_usgn32num_pt_lists,
Xgl_pt_listpl[] );

DESCRIPTION

This operator caches a polygon in the Gcache gcache.  If Model Clipping is enabled (that is, if XGL_3D_CTX_MODEL_CLIP_PLANE_NUM is greater than zero), the polygon is clipped against the model clipping planes, and the result is stored in the Gcache. 

This Gcache can contain only 3D data, so the Context ctx must be a 3D Context.  If the attribute XGL_GCACHE_USE_APPL_GEOM is TRUE and Model Clipping is not enabled, the Gcache does not copy the geometry.  Instead, the Gcache keeps a pointer to it.  It is the application’s responsibility to ensure that the geometry passed as parameters to this function not be released to the system (freed) before xgl_­context_­display_­gcache(3) is called. 

A Gcache can also decompose a polygon into a set of triangles.  The triangles are stored in model coordinates (MC), so the decomposed polygon can be treated by the same transformations as the original polygon.  The attribute XGL_­GCACHE_­DO_­POLYGON_­DECOMP(3) controls whether decomposition is done.  Decomposition is useful when using hardware graphics accelerators that specialize in triangles.  Such an accelerator can draw the set of triangles in the decomposition faster than it can draw the polygon.  However, the decomposition process can be time-consuming; it varies with the complexity of the polygon and the number of vertices that it contains. 

The Gcache has two decomposition algorithms, one for complex polygons and one for non−self-intersecting (NSI) polygons.  An NSI polygon can have any number of bounds, but the bounds cannot cross each other.  A complex polygon does not have this restriction.  An NSI polygon can be decomposed more quickly than a complex polygon.  The Gcache uses the attribute XGL_­GCACHE_­POLYGON_­TYPE to determine which decomposition algorithm to use. 

Decomposition has a few limitations:

•The original polygon vertices are stored in the Gcache or referenced by it (if XGL_­GCACHE_­USE_­APPL_­GEOM is TRUE) even when the polygon is decomposed. 

•The original polygon is used to draw the edges for the polygon or when the fill style is HOLLOW. 

•Only polygons with floating point vertices can be decomposed. 

The following attribute values are saved in the Gcache for later validation:

XGL_3D_CTX_MODEL_CLIP_PLANE_NUM,
XGL_3D_CTX_MODEL_CLIP_PLANES,      /∗ if MODEL_CLIP_PLANE_NUM > 0 ∗/

The Gcache contains the polygon in model coordinates (MC).  Therefore, the display of the Gcache is affected by the full transformation and clipping pipeline. 

RETURN VALUE

Nothing is returned. 

SEE ALSO

xgl_­object_­create(3)
xgl_­context_­display_­gcache(3)
xgl_­polygon(3)

XGL_­GCACHE_­DO_­POLYGON_­DECOMP(3)
XGL_­GCACHE_­POLYGON_­TYPE(3)
XGL_­GCACHE_­USE_­APPL_­GEOM(3)

NOTES

All pts in the point list pl[] must have the same Xgl_pt_type. 

XGL Graphics Library  —  Last change: August 1994