PEXOCCCones - Cone Primitive (5.2)


Synopsis

 
     void PEXOCCCones(
          PEXOCC context,
          double lower_radius,
          double upper_radius,
          int lower_cap,
          int upper_cap,
          unsigned int num_cones,
          PEXPointer cones
     )
 

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).

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

surface_vertex_attributes (OCC)
A mask indicating the vertex attributes provided (PEXGAColor, PEXGARadius, PEXGAFloatData).

surface_vertex_fp_data_count (OCC)
Number of floats provided for each vertex.

lower_radius
The radius of the lower end of the cone.

upper_radius
The radius of the upper end of the cone.

lower_cap
The flag to control the drawing of the lower cap of the cones (PEXOn or PEXOff).

upper_cap
The flag to control the drawing of the upper cap of the cones (PEXOn or PEXOff).

num_cones
The number of cones.

cones
A pointer to the cone vertex data. There are two vertices per cone. See the description below for details. 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 PEXOCCCones to create a cone primitive output command (PEXOCConeSetWithData).

A cone is defined as a three-dimensional surface with upper and lower edges defined by two circles. These circles are perpendicular to the axis which passes through their centers. The sides of the cone are defined by a segment of the shortest possible length connecting the two circles as it is swept around their circumferences. The center vertex and radius of each circle are defined in modeling coordinates.

You specify each cone with two vertices and pass the list of vertices in the argument cones. Therefore the number of vertices you specify must be twice the number of cones you indicate with num_cones. The lower vertex is the first vertex of the two that define each cone.

Use upper_cap and lower_cap to control the capping of the cones. If you set a cap flag to True, then the implementation treats the bounding circle as a fill area with interior style PEXInteriorStyleSolid. Otherwise, it treats the bounding circle as a fill area with interior style PEXInteriorStyleHollow. The cap flags apply to all the cones in the list.

Use surface_vertex_attributes to specify optional data for the two center vertices of each cone. The supported components of the bitmask are PEXGAColor, PEXGARadius and PEXGAFloatData. You must always include coordinate data (not 2D) in the vertex data.

If you set the PEXGAColor bit in the surface_vertex_attributes bitmask, then you supply a color with each center vertex. The colors are of the type specified by color_type. Otherwise, the implementation ignores color_type. The implementation applies to the cone the color associated with the center vertex of the lower circle. The implementation ignores the color associated with the center vertex of the upper circle.

If you set the PEXConeRadius bit in the surface_vertex_attributes bitmask, then you supply the radius for each end of the cone in each center vertex and the implementation ignores the lower_radius and upper_radius arguments. Otherwise the lower_radius and upper_radius arguments define the common radii applied to all cones in the set. If a radius is less than zero or both radii are equal to zero, then the results of rendering that cone are implementation-dependent.

If you set the PEXGAFloatData bit in the surface_vertex_attributes bitmask, then you supply extended data with each center vertex. The surface_fp_data_count indicates the number of floating-point values in the LISTofFLOAT for each vertex. If you do not set the PEXGAFloatData bit, then the implementation ignores surface_fp_data_count.

PEXlib clips PEXConeSetWithData similar to PEXFillArea3D (see Surfaces - General Attributes).

PEXlib does not supply a set of type definitions for cones due to the large number of combinations of vertex data possible when considering both the required and optional vertex data. Therefore, you may find it convenient to design your own data structure to pass in the cones parameter when using the PEXDataPacked data model. You need to design the data structure with the following ordering rules in mind:

The required order is:

  PEXCoord       center
  PEXColor*      one of the PEXlib color types, if provided
  float          radius
  float[n]       floating point data, if provided

As an example, if you wish to supply data for cones using coordinates, RGB floating-point colors, and a radius, you would create a structure like this:

 
typedef struct {
  PEXCoord         center;
  PEXColorRGB      rgb;
  float            radius;
} MY_PEXRGBConeVertex;

Remember to set the correct surface vertex attributes in the OCC. In this case you would make sure that the PEXGAColor flag is on and the PEXGARadius flag is on. You set the color_type field in the OCC to PEXColorTypeRGB. You need to supply two vertices per cone in your list.

If you are using the PEXDataStride data model, then you set the stride and offset members in the OC Context to reflect the way the data is stored in your structured array. Pass a pointer to the start of the structured array in the cones argument of the function call. Be sure that there is a valid offset for each vertex attribute that is present.

If you are using the PEXDataUnpacked data model, then you would set size members in the OCC to the appropriate values and point to each of the data lists with the PEXUnpackedVertexData data structure. Again, be careful to set a size and pointer for every attribute you indicate as present in the vertex attributes.

Errors

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: PEXOCCSpheres

There are no PEXlib 5.1 compatibility primitives similar to this one.

For attributes that affect this primitive, see

For an overview, see Output Command Functions.