PK_SURF_eval_with_normal

PK_ERROR_code_t    PK_SURF_eval_with_normal
(
--- received arguments ---
PK_SURF_t          surf,        --- surf
PK_UV_t            uv,          --- surf u and v parameter pair
int                n_u_derivs,  --- number of u derivatives [NF]
int                n_v_derivs,  --- number of v derivatives [NF]
PK_LOGICAL_t       triangular,  --- triangular derivative array required

--- returned arguments ---
PK_VECTOR_t        p[],     --- point and derivatives
PK_VECTOR_t *const normal   --- surface normal
)


This function evaluates a point, derivatives and normal at a parameter pair
on the given surface.

This function offers partial support for facet geometry [PF]


Specific Errors:
    PK_ERROR_bad_parameter            not permitted to evaluate outside of
                                      range (MILD)
    PK_ERROR_at_singularity           failed to evaluate normal at singularity
                                      (MILD)
    PK_ERROR_too_many_derivatives     too many derivatives requested (MILD)
    PK_ERROR_num_derivs_not_equal     where triangular format requested (MILD)
    PK_ERROR_eval_failure             internal evaluator failure (MILD)


This function provides an extension to the functionality of PK_SURF_eval;
all the documentation for that function also applies here.

The normalised surface normal at 'uv' is also calculated. This normal will be
parallel to the cross product of the the derivative with respect to u and the
derivative with respect to v (unless this cross-product is zero).

A value may be returned for 'normal' even at a singular point of the surface.
Note that a singular point may have an ambiguous parameterisation, and
different 'uv' pairs at the same point may give different normals.

For meshes, there are no derivatives and 'n_u_derivs' and 'n_v_derivs' must
be set to zero. PK_SURF_eval_with_normal returns a unique normal at the
position corresponding to 'uv' by averaging the normals of the relevant
neighbouring mvertices (as returned by PK_MVERTEX_ask_normals).