Functions | |
StatusInt | mdlCurrTrans_begin () |
Creates a new entry on the Current Transformation stack. More... | |
int | mdlCurrTrans_clear () |
Pops all pushed transformation matrices from the Current Transform stack. More... | |
StatusInt | mdlCurrTrans_end () |
Removes the top-of-stack transformation from the Current Transform stack. More... | |
int | mdlCurrTrans_getCount () |
Gets the number of pushed transformation matrices on the Current Transform stack. More... | |
StatusInt | mdlCurrTrans_getAddresses (TransformP *fwd, TransformP *inv) |
Returns the address of the current forward transform in *fwd and the address of the current inverse transform in *inv. More... | |
StatusInt | mdlCurrTrans_getTransforms (TransformP pMdlToUor, TransformP pUorToMdl) |
Return the current transforms. More... | |
void | mdlCurrTrans_getTransformToMDL (TransformP pCallerToMDL, TransformCP pCallerToUOR) |
Combine a "caller to uors" transform with the currtrans "uor to mdl" transform. More... | |
StatusInt | mdlCurrTrans_identity () |
Replaces the current transformation matrix with the identity matrix. More... | |
void | mdlCurrTrans_invScaleDoubleArray (double *out, const double *in, int numValues) |
Scales an array of numValues values pointed to by <code>in</code> from the current coordinate system into design file coordinates. More... | |
void | mdlCurrTrans_invtransPointArray (Dpoint3d *out, const Dpoint3d *in, int numPoints) |
Transforms an array of numPoints points, pointed to by <code>in</code>, from design file coordinates into the current coordinate system. More... | |
void | mdlCurrTrans_invtransRMatrix (RotMatrixP out, RotMatrixCP in) |
Transforms a rotation matrix pointed to by | |
int | mdlCurrTrans_masterUnitsIdentityForModel (int translateToGlobalOrigin, DgnModelRefP modelRef) |
Sets the scales of the current transformation matrix to the number of UORs per master unit as indicated by the specified model. More... | |
int | mdlCurrTrans_subUnitsIdentityForModel (int translateToGlobalOrigin, DgnModelRefP modelRef) |
Sets the scales of the current transformation matrix to the number of UORs per sub unit as indicated by the specified model. More... | |
StatusInt | mdlCurrTrans_masterUnitsIdentity (int translateToGlobalOrigin) |
Identical to mdlCurrTrans_identity, except that it sets the scales of the transformation matrix to the number of UORs per master unit. More... | |
StatusInt | mdlCurrTrans_subUnitsIdentity (int translateToGlobalOrigin) |
Sets the scales of the transformation matrix to the number of UORs per sub unit. More... | |
StatusInt | mdlCurrTrans_rotateByAngles (double xangle, double yangle, double zangle) |
Rotates the current transformation about its origin by the angles specified in | |
StatusInt | mdlCurrTrans_rotateByRMatrix (RotMatrixP rotMatrix, int reverse) |
Rotates the current transformation about its origin by the rotation matrix pointed to by rotMatrix. More... | |
StatusInt | mdlCurrTrans_rotateByView (int viewNumber) |
Rotates the current transformation about its origin by the rotation matrix of view viewNumber. More... | |
StatusInt | mdlCurrTrans_scale (double xscale, double yscale, double zscale) |
Scales the current transformation matrix by the scale factors xScale, yScale, and zScale. More... | |
void | mdlCurrTrans_scaleDoubleArray (double *out, const double *in, int numValues) |
Scales an array of numValues double precision values pointed to by in from the current coordinate system into design file coordinates. More... | |
void | mdlCurrTrans_transformPointArray (Dpoint3d *out, const Dpoint3d *in, int numPoints) |
Transforms an array of numPoints points, pointed to by in, from the current coordinate system into design file coordinates. More... | |
void | mdlCurrTrans_transformRMatrix (RotMatrixP out, RotMatrixCP in) |
Transforms a rotation matrix pointed to by in from the current coordinate system into design file coordinates. More... | |
int | mdlCurrTrans_translateOrigin (Dpoint3d *delta) |
Translates the origin of the current transformation matrix by the distance specified by *delta. More... | |
int | mdlCurrTrans_translateOriginWorld (Dpoint3d *delta) |
Translates the origin of the current transformation matrix by the distance specified by *delta. More... | |
StatusInt mdlCurrTrans_begin | ( | ) |
Creates a new entry on the Current Transformation stack.
It is often useful for MDL applications to deal with positional (x,y,z) information in terms of "local" coordinate systems. For example, the coordinate values in MicroStation elements are in stored in storage units. However, it is often more desirable for MDL programmers to deal with coordinates in terms of "master units." The Current Transform functions provide a way for MDL applications to tell MicroStation to apply a coordinate transformation (a matrix multiply) to coordinate information passed to and from MDL functions.
Given that it is often necessary to temporarily shift to a new coordinate system and then return to the previous one, the Current Transformation system in MicroStation is implemented as a "stack". Each entry in the stack holds a forward and inverse transform, so that MDL can convert from local (top-of-stack) coordinates to world coordinates and vice-versa.
To establish a new temporary local coordinate system, you call mdlCurrTrans_begin
, The transform of the new top-of-stack after the call to mdlCurrTrans_begin
to will be the same as the top-of-stack transform before the call. However, modifications to the "current" (top-of-stack) transform will only change that transform, so calling mdlCurrTrans_end
will restore the Current Transform to the state immediately prior to the last call to mdlCurrTrans_begin
.
By default the Current Transform is the identity matrix. The new top-of-stack transform after the call will be the same as the top-of-stack transform before the call. Calls to mdlCurrTrans_begin
can be nested to any depth, but should always be matched with calls to mdlCurrTrans_end
or mdlCurrTrans_clear
. mdlCurrTrans_begin
must be called at least once before calls can be made to other mdlCurrTrans_... functions.
int mdlCurrTrans_clear | ( | ) |
Pops all pushed transformation matrices from the Current Transform stack.
After the mdlCurrTrans_clear
has been called, the Current Transformation becomes the identity matrix. This is useful for recovering from error conditions in a program.
StatusInt mdlCurrTrans_end | ( | ) |
Removes the top-of-stack transformation from the Current Transform stack.
StatusInt mdlCurrTrans_getAddresses | ( | TransformP * | fwd, |
TransformP * | inv | ||
) |
Returns the address of the current forward transform in *fwd and the address of the current inverse transform in *inv.
[out] | fwd | current forward transform |
[out] | inv | current inverse transform |
int mdlCurrTrans_getCount | ( | ) |
Gets the number of pushed transformation matrices on the Current Transform stack.
StatusInt mdlCurrTrans_getTransforms | ( | TransformP | pMdlToUor, |
TransformP | pUorToMdl | ||
) |
Return the current transforms.
[out] | pMdlToUor | "forward" transorm, typically understood as from working units of the app to design file units. Set to identity if no transforms in effect. |
[out] | pUorToMdl | "inverse" transorm, typically understood as from design file units to working units of the app. Set to identity if no transforms in effect. |
void mdlCurrTrans_getTransformToMDL | ( | TransformP | pCallerToMDL, |
TransformCP | pCallerToUOR | ||
) |
Combine a "caller to uors" transform with the currtrans "uor to mdl" transform.
[out] | pCallerToMDL | combined transform from caller's frame to top of stack. |
[in] | pCallerToUOR | transform from caller's frame (e.g. element in cache) to UOR's. |
StatusInt mdlCurrTrans_identity | ( | ) |
Replaces the current transformation matrix with the identity matrix.
This function is useful for returning the current transformation to a known state.
mdlCurrTrans_identity
after the first call to mdlCurrTrans_begin
, since the default transformation is the identity matrix. void mdlCurrTrans_invScaleDoubleArray | ( | double * | out, |
const double * | in, | ||
int | numValues | ||
) |
Scales an array of numValues values pointed to by <code>in</code> from the current coordinate
system into design file coordinates.
The resulting values are stored in the array pointed to by out
.
[out] | out | the array of resulting values after scaling |
[in] | in | the array of input values to be scaled |
[in] | numValues | the number of values in the array to scale |
Transforms an array of numPoints points, pointed to by <code>in</code>, from design file coordinates into the
current coordinate system.
The resulting points are stored in the array pointed to by out
.
[out] | out | the array of resulting points after transformation |
[in] | in | the array of input points to be transformed |
[in] | numPoints | the number of points in the array to transform |
void mdlCurrTrans_invtransRMatrix | ( | RotMatrixP | out, |
RotMatrixCP | in | ||
) |
Transforms a rotation matrix pointed
to by in
from design file coordinates into the current coordinate system.
The result is stored in the rotation matrix pointed to by out
.
[out] | out | current coordinates |
[in] | in | dgn coordinates |
StatusInt mdlCurrTrans_masterUnitsIdentity | ( | int | translateToGlobalOrigin | ) |
Identical to mdlCurrTrans_identity, except that it sets the scales of the transformation matrix to the number of UORs
per master unit.
After mdlCurrTrans_masterUnitsIdentity is called, all coordinates are in master units. If translateToGlobalOrigin is true, the current transformation is translated so that its (0, 0, 0) point is at the global origin. Otherwise, (0, 0, 0) is at the center of the design plane.
[in] | translateToGlobalOrigin | makes 0,0,0 global origin |
int mdlCurrTrans_masterUnitsIdentityForModel | ( | int | translateToGlobalOrigin, |
DgnModelRefP | modelRef | ||
) |
Sets the scales of the current transformation matrix to the number of UORs per master unit
as indicated by the specified model.
After calling this function, all coordinates are in master units.
[in] | translateToGlobalOrigin | If translateToGlobalOrigin is true, the current transformation is translated so that its (0, 0, 0) point is at the global origin as indicated by the specified model. Otherwise, (0, 0, 0) is at the center of the design plane. |
[in] | modelRef | identifies the model from which the master units and global origin information are obtained. |
StatusInt mdlCurrTrans_rotateByAngles | ( | double | xangle, |
double | yangle, | ||
double | zangle | ||
) |
Rotates the current transformation about its origin by
the angles specified in xAngle, yAngle, and zAngle
in radians.
[in] | xangle | the rotation angle about the x axis |
[in] | yangle | the rotation angle about the y axis |
[in] | zangle | the rotation angle about the z axis |
StatusInt mdlCurrTrans_rotateByRMatrix | ( | RotMatrixP | rotMatrix, |
int | reverse | ||
) |
Rotates the current transformation
about its origin by the rotation matrix pointed to by rotMatrix.
If reverse is true, the current transformation matrix is rotated by the inverse of rotMatrix.
[in] | rotMatrix | the rotation matrix to apply to the current transformation matrix |
[in] | reverse | if true, the current tranformation is rotated by the inverse of rotMatrix |
StatusInt mdlCurrTrans_rotateByView | ( | int | viewNumber | ) |
Rotates the current transformation about
its origin by the rotation matrix of view viewNumber.
For the rotation of the current transformation matrix to match the rotation of a view, verify that the current transformation is set to the identity matrix before calling mdlCurrTrans_rotateByView.
[in] | viewNumber | the index of the view to get the rotation matrix from |
StatusInt mdlCurrTrans_scale | ( | double | xscale, |
double | yscale, | ||
double | zscale | ||
) |
Scales the current transformation
matrix by the scale factors xScale, yScale, and zScale.
[in] | xscale | the scale factor to apply along the x axis |
[in] | yscale | the scale factor to apply along the y axis |
[in] | zscale | the scale factor to apply along the z axis |
void mdlCurrTrans_scaleDoubleArray | ( | double * | out, |
const double * | in, | ||
int | numValues | ||
) |
Scales an array of numValues double precision values pointed to by in from the current coordinate
system into design file coordinates.
The resulting values are stored in the array pointed to by out.
[out] | out | the array of scaled values |
[in] | in | the array of values to scale |
[in] | numValues | the number of values in the array |
StatusInt mdlCurrTrans_subUnitsIdentity | ( | int | translateToGlobalOrigin | ) |
Sets the scales of the transformation matrix to the number of UORs per sub unit.
After mdlCurrTrans_subUnitsIdentity
is called, all coordinates are in sub units.
[in] | translateToGlobalOrigin | If translateToGlobalOrigin is true, the current transformation is translated so that its (0, 0, 0) point is at the global origin. Otherwise, (0, 0, 0) is at the center of the design plane. |
int mdlCurrTrans_subUnitsIdentityForModel | ( | int | translateToGlobalOrigin, |
DgnModelRefP | modelRef | ||
) |
Sets the scales of the current transformation matrix to the number of UORs per sub unit as indicated
by the specified model.
After calling this function, all coordinates are in sub units.
[in] | translateToGlobalOrigin | If true, the current transformation is translated so that its (0, 0, 0) point is at the global origin as indicated by the specified model. Otherwise, (0, 0, 0) is at the center of the design plane. |
[in] | modelRef | identifies the model from which the sub-units and global origin information are obtained. |
Transforms an array of numPoints points, pointed to by in, from the current coordinate system into design
file coordinates.
The resulting points are stored in the array pointed to by out.
[out] | out | the array of points after transformation |
[in] | in | the array of points to be transformed |
[in] | numPoints | the number of points in the array |
void mdlCurrTrans_transformRMatrix | ( | RotMatrixP | out, |
RotMatrixCP | in | ||
) |
Transforms a rotation matrix pointed
to by in from the current coordinate system into design file coordinates.
The result is stored in the rotation matrix pointed to by out.
[out] | out | the rotation matrix after tranformation |
[in] | in | the rotation matrix to be transformed |
int mdlCurrTrans_translateOrigin | ( | Dpoint3d * | delta | ) |
Translates the origin of
the current transformation matrix by the distance specified by *delta.
The units for delta are in the scale of the current coordinate system.
[in] | delta | the distance to transform the current transform |
int mdlCurrTrans_translateOriginWorld | ( | Dpoint3d * | delta | ) |
Translates the origin
of the current transformation matrix by the distance specified by *delta.
The units for delta are in UORs. This function can be used to set the origin to a known point in the design plane.
[in] | delta | the distance to transform the current transform |