Auxiliary Coordinate Systems C Api

Functions
int	mdlACS_createElmdscr (MSElementDescrH eDPP, WCharCP nameP, WCharCP descriptionP, const Dpoint3d *originP, RotMatrixCP rotMatrixP, short type)
	Creates an ACS element descriptor. More...
int	mdlACS_extractElmdscr (Dpoint3d *originP, RotMatrixP rotMatrixP, short *typeP, WChar *nameP, WChar *descriptionP, MSElementDescrCP eDP)
	Extracts the auxiliary coordinate system from the saved ACS element in eDP. More...
int	mdlACS_attachNamed (WCharCP unparsed, bool useRot, bool useOrg)
	Attaches the named auxiliary coordinate system (ACS) to the active model. More...
int	mdlACS_deleteNamed (WCharCP acsName)
	Deletes the named coordinate system specified. More...
bool	mdlACS_isDefined ()
	Determines whether an ACS has been defined for the active model. More...
int	mdlACS_getCurrent (Dpoint3d *originP, RotMatrixP rotMatrixP, DgnPlatform::ACSType *typeP, WChar *nameP, WChar *descriptionP)
	Returns the current ACS's origin, rotation matrix, and type. More...
StatusInt	mdlACS_saveNamed (WChar const *name, WChar const *description)
	Saves the current coordinate system with the specified name and description. More...
int	mdlACS_setCurrent (Dpoint3d *originP, RotMatrixP rotMatrixP, DgnPlatform::ACSType const *type)
	Defines the ACS of the active model. More...
int	mdlACS_locate (MSElementDescrH edPP, UInt32 *filePosP, WCharCP inName, DgnModelRefP modelRef)
	Searches for an ACS using its assigned name. More...
int	mdlACS_getNameOfElmdscr (WChar *acsNameP, MSElementDescrCP edP)
	Gets the name from the specified ACS element descriptor. More...
int	mdlACS_getDescriptionOfElmdscr (WChar *acsDescriptionP, MSElementDescrCP edP)
	Gets the description from the specified ACS element. More...
int	mdlACS_setNameOfElmdscr (MSElementDescrH edPP, WChar const *name)
	Sets the name on the specified ACS element. More...
int	mdlACS_setDescriptionOfElmdscr (MSElementDescrH edPP, WChar const *description)
	Sets the description on the specified ACS element. More...
int	mdlACS_traverseElements (DgnModelRefP modelRef, ACSTraverseFunctionP userFunc, CallbackArgP userDataP)
	Traverses over the elements in a model searching for ACS elements. More...
int	mdlACS_getCanonicalName (WChar *canonicalP, WChar const *nameP)
	Canonizes the specified ACS name string. More...
int	mdlACS_getCanonicalDescription (WChar *canonicalP, WChar const *descrP)
	Canonize the specified ACS description string. More...
int	mdlACS_getTypeOfElmdscr (short *acsTypeP, MSElementDescrCP edP)
	Get the ACS type of the ACS element descriptor. More...
int	mdlACS_setTypeOfElmdscr (MSElementDescrP edP, short const *acsTypeP)
	Sets the ACS type of the ACS element descriptor. More...
int	mdlACS_createElmdscrFromParams (MSElementDescrH edPP, short type, Dpoint3d const *originP, RotMatrixCP rotationP, WChar const *nameP, WChar const *descriptionP)
	Creates an ACS element descriptor from the given parameters. More...

Detailed Description

Function Documentation

int mdlACS_attachNamed	(	WCharCP	unparsed,
		bool	useRot,
		bool	useOrg
	)

 Attaches the named auxiliary coordinate system (ACS)

to the active model.

Parameters

[in]	unparsed	the name of the coordinate system to attach
[in]	useRot	true means apply the rotation stored in the named ACS, and false means ignore it
[in]	useOrg	true means apply the origin stored in the named ACS, and false means ignore it

Returns

SUCCESS if the coordinate system is successfully attached and MDLERR_ACSNOTFOUND if the specified coordinate system is not found.

See also

mdlACS_deleteNamed mdlACS_saveNamed

mdlACS_saveNamed

Remarks

Required Library: mdlbltin.lib

int mdlACS_createElmdscr	(	MSElementDescrH	eDPP,
		WCharCP	nameP,
		WCharCP	descriptionP,
		const Dpoint3d *	originP,
		RotMatrixCP	rotMatrixP,
		short	type
	)

Creates an ACS element descriptor.

Parameters

[out]	eDPP	ACS element descriptor, which you must free when done.
[in]	nameP	ACS Name.
[in]	descriptionP	ACS Description.
[in]	originP	ACS origin. If NULL, uses (0.0, 0.0, 0.0).
[in]	rotMatrixP	ACS RotMatrix. If NULL, uses identity matrix.
[in]	type	one of the valid ACS type constants. Possible values are: ACS_TYPE_NONE ACS_TYPE_RECT ACS_TYPE_CYL ACS_TYPE_SPHERE

Returns

SUCCESS or an appropriate error code

Remarks

This function differs from mdlACS_createElmdscrFromParams in that it applies the MDL application's current transformation to originP and rotMatrixP.

See also

mdlACS_extractElement mdlACS_createElmdscrFromParams

Remarks

Required Library: mdllib.dll

int mdlACS_createElmdscrFromParams	(	MSElementDescrH	edPP,
		short	type,
		Dpoint3d const *	originP,
		RotMatrixCP	rotationP,
		WChar const *	nameP,
		WChar const *	descriptionP
	)

 Creates

an ACS element descriptor from the given parameters.

Parameters

[out]	edPP	is the newly created ACS element descriptor, which you must free when done.
[in]	type	is one of the valid ACS type constants. Possible values are: ACS_TYPE_NONE ACS_TYPE_RECT ACS_TYPE_CYL ACS_TYPE_SPHERE
[in]	originP	origin of the ACS.
[in]	rotationP	rotation of the ACS.
[in]	nameP	name of the ACS.
[in]	descriptionP	the description of the ACS.

Returns

SUCCESS if the element descriptor was created successfully, MDLERR_BADARG if any of the parameters was not valid.

Remarks

Required Library: mdlbltin.lib

int mdlACS_deleteNamed

(

WCharCP

acsName

)

 Deletes the named coordinate

system specified.

Parameters

[in]

acsName

name of the coordinate system

Returns

SUCCESS if the coordinate system is successfully deleted and MDLERR_ACSNOTFOUND if the specified coordinate system is not found.

See also

mdlACS_attachNamed mdlACS_saveNamed

Remarks

Required Library: mdlbltin.lib

int mdlACS_extractElmdscr	(	Dpoint3d *	originP,
		RotMatrixP	rotMatrixP,
		short *	typeP,
		WChar *	nameP,
		WChar *	descriptionP,
		MSElementDescrCP	eDP
	)

Extracts the auxiliary coordinate system from the saved ACS element in eDP.

Parameters

[out]	originP	ACS origin
[out]	rotMatrixP	ACS RotMatrix
[out]	typeP	ACS Type
[out]	nameP	ACS Name
[out]	descriptionP	ACS Description
[in]	eDP	ACS element descriptor

Returns

SUCCESS or an appropriate error code

Remarks

Parameters for which the output is not needed can be set to NULL.

See also

mdlACS_extractElement

Remarks

Required Library: mdllib.dll

int mdlACS_getCanonicalDescription	(	WChar *	canonicalP,
		WChar const *	descrP
	)

 Canonize the

specified ACS description string.

The result is the name string stripped of leading and trailing whitespace characters, whose length and content has been validated.

Parameters

[out]	canonicalP	points to a string buffer where the canonized description is placed. This buffer should be MAX_ACS_DESCR_LENGTH MSWChars long.
[in]	descrP	ACS description to be canonized.

Returns

SUCCESS unless the name string is too large (MDLERR_BADARG) or there is not enough memory to allocate working buffers (MDLERR_INSFMEMORY).

See also

mdlACS_getDescriptionOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_getCanonicalName	(	WChar *	canonicalP,
		WChar const *	nameP
	)

 Canonizes the

specified ACS name string.

The result is the name string stripped of leading and trailing whitespace characters, whose length and content has been validated.

Parameters

[out]	canonicalP	is a pointer to a string buffer where the canonized name is placed. This buffer should be MAX_ACS_NAME_LENGTH MSWChars long.
[in]	nameP	ACS name to be canonized.

Returns

SUCCESS unless the name string is too large or there is not enough memory to allocate working buffers.

See also

mdlACS_getNameOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_getCurrent	(	Dpoint3d *	originP,
		RotMatrixP	rotMatrixP,
		DgnPlatform::ACSType *	typeP,
		WChar *	nameP,
		WChar *	descriptionP
	)

 Returns the current ACS's origin,

rotation matrix, and type.

Remarks

The coordinate system type is specified by one of the following types from msdefs.h:

• ACS_RECTANGULAR
• ACS_CYLINDRICAL
• ACS_SPHERICAL

Parameters

[out]	originP	current ACS origin
[out]	rotMatrixP	current ACS orientation
[out]	typeP	current ACS type
[out]	nameP	points to a buffer where the name is copied. This buffer should be MAX_ACS_NAME_LENGTH MSWChars long.
[out]	descriptionP	points to a buffer where the description is copied. This buffer should be MAX_ACS_DESCR_LENGTH MSWChars long

Returns

SUCCESS if an ACS is active and MDLERR_NOACSDEFINED if no system is currently defined.

See also

mdlACS_setCurrent

Remarks

Required Library: mdlbltin.lib

int mdlACS_getDescriptionOfElmdscr	(	WChar *	acsDescriptionP,
		MSElementDescrCP	edP
	)

 Gets

the description from the specified ACS element.

Parameters

[out]	acsDescriptionP	points to a buffer where the description is copied. This buffer should be MAX_ACS_DESCR_LENGTH MSWChars long
[in]	edP	points to the ACS element to get the description from.

Returns

SUCCESS if the operation was completed successfully, otherwise ERROR.

See also

mdlACS_setDescriptionOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_getNameOfElmdscr	(	WChar *	acsNameP,
		MSElementDescrCP	edP
	)

 Gets the name

from the specified ACS element descriptor.

Parameters

[out]	acsNameP	points to a buffer where the name is copied. This buffer should be MAX_ACS_NAME_LENGTH MSWChars long.
[in]	edP	points to the ACS element to get the name from.

Returns

SUCCESS if the operation was completed successfully, otherwise ERROR.

See also

mdlACS_setNameOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_getTypeOfElmdscr	(	short *	acsTypeP,
		MSElementDescrCP	edP
	)

Get the ACS type of the ACS element descriptor.

Parameters

[out]	acsTypeP	points to a variable which will contain one of the following values upon a return of SUCCESS. ACS_TYPE_NONE ACS_TYPE_RECT ACS_TYPE_CYL ACS_TYPE_SPHERE
[in]	edP	points to the ACS element.

Returns

SUCCESS if the element is an ACS element, MDLERR_BADARG if it is not.

See also

mdlACS_setTypeOfElmdscr

Remarks

Required Library: mdlbltin.lib

bool mdlACS_isDefined

(

)

Determines whether an ACS has been defined for the active model.

Returns

true if any ACS has been defined, false if no ACS has been defined.

Remarks

Required Library: mdlbltin.lib

int mdlACS_locate	(	MSElementDescrH	edPP,
		UInt32 *	filePosP,
		WCharCP	inName,
		DgnModelRefP	modelRef
	)

Searches for an ACS

using its assigned name.

Parameters

[out]	edPP	Copy of ACS element descriptor. You must free it when done.
[out]	filePosP	file position of the located ACS element.
[in]	inName	name of the ACS element to find.
[in]	modelRef	model to search for the ACS element.

Returns

SUCCESS if the operation completed successfully, otherwise ERROR.

See also

mdlACS_traverseElements

Remarks

Required Library: mdlbltin.lib

StatusInt mdlACS_saveNamed	(	WChar const *	name,
		WChar const *	description
	)

 Saves the current coordinate

system with the specified name and description.

The name must consist of one to MAX_ACS_NAME_LENGTH MSWChars, and the description can contain up to MAX_ACS_DESCR_LENGTH MSWChars. The user or an MDL application can recall saved coordinate systems with the mdlACS_attachNamed function.

Parameters

[in]	name	name of the ACS
[in]	description	description of the ACS

Returns

SUCCESS if the coordinate system is successfully saved. If the coordinate system name already exists, the existing ACS is overwritten. If no ACS is active, MDLERR_NOACSDEFINED is returned.

See also

mdlACS_attachNamed mdlACS_deleteNamed

Remarks

Required Library: mdlbltin.lib

int mdlACS_setCurrent	(	Dpoint3d *	originP,
		RotMatrixP	rotMatrixP,
		DgnPlatform::ACSType const *	type
	)

Defines the ACS of the active model.

• ACS_RECTANGULAR
• ACS_CYLINDRICAL
• ACS_SPHERICAL

Parameters

[in]	originP	new ACS origin or pass NULL to leave unchanged
[in]	rotMatrixP	new ACS orientation or pass NULL to leave unchanged
[in]	type	new ACS type or pass NULL to leave unchanged

Returns

SUCCESS if the coordinate system is successfully defined.

See also

mdlACS_getCurrent

Remarks

Required Library: mdlbltin.lib

int mdlACS_setDescriptionOfElmdscr	(	MSElementDescrH	edPP,
		WChar const *	description
	)

Sets the description on the specified ACS element.

Parameters

[out]	edPP	points to ACS element descriptor pointer.
[in]	description	points to a buffer where the description is stored.

Returns

SUCCESS if the operation was completed successfully, otherwise ERROR.

See also

mdlACS_getDescriptionOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_setNameOfElmdscr	(	MSElementDescrH	edPP,
		WChar const *	name
	)

Sets the name on the specified ACS element.

Parameters

[out]	edPP	points to ACS element descriptor pointer.
[in]	name	points to a buffer where the name is stored.

Returns

SUCCESS if the operation was completed successfully, otherwise ERROR.

See also

mdlACS_getNameOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_setTypeOfElmdscr	(	MSElementDescrP	edP,
		short const *	acsTypeP
	)

 Sets the ACS type

of the ACS element descriptor.

Parameters

[out]	edP	ACS element descriptor which is being accessed
[in]	acsTypeP	type to set in the ACS, and should be one of: ACS_TYPE_NONE ACS_TYPE_RECT ACS_TYPE_CYL ACS_TYPE_SPHERE

Returns

SUCCESS if the element is an ACS element, MDLERR_BADARG if it is not.

See also

mdlACS_getTypeOfElmdscr

Remarks

Required Library: mdlbltin.lib

int mdlACS_traverseElements	(	DgnModelRefP	modelRef,
		ACSTraverseFunctionP	userFunc,
		CallbackArgP	userDataP
	)

 Traverses over

the elements in a model searching for ACS elements.

A user function can be specified, and is called with an element descriptor for each ACS element found in the specified model.

Parameters

[in]	modelRef	which model to search.
[in]	userFunc	pointer to the user function to invoke for each ACS element found.
[in]	userDataP	user data to pass in to callback, or is set to NULL.

Returns

SUCCESS if the operation has completed successfully.

See also

mdlACS_locate

Remarks

Required Library: mdlbltin.lib