 |
PK_SURF_eval |
|
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 [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
)
This function evaluates a point and derivatives 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_too_many_derivatives too many derivatives requested (MILD)
PK_ERROR_num_derivs_not_equal where triangular format was requested
(MILD)
PK_ERROR_eval_failure internal evaluator failure (MILD)
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. For cases where it is not
permitted to evaluate outside the range, PK_ERROR_bad_parameter will be
returned.
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 mesh surfaces (PK_CLASS_mesh), no derivatives can be returned.
'n_u_derivs' and 'n_v_derivs' must be set to 0.
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, but it is still restricted to values smaller than
ten. 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 | 3-10 |
--------------------------------------
0 | A | A | B | D |
--------------------------------------
v derivs 1 | A | A | C | D |
--------------------------------------
2 | B | C | C | D |
--------------------------------------
3-10 | 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 - All surface types, excluding blend and offset surfaces.
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