PK_DEBUG_shuffle_start

PK_ERROR_code_t                   PK_DEBUG_shuffle_start
(
--- received arguments ---
const PK_DEBUG_shuffle_start_o_t *options --- options structure
)


Initialises and starts the shuffling of return array arguments for some
PK functions.


Specific Errors:
PK_ERROR_not_stopped    PK_DEBUG_shuffle_start already called since the last
                        call to PK_DEBUG_shuffle_stop (MILD).


When shuffling is started, the return array arguments of some PK functions
might have their contents in a different order. The new order will be solely
determined by the length of each array, i.e. arrays of the same length will
always be shuffled using the same permutation to maintain any correspondence
between them.

The option 'value' can be used to give a variety of different shuffle
behaviours.

This function can be called at any time.
See here for more information.

The applicable PK functions and their shuffled return arguments are:

- PK_BODY_ask_edges             'edges'
- PK_BODY_ask_faces             'faces'   (see note 1)
- PK_BODY_ask_regions           'regions' (see note 2)
- PK_BODY_emboss                'track_records'
- PK_BODY_extend                'track_records'
- PK_BODY_extrude               'track_records'
- PK_BODY_fix_blends            'blends', 'unders', 'topols'
- PK_BODY_hollow_2              'track_records'
- PK_BODY_imprint_curves_vector 'edges'
- PK_BODY_imprint_curves_normal 'edges'
- PK_BODY_imprint_cus_vec       'track_records'
- PK_BODY_imprint_cus_normal    'track_records'
- PK_BODY_imprint_faces         'edges'
- PK_BODY_imprint_plane         'edges'
- PK_BODY_offset_2              'track_records'
- PK_BODY_sweep                 'laterals', 'bases'
- PK_BODY_thicken_3             'track_records'
- PK_FACE_make_blend            'sheet_bodies', 'blend_topols', 'unders'
                                (see note 3)
- PK_GROUP_ask_entities         'entities'
- PK_SURF_ask_faces             'faces'

Note 1: This overrides the standard faces order for solids created using the
        primitive creation functions.
Note 2: The first region will always remain unshuffled and the rest of the
        regions shuffled as an array of size 'n_regions' - 1.
Note 3: If blend ribs are returned then 'sheet_bodies' will not be shuffled.