PEXSetOfFillAreaSets(3) — Subroutines

Name

PEXSetOfFillAreaSets - 3D Set of Fill Area Sets Primitive

Synopsis

void PEXSetOfFillAreaSets(Display ∗display, XID resource_id, PEXOCRequestType req_type, int shape_hint, unsigned int facet_attributes, unsigned int vertex_attributes, unsigned int edge_attributes, int contour_hint, int contours_all_one, int color_type, unsigned int set_count, PEXArrayOfFacetData facet_data, unsigned int vertex_count, PEXArrayOfVertex vertices, unsigned int index_count, PEXSwitch ∗edge_flags, PEXConnectivityData ∗connectivity)

Arguments

displayA pointer to a display structure returned by a successful XOpenDisplay call.

resource_idThe resource identifier of the renderer or structure.

req_typeThe request type for the output command (PEXOCRender, PEXOCStore, PEXOCRenderSingle or PEXOCStoreSingle).

shape_hintThe shape which describes all of the contours (PEXShapeComplex, PEXShapeNonConvex, PEXShapeConvex, PEXShapeUnknown).

facet_attributes
A mask indicating the facet attributes provided (PEXGANone, PEXGAColor, PEXGANormal).

vertex_attributes
A mask indicating the vertex attributes provided (PEXGANone, PEXGAColor, PEXGANormal).

edge_attributes
A mask indicating the edge attributes provided (PEXGANone or PEXGAEdges).

contour_hintA flag indicating whether contours are disjoint or overlapping (PEXContourDisjoint, PEXContourNested, PEXContourIntersecting, PEXContourUnknown).

contours_all_one
True if each fill area set contains only one contour; False otherwise.

color_typeThe type of color data provided (PEXColorTypeIndexed, PEXColorTypeRGB, PEXColorTypeCIE, PEXColorTypeHSV, PEXColorTypeHLS, PEXColorTypeRGB8, PEXColorTypeRGB16).

set_countThe number of fill area sets.

facet_dataAn array of facet data.

vertex_countThe number of vertices.

verticesAn array of vertices.

index_countThe number of vertex connectivity indices (also number of edge flags, if edges are specified).

edge_flagsAn array of edge flags.

connectivityA pointer to the list of contour connectivity data.

Returns

None

Description

This function creates a set of fill area sets output primitive.

A fill area may cross over itself to create a complex shape. The odd-even rule is used for determining the area that lies in the interior of the fill area. The shape hint is provided to enable performance improvements for certain shapes. Fill areas that are of higher complexity than indicated by the shape hint are rendered in an implementation-dependent manner. Consequently, applications should pass PEXShapeUnknown as the shape unless they are certain the fill area’s shape is one of the other three. Note that a fill area set with more than one contour is always allowed to have contours that intersect. If is quite possible that the only times rendering optimization can occur are when the number of contours in a fill area set is equal to one or if the "contours all one" flag is True, and the shape hint is PEXShapeConvex.

The contour hint provides further information about the relationships between contours in the fill area set. If the contour hint is PEXContourDisjoint, all contours will be spatially disjoint. No overlapping or intersection occurs between any contours in the fill area set. If the contour hint is PEXContourNested, contours will either be disjoint or wholly contained within another contour. No contour will have edges that intersect or are coincident with edges of any other contour. If the contour hint is PEXContourIntersecting, separated contours may have edges that are coincident or overlap. If the contour hint is PEXContourUnknown nothing is known about the interrelationships between contours. Fill area sets with contours that have higher complexity interrelationships than that indicated by the contour hint are rendered in an implementation-dependent manner.

The facet attributes indicate the content of the facet data. This data may be a color, a normal, or a color followed by a normal. Use the constants PEXGANone, PEXGAColor and PEXGANormal to construct a mask indicating the data provided. If specified, the facet color takes precedence over the surface color. If specified, the facet normal is used to determine whether the fill area is back-facing.

The vertex attributes indicate the content of each fill area vertex. In addition to the coordinate (x,y,z), applications may specify a color, a normal, or a color followed by a normal for each vertex. Use the constants PEXGANone, PEXGAColor and PEXGANormal to construct a mask indicating the data provided. If specified, vertex colors will override facet color or the current surface color. If specified, vertex normals are taken to be normals at the vertices of the fill area.

The reflection model and the surface interpolation will affect how the additional data is used in rendering the surface.

Color values passed must be of the specified color type. Normals are assumed to be unit length vectors. The effect if the normal is not unit length is implementation-dependent.

The edge attributes indicate the content of the edge flags. Use PEXGAEdges to indicate edge flags are provided or PEXGANone if no edge flags are provided. The edge flags, if present, are set to PEXOn or PEXOff and are used to indicate which edges should be rendered. The edge control for vertex i indicates whether or not to render the edge between vertex i and vertex i+1. Surface edges are always rendered with the surface edge color and are not affected by the facet or vertex colors.

The connectivity of the primitive is defined by the connectivity list. The connectivity list is a pointer to an array of PEXConnectivityData structures. Each entry in the array gives the contours for one fill area set in the set of fill area sets, and, in turn, contains a pointer to an array of PEXListOfUShort structures. Each of these latter structures gives the index of the vertices of one contour in that fill area set. The indices select a vertex in the array of vertices. Vertices are numbered with indices starting from zero (i.e. the first vertex is referenced as vertex 0). As a special case, if the "contours all one" flag is True then the contour count field in each fill area set is guaranteed to be one.

All attributes affecting the representation of fill area sets also affect the representation of this primitive.

Data Structures

typedef struct {
    unsigned short      count;
    PEXListOfUShort     ∗lists;
} PEXConnectivityData;
typedef struct {
    unsigned short      count;
    unsigned short      ∗shorts;
} PEXListOfUShort;
typedef unsigned char   PEXSwitch;
See also the PEXStructuresman page.

Errors

BadPEXOutputCommand
The output command contains an invalid value.

BadPEXRenderer
The specified renderer resource identifier is invalid.

BadPEXStructure
The specified structure resource identifier is invalid.

Museum