PK_ERROR_code_t PK_SURF_eval
(
--- received arguments ---
PK_SURF_t surf, --- surface
PK_UV_t uv, --- u and v parameter pair
int n_u_derivs, --- number of u derivatives
int n_v_derivs, --- number of v derivatives
PK_LOGICAL_t triangular, --- triangular derivative array required
--- returned arguments ---
PK_VECTOR_t p[] --- point and derivatives
)
This function evaluates a point and derivatives at a parameter pair on
the given surface.
Specific Errors:
PK_ERROR_bad_parameter cannot evaluate out of range
PK_ERROR_too_many_derivatives too many derivatives requested
PK_ERROR_num_derivs_not_equal where triangular format was requested
PK_ERROR_eval_failure internal evaluator failure
The function calculates the cartesian coordinates of the point at the
given parameter pair uv, and also the derivatives with respect to uv,
up to order n_u_derivs and n_v_derivs respectively. triangular controls
whether the returned array of derivatives is triangular or not.
It is not necessarily required that the supplied parameters lie inside the
ranges as given by PK_SURF_ask_params. If the surface is
PK_PARAM_periodic_yes_c or PK_PARAM_periodic_seamed_c in a parametric direction
then any value is acceptable for that parameter. If a parameter is outside
the range but the surface is PK_PARAM_bound_extendable_c in that parametric
direction, then the evaluation will be performed on the surface extension.
Where derivative discontinuities occur at patch boundaries, the derivatives
just after the discontinuity are returned.
There is a limit on the number of derivatives which may be requested.
In the case of foreign geometry surfaces (PK_CLASS_fsurf), the maximum
number of derivatives that can be returned by this function is determined
by the surface's external evaluator. The evaluator should, at least, be
able to calculate up to second order derivatives.
The following table shows the derivatives that can be requested for other
surface types.
u derivs
| 0 | 1 | 2 | >2 |
--------------------------------------
0 | A | A | B | D |
--------------------------------------
v derivs 1 | A | A | C | D |
--------------------------------------
2 | B | C | C | D |
--------------------------------------
>2 | D | D | D | D |
--------------------------------------
A - All surface types.
B - All surface types (blend surfaces will approximate derivatives).
C - All surface types (blend & offset surfaces will approximate derivatives).
D - B-Surfaces only.
The return argument p is a vector array returning the point and possibly
derivatives. This array is filled as follows:
p[0] is the point on the surface itself.
If derivatives are required and triangular is PK_LOGICAL_false then
a rectangular derivative matrix is returned. The derivatives are stored
as follows:
The i'th derivative ( i <= n_u_derivs ) with respect to u and
the j'th derivative ( j <= n_v_derivs ) with respect to v is
p[ i + ( n_u_derivs+1 ) * j ) ]
For example, if n_u_derivs is 2 and n_v_derivs is 3, then the array
contains 12 vectors:-
p(u,v) p(u,v) p(u,v)
u uu
then:-
p(u,v) p(u,v) p(u,v)
v uv uuv
then:-
p(u,v) p(u,v) p(u,v)
vv uvv uuvv
then:-
p(u,v) p(u,v) p(u,v)
vvv uvvv uuvvv
where
p(u,v) for example is the first derivative with respect to u
uvv and the second derivative with respect to v.
Alternatively, if triangular is PK_LOGICAL_true then a triangular derivative
matrix is returned. The derivatives are stored as follows:
The i'th derivative ( i <= n_u_derivs ) with respect to u and
the j'th derivative ( j <= n_v_derivs ) with respect to v is
p[ i + ( n_u_derivs+1 ) * j - 0.5 * j * ( j-1) ]
In this case it is an error if n_u_derivs and n_v_derivs are not
equal. This will only be detected when argument checking is turned on.
For example, if n_u_derivs is 2 and n_v_derivs is 2, then the array
contains 6 vectors:-
p(u,v) p(u,v) p(u,v)
u uu
then:-
p(u,v) p(u,v)
v uv
then:-
p(u,v)
vv
