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]	fwd	current forward transform
[out]	inv	current 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]	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.

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

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

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]	out	current coordinates
[in]	in	dgn 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]

translateToGlobalOrigin

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

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

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

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]

viewNumber

the 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]	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

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]	out	the array of scaled values
[in]	in	the array of values to scale
[in]	numValues	the 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]

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.

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

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

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]	out	the rotation matrix after tranformation
[in]	in	the 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]

delta

the 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]

delta

the 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