PK_TOPOL_render_facet

PK_ERROR_code_t                  PK_TOPOL_render_facet
(
--- received arguments ---
const int                        n_topols,        --- number of entities
const PK_TOPOL_t                 topols[],        --- entities to be facetted
const PK_TRANSF_t                topol_transfs[], --- applied transformations
const PK_TRANSF_t                view_transf,     --- viewing transformation
const PK_TOPOL_render_facet_o_t *options          --- options structure [PF]
)


Generate a facetted representation of topological entities through GO.

This function offers partial support for topology that has facet geometry
(meshes & plines) [PF]


Specific Errors:
    PK_ERROR_duplicate_array_item   topol has duplicates but no transf array
                                    (MILD)
    PK_ERROR_bad_component          topol or view transf is inappropriate
                                    (MILD)
    PK_ERROR_field_of_wrong_type    PK_facet_match_topol_c requires cull_none_c
                                    (MILD)
    PK_ERROR_unsuitable_topology    entity in topols array is not face or body
                                    (MILD)
    PK_ERROR_bad_combination        'consistent_parms' set to
                                    PK_facet_consistent_parms_fa_c and 'degen'
                                    set to PK_facet_degen_single_vx_c (MILD)
    PK_ERROR_function_not_exclusive 'incremental_facetting' option value is
                                    incompatible with the function running
                                    concurrently in a thread without locked
                                    partitions (MILD)


See here for more information.

Each received topological entity can be a general, solid or a sheet body or
face, if any other type of topological entity appears in 'topols' the error
PK_ERROR_unsuitable_topology will be returned.

Note that general bodies with facet geometry are not supported.

If 'topol_transfs' is set to NULL the 'topols' entities are not transformed
(and the 'topols' array cannot contain duplicates).

If 'topol_transfs' is not NULL, it is an array of TRANSFs of length 'n_topols'.
The 'topols' array can contain duplicates in this case. Each entity in 'topols'
is transformed by its corresponding entity in 'topol_transfs'.
Any entry in the 'topol_transfs' array can be PK_ENTITY_null, indicating that
the corresponding entity in 'topols' is not to be transformed.
Transforms may only contain translation, rotation and reflection components;
scales, shears and perspective are not allowed.

The 'view_transf' argument is only used when generating view-dependent facet
data for the back face culling and the increased local silhouette density
options.  The 'view_transf' may contain perspective components but the
perspective will only be taken into account for back face culling; for
increased local silhouette density only the directional component of the
'view_transf' will be used.

Facet vertex coordinates are always output through GO as world coordinates
even when a viewing transform entity is provided (data must be transformed
into the viewing coordinate system before display).

The PK_TOPOL_facet_o_t options structure defines two sets of controls

    1) how the facet mesh is generated
    2) which additional GO data are output

The mesh generation options include parameters such as the maximum number
of sides per facet and the tolerance values which are to be used when
approximating surfaces by planar facets.

By default, only the facet coordinate data are output through GO.
The additional GO data options denote whether the function should
calculate and output the following data through GO :

    - face normals
    - surface parameters
    - first and second order derivatives of the surface parameterisation
    - principal directions and curvatures of the face
    - owner edge identifiers

and whether it should output facets individually or in facet strip form.

If derivatives are requested, the cross product dPdu X dPdv points in the
same direction as the surface normal. This is true except in the case where
a transform is supplied for which PK_TRANSF_classify on the transform returns
a matrix_type of PK_matrix_type_reflection_c. In this case, each dPdu X dPdv
points in the opposite direction to the corresponding surface normal.

The following restrictions apply when generating facet data:

    - if topology edge matching is on, the 'cull' option must not be used

    - the 'view_transf' matrix may not contain reflections, scales or shear
      components.

    - the silhouette density option PK_facet_density_use_view_c only uses the
      directional component of the viewing transform entity (and it assumes a
      parallel view).  If multiple view_directions are supplied via the option
      'view_directions', these directions will override the 'view_transf'.

    - if incremental facetting is on then only geometry or topology matching is
      allowed.

    - if the function is running concurrently in a thread without locked
      partitions then incremental facetting must be off.

    - if 'consistent_parms' is set to PK_facet_consistent_parms_fa_c then the
      'degen' option cannot be set to PK_facet_degen_single_vx_c.