PK_ERROR_code_t PK_EDGE_set_blend_variable
(
--- received arguments ---
PK_EDGE_t edge, --- edge to have
--- blend set
PK_blend_edge_shape_t edge_shape, --- shape of blend
const PK_EDGE_set_blend_variable_o_t *options, --- options structure
--- returned arguments ---
int *const n_blend_edges, --- number of edges with
--- blends set
PK_EDGE_t **const blend_edges --- edges with blends
--- set
)
This function sets edges to have a variable radius blend.
Specific Errors:
PK_ERROR_bad_blend_param illegal combination of blend properties
PK_ERROR_general_body edges are from a general body
Attaches a variable radius blend with the given parameters to an edge. Any
existing attribute is replaced by one with the given parameters.
edge_shape is a structure defining the shape of the blend, as follows:
n_ranges if this is greater than 1 then a variable radius blend
is produced, otherwise PK_ERROR_bad_blend_param is returned.
ranges_1 is an array of length n_ranges, consisting of values
specifying the range of the blend off the left face at the
corresponding position.
ranges_2 is an array of length n_ranges, consisting of values
specifying the range of blend off the right face at the
corresponding position.
rhos is an array of length n_ranges, consisting of values
specifying the rho value at the corresponding position.
positions is an array of length n_ranges, consisting of position
vectors of the data points on the edge at which the blend
ranges and rho values are defined.
All ranges must be greater than twice the maximum tolerance of the edge
and its associated vertices.
option structure
------ ---------
The option structure allows the caller to control which blend properties are
set.
The option structure allows the following to be set:
properties
properties of blend contained in a PK_blend_properties_t structure.
The fields appropriate to this type of blend are detailed below:
tolerance
Sets the tolerance for the blended edge. The default tolerance is
1000 * modeller resolution.
vary
Causes the blend ranges to vary naturally. The default behaviour
is for the range variation to be constrained in such a way
as to ensure that they would meet other blends smoothly at
the vertices. (PK_blend_vary_smooth_c)
propagate
Blend will be propagated over tangent edges, or past other
unfixed blends if the resultant combination of blends at a
vertex would be invalid, and blending the third edge results
in a valid combination. The propagation will consist of exact
rolling ball blends.
The default behaviour is no propagation.
Note that if a blend does propagate, and you wish to remove
the resulting blend attributes, PK_EDGE_remove_blend
will need to be passed the edges propagated on to
as well as that of the original edge.
Overflow: The default overflow behaviour of a blend is as follows;
When fixing a blend, it is possible that the blend as defined by
its basic parameters would lie outside the faces adjacent
to the edge being blended. If this is so, the blend must 'overflow'.
ov_smooth
If the configuration allows us, we `smoothly overflow' and
create a blend one of whose underlying faces is the
one it has overflowed onto.
ov_cliff
If the configuration is unsuitable for smooth overflow,
we try to `cliff overflow' - that is replace the
appropriate section of the blend by a cliffedge blend
running along the appropriate edges.
ov_cliff_end
If the configuration is unsuitable for cliff overflow,
we try to `cliff and overflow' - that is replace the
appropriate section of the blend by a cliffedge blend
at the ends of the appropriate edges.
ov_notch
If the configuration is unsuitable for cliff overflow too,
we will then `notch overflow' - that is, merely trim the blend
by the other faces in the region, leaving its surface geometry
unchanged. If the configuration is unsuitable
for this as well, the blend will not fix.
By default neither cliffedge or smooth overflows will occur when
the edge being overflowed is of the same convexity as the
edge being blended.
By default also, cliffedge overflows will not occur
at the ends of blends, except where they meet another blend smoothly.
Overflow Type | Prevent
--------------------------------------------
SMOOTH | PK_blend_ov_smooth_no_c
CLIFFEDGE | PK_blend_ov_cliff_no_c
NOTCH | PK_blend_ov_notch_no_c
--------------------------------------------
Overflow Type | Allow when Same Convexity
--------------------------------------------
SMOOTH | PK_blend_ov_smooth_any_c
CLIFFEDGE | PK_blend_ov_cliff_any_c
--------------------------------------------
Overflow Type | Allow at End
--------------------------------------------
CLIFFEDGE END | PK_blend_ov_cliff_end_yes_c
--------------------------------------------
Overflow Type | Default
--------------------------------------------
SMOOTH | PK_blend_ov_smooth_diff_c
CLIFFEDGE | PK_blend_ov_cliff_diff_c
CLIFFEDGE END | PK_blend_ov_cliff_end_no_c
NOTCH | PK_blend_ov_notch_yes_c
--------------------------------------------
render_ribs
Whether ribs will be drawn by the rendering functions.
ribspace
The approximate separation of rib lines.
( 0 < ribspace < size )
draw_fix
When draw_fix is PK_LOGICAL_true, the created unfixed blends are
fixed, checked and rendered when required.
Setting draw_fix to PK_LOGICAL_false causes the unfixed blends
to be ignored by PK_BODY_fix_blends, PK_EDGE_check_blends and
PK_TOPOL_render_line, which will all treat the edges as unblended.
For further explanation, and examples, of the use of these tokens,
please refer to the blending section of the manual.
A successful result will produce a new blend attribute. It will return
the edge(s) to which the blend attribute is attached in the array
blend_edges.
See PK_BODY_fix_blends for making the blends a part of the topology.
This function is not supported for edges on general bodies.
