PEXOCCFillArea - Fill Area Primitive (5.0)


Synopsis

 
     void PEXOCCFillArea(
          PEXOCC context,
          PEXPointer facet_data,
          unsigned int count,
          PEXPointer vertices
)
 

Arguments

context
An OC context returned by a successful PEXCreateOCC call.

display (OCC)
A pointer to a display structure returned by a successful XOpenDisplay call.

resource_id (OCC)
The resource identifier of the renderer or structure.

req_type (OCC)
The request type for the output command (PEXOCRender, PEXOCStore, PEXOCRenderSingle or PEXOCStoreSingle).

shape_hint (OCC)
The shape of the fill area (PEXShapeComplex, PEXShapeNonConvex, PEXShapeConvex or PEXShapeUnknown).

ignore_edges (OCC)
A flag that determines if surface edges are rendered (True or False).

facet_attributes (OCC)
A mask indicating the facet attributes provided (PEXGANone(5.0), PEXGAColor(5.0), PEXGANormal(5.0), or PEXGAFloatData(5.2)).

surface_vertex_attributes (OCC)
A mask indicating the vertex attributes provided (PEXGANone(5.0), PEXGAColor(5.0), PEXGANormal(5.0), PEXGAEdges(5.0), PEXGA2D(5.2), PEXGAFloatData(5.2)).

color_type (OCC)
The type of color data provided (PEXColorTypeIndexed, PEXColorTypeRGB, PEXColorTypeCIE, PEXColorTypeHSV, PEXColorTypeHLS, PEXColorTypeRGB8, PEXColorTypeRGB16, PEXColorTypeRGBA, PEXColorTypeRGBA8, or PEXColorTypeRGBA16).

facet_fp_data_count (OCC)
The number of optional floating-point numbers for each facet.

surface_vertex_fp_data_count (OCC)
The number of optional floating-point numbers for each vertex.

facet_data
A pointer to facet data. See Facet / Vertex Data Formats.

count
The number of vertices.

vertices
A pointer to the vertex data defining the fill area. See Facet / Vertex Data Formats.

data_model (OCC)
Specifies the data model used to represent the geometric data.

data_model_specs (OCC)
Offset and size data for the PEXDataStride or PEXDataUnpacked data models.

Returns

None.

Description

Invoke PEXOCCFillArea to create a fill area primitive output command. This function encompasses all the functionality contained in the PEXFillArea, PEXFillArea2D, and PEXFillAreaWithData functions. Depending on the attributes you supply, this function generates a PEXOCFillArea, PEXOCFillArea2D, or PEXOCFillAreaWithData output command. If a PEXOCFillAreaSetWithDataFP OC is needed and the display is a connection to a 5.1 server or the Alternate Protocol Level is 5.1, this function generates a PEXOCFillAreaSetWithData output command instead of a PEXOCFillAreaSetWithDataFP output command.

A fill area is a list of vertices joined together to form a planar surface. The implementation does not require fill areas to be strictly planar, but shading artifacts may occur if a fill area is not planar or nearly so. The first vertex of the fill area is connected to the second, the second to the third, and so on. The implementation implicitly connects the last vertex to the first.

During the rendering process, the implementation transforms the fill area vertices to positions in device coordinates.

Reflectance calculations affect the surface colors. These calculations use the light state, interior style, and reflection model attributes. Depth-cueing computations affect surface colors and map the surface colors to device colors. The implementation does not display fill areas outside of the currently defined clipping volume. The implementation clips fill areas crossing the clipping volume, and displays only the portions inside the clipping volume.

Defining a fill area with fewer than three vertices creates a degenerate area. The implementation stores the fill area in a structure, but when the area is rendered, there is no visual effect. The implementation ignores the primitive.

A fill area may cross over itself to create a complex shape. The implementation uses the even-odd rule to determine the area that lies in the interior of the fill area. Specifying the shape_hint argument improves performance for certain shapes. The implementation renders fill areas that are of higher complexity than indicated by shape_hint in an implementation-dependent way. Consequently, your applications should pass PEXShapeUnknown as the shape unless you are certain the fill area's shape is one of the other three.

Specify the ignore_edges argument as a boolean value indicating whether surface edges are rendered. This argument value applies to each of the fill areas in the set. If True, the implementation draws no edges for the fill area set, even if edge data is supplied and/or the pipeline state's surface edge flag is on. If False, the implementation draws edges only if the pipeline state's surface edge flag is on. If you set PEXGAEdges in the vertex attributes, you supply a surface edge flag for each vertex by setting the edge field of the vertex data to either PEXOn or PEXOff. For the ith vertex, the edge flag indicates whether to draw the edge between the ith and i+1th vertex. If you do not supply edge data by not setting the PEXGAEdges vertex attribute, then the implementation draws all edges of the fill area sets.

Depending on the setting of the surface edge source flag values, this primitive obtains the attributes: surface edges, surface edge color, surface edge type, and surface edge width either directly from the current surface edge attribute values or from the edge bundle lookup table entry specified by the current edge bundle index attribute.

Depending on the setting of the surface attribute source flag values, this primitive obtains the attributes: surface color, interior style, interior style index, surface interpolation method, and reflection model either directly from the current surface attributes values or from the interior bundle lookup table entry specified by the current interior bundle index attribute.

If a surface is front-facing with respect to the point of view and the current culling mode enables front-faces to be rendered, then the implementation uses the surface color and reflection attributes when rendering the surface. If the surface is back-facing, and the current facet distinguish mode is True, and the current culling mode enables back-facing surfaces to be rendered, then the implementation uses the corresponding back-facing attributes instead.

Regardless of the fill area orientation, if the interior style is PEXInteriorStylePattern, then the primitive uses the pattern size, pattern reference point and pattern reference vectors to pattern the fill area.

Specify facet_attributes to 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. If specified, facet colors override the current surface color.

Specify surface_vertex_attributes to indicate the content of each fill area vertex. In addition to the coordinate (x,y,z), your application may specify a color, a normal, 2D coords, or optional floating-point data for each vertex. Use the constants PEXGANone, PEXGAColor, PEXGANormal, PEXGAEdges, PEXGA2D, and PEXGAFloatData to construct a mask indicating the data provided. If specified, vertex colors 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 affect how the implementation uses additional data in rendering the surface.

Normals are assumed to be unit length vectors. If you specify a normal that is not unit length, then the result is implementation-dependent.

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.

See Also

For primitives similar to this one, see:

For PEXlib 5.1 compatibility primitives similar to this one see:

For attributes that affect this primitive, see

For an overview, see Output Command Functions.