 |
PK_GEOM_transform_2 |
|
PK_ERROR_code_t PK_GEOM_transform_2
(
--- received arguments ---
int n_geoms, --- number of geometry entities
const PK_GEOM_t in_geoms[], --- geometric entities to be
--- transformed
PK_TRANSF_t transf, --- transformation
const PK_GEOM_transform_o_t *options, --- options structure [PF]
--- returned arguments ---
PK_GEOM_t out_geoms[], --- transformed geometric entities
PK_LOGICAL_t exact[] --- whether result is exact
)
This function transforms the array of given geometric entities by the given
transformation.
This function offers partial support for facet geometry [PF]
Specific Errors:
PK_ERROR_request_not_supported bad combination of geometry and transf
(MILD)
PK_ERROR_bad_component transformation matrix has perspective terms
(MILD)
PK_ERROR_is_attached geometric entity is attached to topology
(MILD)
PK_ERROR_bad_sharing sharing prevents transformation (MILD)
This function has two distinct modes of operation: transformations which modify
geometric entities and transformations that create new geometric entities. The
modify transformations will modify the geometric entities in the 'in_geoms'
array, whereas the new transformations will create new geometric entities in
the 'out_geoms' array.
Some restrictions upon the use of the function are specific to the mode of
operation. The transformation matrix must not contain perspective terms for
both modes of operation.
Modification transformations
The function will receive an array of geometric entities to be transformed. The
input geometric entities will be modified by the received transformation.
If the function has successfully completed, the input array will contain
the transformed geometric entities. The 'out_geoms' array will by default
contain a copy of the 'in_geoms' array. The 'exact' array will by default be
set to PK_LOGICAL_true for all of its fields.
The allowed transformations for this mode are translation, rotation, uniform
scale and reflection. Transforms that are not supported will return the error
PK_ERROR_request_not_supported. The geometry must also not be attached to any
topology, if this is the case the error PK_ERROR_is_attached will be returned.
All dependants of the geometry must be included in the array, if they are not
PK_ERROR_bad_sharing will be returned.
Creation transformations
The function returns two arrays, one of transformed geometric entities
'out_geoms', the other an array of PK_LOGICAL_ts, 'exact', which describes
whether each transformation was exact or not. They are both equal in length
to the 'in_geoms' array. The 'in_geoms' array will contain the geometric
entities to be transformed, and upon successful completion the 'out_geoms'
array will contain the transformed geometric entities.
If a piece of geometry in the array 'in_geoms' is a point or lattice then the
corresponding geometry in the output array 'out_geoms' is a point or lattice.
For curves and surfaces in the 'in_geoms' array, the corresponding geometry
in the 'out_geoms' array will satisfy the first possible of the following
list of criteria:
1 - be of the same class as the 'in_geoms' geometry,
2 - be exactly coincident with the transformation of the 'in_geoms' geometry,
3 - not deviate by more than the given tolerance from the transformation of
the 'in_geoms' geometry.
The fields of the array 'exact' are set to PK_LOGICAL_true if the
corresponding geometry in the 'out_geoms' array is either a point, a lattice,
or criterion 1 or 2 has been satisfied.
If the geometry in the 'out_geoms' array only satisfies criterion 3,
then 'exact' array is set to PK_LOGICAL_false for the corresponding field.
If 'in_geoms' has any geometric dependants not included in the array then new
geometric entities will be created as transformations of these.
If any geometry in the 'in_geoms' array is a cone or a lattice, then it is
not possible to transform it by a transformation involving non-uniform scale.
An attempt to do this will lead to the error PK_ERROR_request_not_supported.
Creation transformations are currently only supported for unit size arrays.