PK_CURVE_eval

PK_ERROR_code_t PK_CURVE_eval
(
--- received arguments ---
PK_CURVE_t      curve,      --- curve
double          t,          --- curve parameter
int             n_derivs,   --- number of derivatives

--- returned arguments ---
PK_VECTOR_t     p[]         --- point and derivatives.
)


This function evaluates a point and derivatives at a given parameter on the
given curve.


Specific Errors:
    PK_ERROR_at_terminator            unable to calculate 2nd derivatives at
                                      a terminator of 'curve' (MILD)
    PK_ERROR_bad_parameter            not permitted to evaluate outside of
                                      range (MILD)
    PK_ERROR_too_many_derivatives     too many derivatives requested (MILD)
    PK_ERROR_eval_failure             internal evaluator failure (MILD)


The function calculates the Cartesian coordinates of the point at the given
curve parameter 't', and also the derivatives with respect to 't', up to
order 'n_derivs'.

In the array of returned data:

            p[0] is the point itself
            p[1] is the first derivative
            p[2] is the second derivative
            p[n] is the nth derivative

It is not necessarily required that 't' lies inside the range as given by
PK_CURVE_ask_param.  If the curve is PK_PARAM_periodic_yes_c or
PK_PARAM_periodic_seamed_c then any value is acceptable.  For cases where it is
not permitted to evaluate outside the range, PK_ERROR_bad_parameter will be
returned.

Where derivative discontinuities exist at a junction between segments, the
derivatives just after the discontinuity are returned, i.e. on the right.
An exception to this is where the curve is periodic, and 't' is at the top
of the periodic range, in which case evaluation is on the left (parameters
which are equal to the top of the range, plus a non-zero multiple of the
period, still evaluate from the right).

The maximum number of derivatives that can be computed depends on the class
of the given curve:

    curve type:               maximum number of derivatives
    -----------               -----------------------------
    line/circle/ellipse       10

    intersection curve        2

    foreign geometry          10

    SP-curve                  2

    B-curve                   10

PK_ERROR_too_many_derivatives can also be returned when 'n_derivs' is less than
the maximum, if the function could evaluate at least the position, but is
unable to evaluate all the requested derivatives due to internal evaluator
failure.