PK_BODY_pick_topols_r_t

struct PK_BODY_pick_topols_r_s
    {
    int                     n_faces;
    PK_BODY_pick_topol_r_t *faces;
    int                     e_faces;

    int                     n_edges;
    PK_BODY_pick_topol_r_t *edges;
    int                     e_edges;

    int                     n_vertices;
    PK_BODY_pick_topol_r_t *vertices;
    int                     e_vertices;
    };
typedef struct PK_BODY_pick_topols_r_s PK_BODY_pick_topols_r_t;



Structure returning picked entities

Used in:

PK_BODY_pick_topols
PK_BODY_pick_topols_r_f

Each picked entity is recorded in a PK_BODY_pick_topol_r_t structure.

The 'entity' field refers to a picked face, an edge or a vertex.

The 'occurence' field is a number in the range [0..n_bodies-1]. It identifies
an index into the owning body array and possibly an associated transformation.

If faces are being picked, the 'intersect' point is the exact intersection
between the ray and face. The 'distance' values of picked faces are set to
zero. If faces are picked within curve tolerance distance of their edge or
silhouette boundary, the function may fail to pick the correct face.

If edges are being picked, the 'intersect' field is a 'hit point' on the ray
at which the distance to the (transformed) edge occurrence was at a minimum.
The 'distance' field records the radial distance, measured from here to the
edge.

If vertices are being picked, the 'intersect' field is a 'hit point' on the
ray at which the distance to the (transformed) vertex occurrence was at a
minimum. The 'distance' field records the distance from here to the vertex.

The arrays of picked entity arrays are returned in a PK_BODY_pick_topols_r_t
structure. If no entities of a particular type were requested or if none were
picked by the ray, each array is returned empty; its PK_BODY_pick_topol_r_t
pointer set to NULL and its `e_<entities>' and `n_<entities>' counts set to
zero.

If more than 'max_<entity>' entities would be picked by the ray, details of the
closest 'max_<entities>' are returned in the array and the number of 'excess'
entities which also met the pick criteria recorded in the 'e_<entity>' count.
If 'ignore excess entities' has been requested then the 'e_<entity>' counts
will be set to zero.

The excess count hints to the application that the model is topologically
complex around the region of the ray or possibly that geometric selection
criteria set by the application are too lax.

The returned pick data must not be used to simulate "closest approach" or
"boolean" operations. This is because returned hit point and radial distance
measurements may only be computed to the accuracy of the supplied (or the
implied) curve tolerances, not to modelling accuracy.

The function PK_BODY_pick_topols_r_f may be used to free associated memory.