PEXOCCArcs - Arc Primitive (5.2)


Synopsis

 
     void PEXOCCArcs(
          PEXOCC context,
          PEXArcType arc_type,
          unsigned int count,
          PEXPointer arcs
      )
 

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 data provided (PEXColorTypeIndexed, PEXColorTypeRGB, PEXColorTypeCIE, PEXColorTypeHSV, PEXColorTypeHLS, PEXColorTypeRGB8, PEXColorTypeRGB16, PEXColorTypeRGBA, PEXColorTypeRGBA8, or PEXColorTypeRGBA16).

line_vertex_attributes (OCC)
A mask indicating the vertex attributes provided (PEXGAColor, PEXGA2D, and PEXGAFloatData).

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

arc_type
The type of arc requested (PEXArcCircle, PEXArcCircularArc, PEXArcCircularClosedChordArc, PEXArcCircularClosedPieArc, PEXArcEllipse, PEXArcEllipticalArc, PEXArcEllipticalClosedChordArc or PEXArcEllipticalClosedPieArc).

count
The number of arcs.

arcs
A pointer to the arc data. See the description below for an explanation of this data. 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 PEXOCCArcs to create an arc-based line primitive output command (PEXOCArcSetWithData). The implementation applies the Line, Shaded Line, and Curve attribute sets, and line clipping to this primitive.

You can only define one type of arc per function call. PEXlib defines the following arc-based lines:

PEXArcCircle -
specifies a curve, which is everywhere equidistant from the center vertex in the z=0 plane. If your application defines a three-dimensional circle, then the implementation ignores the z values. If the radius of the circle is less than or equal to zero, then the circle degrades to a dot at the center vertex.

PEXArcCircularArc -
PEXArcCircularClosedChordArc -
PEXArcCircularClosedPieArc -
specifies a circular arc in the z=0 plane defined by the radius, a start angle (), and a stop angle () as follows:

where:

M = <radius, 0, 0>,
m = <0, radius, 0>

If

  | - | > 2, 
then
   =  + 2.

If

 
   < , 
then
 
   =  + 2

You leave the arc open by specifying the PEXArcCircularArc arc type or close it with a chordal segment (PEXArcCircularClosedChordArc) or by connecting each endpoint to the center vertex (PEXArcCircularClosedPieArc). If your application defines a three-dimensional circular closed arc, then the implementation ignores the z value. If the radius of the circular closed arc is less than or equal to zero, then the arc degrades to a dot at the center vertex.

PEXArcEllipse -
specifies a curve, defined by a center vertex and major and minor axes. The major and minor axes define a parallelogram that circumscribes the ellipse and is anchored at the center vertex of the ellipse. Two sides of the parallelogram are parallel to the major axis. The other two sides are parallel to the minor axis. The major and minor axes extend from the center of the ellipse to the midpoints of the sides of the parallelogram. The ellipse is tangent to the sides of the parallelogram at their midpoints. If the length of both of the axes is equal to zero, then the ellipse degrades to a dot at the center vertex. If the length of just one of the axes is equal to zero, then the ellipse degrades to a segment representing the other axis. In both of these cases, PEXlib applies edge attributes. If the axes have non-zero lengths and are parallel, then the ellipse degrades in an implementation-dependent way.

PEXArcEllipticalArc -
PEXArcEllipticalClosedChordArc -
PEXArcEllipticalClosedPieArc -
specifies an elliptical arc defined by a start angle (), and a stop angle () as follows:

If

   | - | > 2, 
then
   =  + 2.

If

   < , 
then
   =  + 2.

You leave the arc open by specifying the PEXArcEllipticalArc arc type or close it with a segment between the two endpoints (PEXArcEllipticalClosedChordArc) or connect each endpoint with a segment to the center vertex (PEXArcEllipticalClosedPieArc). If the length of both of the axes is equal to zero, then the arc degrades to a dot at the center vertex. If the length of just one of the axes is equal to zero or if the axes have non-zero lengths and are parallel, then the arc degrades in an implementation-dependent way.

This primitive only supports the optional vertex_attributes: PEXGAColor, PEXGAFloatData, and PEXGA2D.

Although there is no non-OCC form of this function, you may use the PEXDataPacked, PEXDataStride, or the PEXDataPacked data models to supply the arc data via the arcs parameter in modeling coordinates.

Each arc type has its own set of required vertex data, where each vertex is used to describe a complete arc.

Required Vertex Data for Arc Primitives

-----------------------------------------------------
Arc Type                        Required Vertex Data
-----------------------------------------------------
PEXArcCircle                    coord, radius
PEXArcCircularArc               coord, radius, angles
PEXArcCircularClosedChordArc    coord, radius, angles
PEXArcCircularClosedPieArc      coord, radius, angles
PEXArcEllipse                   coord, axes
PEXArcEllipticalArc             coord, axes, angles
PEXArcEllipticalClosedChordArc  coord, axes, angles
PEXArcEllipticalClosedPieArc    coord, axes, angles
 
-----------------------------------------------------

PEXlib ignores the PEXGARadius flag since the presence of a radius is implicit with the arc type.

PEXlib does not supply a set of type definitions for arc set vertex data 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 arcs parameter when using the PEXDataPacked data model. You need to design the data structure with the following ordering rules in mind:

For the four circular arc types, the required order is:

 
  PEXCoord        (or PEXCoord2D) center
  PEXColor*       one of the PEXlib color types, if provided
  float           radius
  float           start angle, if an arc
  float           end angle, if an arc
  float[n]        floating point data, if provided

For the four elliptical arc area types, the required order is:

 
  PEXCoord       (or PEXCoord2D) center
  PEXColor*      one of the PEXlib color types, if provided
  PEXCoord       (or PEXCoord2D) major axis
  PEXCoord       (or PEXCoord2D) minor axis
  float          start angle, if an arc
  float          end angle, if an arc
  float[n]       floating point data, if provided

As an example, if you wish to supply data for Closed Circular Arcs using 3D coordinates, RGB floating-point colors and three floating-point numbers (for texture data), you would create a structure like this:

 typedef struct {
   PEXCoord         center;
   PEXColorRGB      rgb;
   float            radius;
   float            start_angle;
   float            stop_angle;
   float            texture_data[3];
 } MY_PEXRGBCircularClosedArc;

Remember to set the correct line vertex attributes in the OCC. In this case you would make sure that the PEXGA2D flag is off, the PEXGAColor is on and the PEXGAFloatData flag is on. You set the color_type field in the OCC to PEXColorTypeRGB and the number of floats in the OCC to three.

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 arcs parameter 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

BadPEXOutputCommand
The specified arc type is invalid.

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: PEXOCCArcAreas.

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.