 |
PK_SURF_find_vectors_o_t |
|
struct PK_SURF_find_vectors_o_s
{
int o_t_version; --- option structure version
int n_measurements; --- number of measurements
--- (1)
double *measurements; --- values of the measurements
--- (0.5)
PK_measure_t measurement_method; --- what 'measurements' measure
--- (PK_measure_chord_ratio_c)
PK_SURF_curve_t curve_type; --- type of curve on surface
--- (PK_SURF_curve_vec_proj_c)
--- [PF]
PK_LOGICAL_t have_help_point; --- whether a 'help_point' has
--- been supplied
--- (PK_LOGICAL_false)
PK_VECTOR_t help_point; --- help position vector
PK_LOGICAL_t have_proj_direction; --- whether a 'proj_direction'
--- has been supplied
--- (PK_LOGICAL_false)
PK_VECTOR1_t proj_direction; --- projection direction vector
PK_ERROR_on_fail_t error_on_failure; --- when to return an error
--- indicating failure
--- (PK_ERROR_on_fail_no_c)
};
typedef struct PK_SURF_find_vectors_o_s PK_SURF_find_vectors_o_t;
This structure holds controls for PK_SURF_find_vectors.
Used in:
PK_SURF_find_vectors
The option structure allows the caller to control how the position vectors
on the surface are determined.
Notation: The "path curve" is a bounded curve, lying on the supplied 'surface',
on which all the returned vectors lie.
The "start point" of the path curve is the position vector
corresponding to evaluating the surface at 'uv_start'.
The "end point" of the path curve is the position vector
corresponding to evaluating the curve at 'uv_end'.
The "bounded length" of the path curve is the length of the curve
measured along the curve from the start point to the end point.
n_measurements:
---------------
The number of values supplied in 'measurements'.
measurements:
-------------
The values supplied are either distances or ratios of distances measured in
3-space. If they are distance measurements, they may neither be negative nor
exceed the bounded length of the path curve. If they are ratios, they may
neither be negative nor greater than 1.
measurement_method:
-------------------
This enum determines what the values in 'measurements' represent. The allowed
options are:
PK_measure_distance_c
PK_measure_distance_ratio_c
PK_measure_chord_c
PK_measure_chord_ratio_c
PK_measure_2_chords_ratio_c
See the documentation of PK_CURVE_find_vectors_o_t for detailed information.
In general, the computational cost of the methods involving chord measurements
is lower than the methods involving true curve lengths or ratios of such.
curve_type:
-----------
This argument of type PK_SURF_curve_t determines the method used to define the
path curve. See the documentation of PK_SURF_curve_t for the existing options.
Facet geometry is not supported when 'curve_type' is PK_SURF_curve_linear_sp_c.
If 'curve_type' is set equal to PK_SURF_curve_vec_proj_c, the path curve is
the projected image of the chord between 'uv_start' and 'uv_end'. If
'have_proj_direction' is set to PK_LOGICAL_false, the chord is projected using
a plane characterised by the chord direction and the surface normals at
'uv_start' and 'uv_end'(see #here#DOC0000# for more information).
Otherwise, if 'have_proj_direction' is set to PK_LOGICAL_true, the chord
between 'uv_start' and 'uv_end' is projected in the supplied 'proj_direction'.
help_point:
-----------
This option is only available if 'curve_type' is set to
PK_SURF_curve_linear_sp_c. If the application intends to supply a
'help_point', the option 'have_help_point' must be set to PK_LOGICAL_true.
In some cases (e.g. periodic surfaces), ambiguity may exist on the
definition of the path curve. The application should then provide a
'help_point' via the option structure, and the function will use the nearest
path curve to the 'help_point'. Otherwise, the path curve will be the curve
segment with shortest bounded length.
proj_direction:
---------------
This option is only available if 'curve_type' is set to
PK_SURF_curve_vec_proj_c. If the application intends to supply a
'proj_direction', the option 'have_proj_direction' must be set to
PK_LOGICAL_true.
error_on_failure:
-----------------
This enum determines when the error PK_ERROR_cant_get_vectors will be
returned. It can be set to:
PK_ERROR_on_fail_any_c
The error PK_ERROR_cant_get_vectors will be returned unless the
operation is successful for all values in 'measurements'.
PK_ERROR_on_fail_all_c
The error PK_ERROR_cant_get_vectors will be returned if the
operation is successful for none of the values in 'measurements'.
PK_ERROR_on_fail_no_c
The error PK_ERROR_cant_get_vectors will not be returned.