Functions
CurrentTransform

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 in from design file coordinates into the current coordinate system. More...

 
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 xAngle, yAngle, and zAngle in radians. More...

 
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...

 

Detailed Description

Function Documentation

StatusInt mdlCurrTrans_begin ( )

Creates a new entry on the Current Transformation stack.

The Current Transform

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.

Returns
SUCCESS if the transformation was successfully pushed.
See also
mdlCurrTrans_end mdlCurrTrans_clear
Remarks
Required Library: mdlbltin.lib
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.

Returns
returns the number of entries popped.
See also
mdlCurrTrans_begin mdlCurrTrans_end
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCurrTrans_end ( )

Removes the top-of-stack transformation from the Current Transform stack.

Returns
SUCCESS if a transformation is popped. Otherwise, MDLERR_NOTRANSFORM if no transformation was pushed.
See also
mdlCurrTrans_begin mdlCurrTrans_clear
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]fwdcurrent forward transform
[out]invcurrent inverse transform
Remarks
These addresses can be used to perform transform operations that MDL does not support. If you change the forward transform, you must also change the inverse transform so that the product of the two is always the identity matrix.
The addresses returned are valid only for the current transformation. Any calls to mdlCurrTrans_begin or mdlCurrTrans_end cause these addresses to become invalid.
Use mdlCurrTrans_getTransforms to just copy the transforms out. Please stop using mdlCurrTrans_getAddresses.
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_begin mdlCurrTrans_end
Remarks
Required Library: mdlbltin.lib
int mdlCurrTrans_getCount ( )

Gets the number of pushed transformation matrices on the Current Transform stack.

Returns
returns the number of entries popped.
See also
mdlCurrTrans_begin mdlCurrTrans_end
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCurrTrans_getTransforms ( TransformP  pMdlToUor,
TransformP  pUorToMdl 
)

Return the current transforms.

Parameters
[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.
Returns
SUCCESS if transforms taken form currtrans stack, MDLERR_NO_TRANSFORMS if stack is empty.
See also
mdlCurrTrans_begin mdlCurrTrans_end
Remarks
Required Library: mdlbltin.lib
void mdlCurrTrans_getTransformToMDL ( TransformP  pCallerToMDL,
TransformCP  pCallerToUOR 
)

Combine a "caller to uors" transform with the currtrans "uor to mdl" transform.

Parameters
[out]pCallerToMDLcombined transform from caller's frame to top of stack.
[in]pCallerToUORtransform from caller's frame (e.g. element in cache) to UOR's.
Returns
SUCCESS if transforms taken form currtrans stack, MDLERR_NO_TRANSFORMS if stack is empty.
Remarks
Required Library: mdlbltin.lib
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.

Remarks
It is not necessary to call mdlCurrTrans_identity after the first call to mdlCurrTrans_begin, since the default transformation is the identity matrix.
Returns
SUCCESS MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_masterUnitsIdentity
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]outthe array of resulting values after scaling
[in]inthe array of input values to be scaled
[in]numValuesthe number of values in the array to scale
Remarks
Both mdlCurrTrans_scaleDoubleArray and mdlCurrTrans_invScaleDoubleArray will produce incorrect results if the current coordinate system transformation contains nonuniform scaling (different scale factors in the X, Y or Z directions).
See also
mdlCurrTrans_transformPointArray mdlCurrTrans_invtransPointArray mdlCurrTrans_transformRMatrix mdlCurrTrans_invtransRMatrix mdlCurrTrans_scaleDoubleArray
Remarks
Required Library: mdlbltin.lib
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.

The resulting points are stored in the array pointed to by out.

Parameters
[out]outthe array of resulting points after transformation
[in]inthe array of input points to be transformed
[in]numPointsthe number of points in the array to transform
Remarks
in and out can point to the same array.
See also
mdlCurrTrans_transformPointArray
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]outcurrent coordinates
[in]indgn coordinates
See also
mdlCurrTrans_transformPointArray mdlCurrTrans_invtransPointArray mdlCurrTrans_scaleDoubleArray mdlCurrTrans_invScaleDoubleArray mdlCurrTrans_transformRMatrix
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]translateToGlobalOriginmakes 0,0,0 global origin
Remarks
mdlCurrTrans_identity does not need to be called after the first call to mdlCurrTrans_begin since the default transformation is the identity matrix.
Returns
SUCCESS if successful, or MDLERR_NOTRANSFORM if there is no current transformation.
See also
mdlCurrTrans_identity mdlCurrTrans_masterUnitsIdentityForModel
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]translateToGlobalOriginIf 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]modelRefidentifies the model from which the master units and global origin information are obtained.
Returns
SUCCESS if the operation is completed successfully, otherwise ERROR.
See also
mdlCurrTrans_subUnitsIdentityForModel
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.

Parameters
[in]xanglethe rotation angle about the x axis
[in]yanglethe rotation angle about the y axis
[in]zanglethe rotation angle about the z axis
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
Remarks
In 3D files, the rotations are applied first about the Z-axis, then about the Y-axis, and finally about the X-axis. If this is not the desired order of rotation, make separate calls to this function.
In 2D files, only zAngle is used.
See also
mdlCurrTrans_rotateByRMatrix mdlCurrTrans_rotateByView
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]rotMatrixthe rotation matrix to apply to the current transformation matrix
[in]reverseif true, the current tranformation is rotated by the inverse of rotMatrix
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_rotateByAngles mdlCurrTrans_rotateByView
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]viewNumberthe index of the view to get the rotation matrix from
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_rotateByAngles mdlCurrTrans_rotateByRMatrix
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCurrTrans_scale ( double  xscale,
double  yscale,
double  zscale 
)

Scales the current transformation

matrix by the scale factors xScale, yScale, and zScale.

Parameters
[in]xscalethe scale factor to apply along the x axis
[in]yscalethe scale factor to apply along the y axis
[in]zscalethe scale factor to apply along the z axis
Remarks
The axes refer to the axes of the current coordinate system.
In 2D files, zScale is ignored.
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]outthe array of scaled values
[in]inthe array of values to scale
[in]numValuesthe number of values in the array
Remarks
Both mdlCurrTrans_scaleDoubleArray and mdlCurrTrans_invScaleDoubleArray will produce incorrect results if the current coordinate system transformation contains nonuniform scaling (different scale factors in the X, Y or Z directions).
See also
mdlCurrTrans_transformPointArray mdlCurrTrans_invtransPointArray mdlCurrTrans_transformRMatrix mdlCurrTrans_invtransRMatrix mdlCurrTrans_invScaleDoubleArray
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]translateToGlobalOriginIf 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.
Returns
SUCCESS if successful, or MDLERR_NOTRANSFORM if there is no current transformation.
See also
mdlCurrTrans_subUnitsIdentityForModel
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]translateToGlobalOriginIf 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]modelRefidentifies the model from which the sub-units and global origin information are obtained.
Returns
SUCCESS if the operation is completed successfully, otherwise ERROR.
See also
mdlCurrTrans_subUnitsIdentity
Remarks
Required Library: mdlbltin.lib
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.

The resulting points are stored in the array pointed to by out.

Parameters
[out]outthe array of points after transformation
[in]inthe array of points to be transformed
[in]numPointsthe number of points in the array
Remarks
in and out can point to the same array.
See also
mdlCurrTrans_invtransPointArray
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]outthe rotation matrix after tranformation
[in]inthe rotation matrix to be transformed
Returns
mdlCurrTrans_transformRMatrix is of type void, it does not return a value.
See also
mdlCurrTrans_transformPointArray mdlCurrTrans_invtransPointArray mdlCurrTrans_scaleDoubleArray mdlCurrTrans_invScaleDoubleArray mdlCurrTrans_invtransRMatrix
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]deltathe distance to transform the current transform
Remarks
The mdlCurrTrans_translateOrigin function always translates the origin from the current position. To set the origin to an absolute coordinate, call mdlCurrTrans_identity first.
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_translateOriginWorld
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]deltathe distance to transform the current transform
Remarks
The mdlCurrTrans_translateOriginWorld function always translates the origin from the current position. To set the origin to an absolute coordinate, call mdlCurrTrans_identity first.
Returns
MDLERR_NOTRANSFORM if there is no current transformation. Otherwise, SUCCESS.
See also
mdlCurrTrans_translateOrigin
Remarks
Required Library: mdlbltin.lib

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.