PK_BODY_pick_topols

PK_ERROR_code_t                 PK_BODY_pick_topols
(
--- received arguments ---
const int                       n_bodies,       --- number of bodies
const PK_PART_t                 bodies[],       --- body array
const PK_TRANSF_t              *body_transfs,   --- transformations
const PK_AXIS1_sf_t            *ray,            --- picking ray
const PK_BODY_pick_topols_o_t  *options,        --- control options

--- returned arguments ---
PK_BODY_pick_topols_r_t  *const picked          --- picked entities
)


Pick entities from an array of body instances by their proximity to a line


Specific Errors:

    PK_ERROR_null_direction         (MILD) near and far points are identical
    PK_ERROR_wrong_direction        (MILD) near and far points are reversed
    PK_ERROR_bad_combination        (MILD) bad combination of options
    PK_ERROR_bad_component          (MILD) 'body_transfs' contains a transform
                                    with non-uniform scaling, shearing
                                    or perspective terms
    PK_ERROR_duplicate_array_item   (MILD) body array contains duplicate bodies
                                    but 'body_transfs' is null



Overview
This function picks faces, edges and vertices from an array of instanced bodies
using a straight line ray. Faces are picked if they are intersected by the ray.
Edges & vertices are picked if they lie within a specified distance of the ray.


Body Instances
If the 'body_transfs' argument is NULL, the ray is compared directly with
each of the 'n_bodies' bodies. The bodies array must not contain duplicates.

If the 'body_transfs' argument is not NULL, it refers to an array of 'n_bodies'
PK_TRANSF_t entities. The ray is compared with the 'n_bodies' bodies, with each
transformed by the corresponding entry in 'body_transfs'. The bodies array may
contain duplicates. Instancing transforms may contain translation, reflection,
rotation and uniform scaling, but not non-uniform scaling, shearing or
perspective terms. If an instance does not need to be transformed, its
'body_transfs' entry can be set to PK_ENTITY_null.


Options
The options structure defines which types of entity are picked, the maximum
distance allowed between an entity and the ray, controls on approximating
edge curves by polylines and the method by which picked edges and vertices
are sorted. It allows the picking ray to be constrained by near/far planes.