ModelAccess API

Classes
struct	API_3D_Head
	Common header for the 3D components. More...
struct	API_BodyType
	Representation of a 3D body. More...
struct	API_PgonType
	Representation of a 3D Polygon. More...
struct	API_PedgType
	Representation of a 3D edge reference. More...
struct	API_EdgeType
	Representation of a 3D edge. More...
struct	API_VertType
	Representation of a 3D vertex. More...
struct	API_VectType
	Representation of a 3D normal vector. More...
struct	API_LghtType
	Representation of a 3D light source. More...
struct	API_UmatType
	Representation of a 3D material. More...
union	API_Component3D
	General representation of a 3D component. More...
struct	API_Texture
	Texture reference. More...
struct	API_MaterialType
	Description of a surface material attribute. More...
struct	API_UVCoord
	The local coordinate system of a texture at a given surface point. More...
struct	API_ElemInfo3D
	3D data of an element. More...
struct	API_TexCoordPars
	Identifies the surface point to get the texture coordinates for. More...

Enumerations
enum	API_3DTypeID {   API_Zombie3DID = 0 , API_BodyID , API_PgonID , API_PedgID ,   API_EdgeID , API_VertID , API_VectID , API_UmatID ,   API_LghtID }
	This is the enumeration of the applicable types of 3D components. More...
enum	API_LghtSouID {   APILght_DistantID , APILght_DirectionID , APILght_SpotID , APILght_PointID ,   APILght_SunID , APILght_EyeID }
	Possible types of a 3D light source. More...
enum	API_MaterTypeID {   APIMater_GeneralID , APIMater_SimpleID , APIMater_MatteID , APIMater_MetalID ,   APIMater_PlasticID , APIMater_GlassID , APIMater_GlowingID , APIMater_ConstID }
	Enumeration of material types. More...

Functions
GSErrCode	ACAPI_ModelAccess_GetTextureCoord (API_TexCoordPars *texCoordPars, API_UVCoord *uvCoord)
	Returns the texture coordinates of the given surface point.
GSErrCode	ACAPI_ModelAccess_Get3DInfo (const API_Elem_Head &elemHead, API_ElemInfo3D *info3D)
	Retrieves information on the 3D data of an element.
GSErrCode	ACAPI_ModelAccess_GetConnectionTable (const GS::HashSet< API_Guid > &elementList, API_ElementConnectionTable *connectionTable)
	Returns a table of connected elements and the connecting polygons.
GSErrCode	ACAPI_ModelAccess_GetBuildingMaterial (const UInt32 elemIdx, const UInt32 bodyIdx, API_AttributeIndex *materialIdx)
	Returns the attribute index of the material of a specific body of an element.
GSErrCode	ACAPI_ModelAccess_GetNum (API_3DTypeID typeID, Int32 *count)
	Returns the number of existing 3D components.
GSErrCode	ACAPI_ModelAccess_GetComponent (API_Component3D *component)
	Retrieves a component from the 3D model of Archicad.
GSErrCode	ACAPI_ModelAccess_DecomposePgon (Int32 ipgon, Int32 ***cpoly)
	Decomposes a polygon of the 3D model into convex polygons.
GSErrCode	ACAPI_ModelAccess_GenerateModelWithSeparateComponents (const GS::Array< API_Guid > &elementGuids)
	Generates a model with separate components of the given elements, and switches to that model for subsequent operations. The operation will not be executed if the active sight is the sight of 3D window.

Detailed Description

Model Access API

The ModelAccess API provides geometry-level access to the 3D model of the Virtual Building.

3D Database

To have an overview what the 3D model is, and how it fits into the entire database please refer to the Element_Overview chapter.

3D Manager

To have an overview on the 3D model of Archicad, and how the 3D database fits into the entire database system please refer to the Element Overview chapter.

All of the 3D handler function begin with the ACAPI_ModelAccess_ prefix. This function family gives support to query the 3D database. Modifications are not supported in this version of the API; you have no possibility to change the 3D model.

Enumeration Type Documentation

API_3DTypeID

enum API_3DTypeID

This is the enumeration of the applicable types of 3D components.

Remarks

These component types are usable in the typeID field of API_3D_Head structure.

API_LghtSouID

enum API_LghtSouID

Possible types of a 3D light source.

Remarks

These identifiers are usable in API_LghtType type field.

API_MaterTypeID

enum API_MaterTypeID

Enumeration of material types.

Remarks

This type identifier can be used as mtype in API_MaterialType.

Function Documentation

ACAPI_ModelAccess_DecomposePgon()

GSErrCode ACAPI_ModelAccess_DecomposePgon	(	Int32	ipgon,
		Int32 ***	cpoly
	)

Decomposes a polygon of the 3D model into convex polygons.

Parameters

ipgon	[in] Index of a polygon in the 3D model.
cpoly	[out] Points to an array which contains the vertices of subpolygons.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr ; cpoly
• APIERR_REFUSEDCMD - The 3D model is not available in the current context, or The polygon type cannot be queried directly; no active body
• APIERR_BADINDEX - The polygon index is out of range
• APIERR_MEMFULL - Not enough memory

Remarks

This function is used to decompose a polygon into convex polygons. The polygon is defined by ipgon index. The decomposed polygon is returned in the cpoly Int32 array, which contains the following values: [-n], [-m1 ], i1, i2, ... i(m1 ), [-m2 ], j1, j2, ... j(m2 )... where:

• negative values mean some kind of measurement
• positive values mean vertex indices

  Parameter	Descriptions
  n	The number of subpolygons. Can be 0 on error, or if the polygon is degenerate.
  m i	The number of vertices of the following subpolygon
  i1 .. i(m 1 ) j1 .. j(m 2 )	The actual VERT indices of the subpolygons. The function doesn't generate new points, so these indices refer to the original VERT indices.

  Do not forget to dispose the returned handle if it is not needed any more.

ACAPI_ModelAccess_GenerateModelWithSeparateComponents()

GSErrCode ACAPI_ModelAccess_GenerateModelWithSeparateComponents

(

const GS::Array< API_Guid > &

elementGuids

)

Generates a model with separate components of the given elements, and switches to that model for subsequent operations. The operation will not be executed if the active sight is the sight of 3D window.

Parameters

elementGuids

[in] The guids of the elements which will be part of the model.

Returns

• NoError - The function has completed with success.
• APIERR_REFUSEDCMD - The 3D model is not available in the current context.
• APIERR_BADID - One of the elements represented by a guid can not be found in the project.
• APIERR_GENERAL - The active sight is the sight of 3D Window.

Remarks

Before calling this function, you should create a new sight (ACAPI_Sight_CreateSight) and select it as active sight (ACAPI_Sight_SelectSight). Don't forget to delete the sight in the end (ACAPI_Sight_DeleteSight).

ACAPI_ModelAccess_Get3DInfo()

GSErrCode ACAPI_ModelAccess_Get3DInfo	(	const API_Elem_Head &	elemHead,
		API_ElemInfo3D *	info3D
	)

Retrieves information on the 3D data of an element.

Parameters

elemHead	[in] The element to get the 3D information for.
info3D	[out] The 3D information to be retrieved.

Returns

• NoError - The operation was successful.
• APIERR_BADID - Incorrect elemHead.guid was specified. Incorrect type was specified, for example 0 or an element without 3D representation. such as API_LineID.
• APIERR_BADPARS - The info3D parameter was nullptr.
• APIERR_NOTMINE - The element was attempted to be accessed on a layer owned by someone else. Most likely to occur when working on documents in teamwork mode.
• APIERR_LOCKEDLAY - The element was attempted to be accessed on a locked layer.
• APIERR_HIDDENLAY - The element was attempted to be accessed on a hidden layer.
• APIERR_GENERAL - The element wasn't found in the 3D database.

Remarks

This function returns information on the 3D data of the element defined by elemHead. This function is defined only for those elements which have 3D representation: API_WallID, API_ColumnID, API_BeamID, API_WindowID, API_DoorID, API_ObjectID, API_LampID, API_SlabID, API_RoofID, and API_RoomID. The returned structure contains the first and last body (or, in case of API_LampID, the first and last light also) indices of the element's 3D data. This index is an index to the whole 3D data structure, where all the 3D data is stored in a continuous way. The 3D data of the element doesn't need to exist; Archicad will convert the element to 3D independently of any existing 3D window data. This also means that the 3D representation doesn't contain perspective cuts and 3D cut planes! Currently, this is the only way to obtain information on holes in walls. Look for polygons which have a horizontal normal vector perpendicular to the reference line of the wall. Similarly, you can get information on the intersection of walls by looking for polygons with a vertical normal vector. You can find more information on the 3D data in the 3D Manager and at the API_ElemInfo3D page of this help. You have to be familiar with the primitive element section of the GDL Reference Manual.

ACAPI_ModelAccess_GetBuildingMaterial()

GSErrCode ACAPI_ModelAccess_GetBuildingMaterial	(	const UInt32	elemIdx,
		const UInt32	bodyIdx,
		API_AttributeIndex *	materialIdx
	)

Returns the attribute index of the material of a specific body of an element.

Parameters

elemIdx	[in] The index of the element.
bodyIdx	[in] The index of the body in the element.
materialIdx	[out] API_AttributeIndex of the material.

Returns

• NoError - The operation was successful.
• APIERR_BADDATABASE - Not the appropriate database was open for the operation. Only 2D and 3D are supported.
• APIERR_REFUSEDCMD - The 3D model is not available in the current context.
• APIERR_GENERAL - Data for the given element can not be found.

Remarks

This function can not work properly unless the model of the active sight was generated for separate components with the ACAPI_ModelAccess_GenerateModelWithSeparateComponents function.

ACAPI_ModelAccess_GetComponent()

GSErrCode ACAPI_ModelAccess_GetComponent

(

API_Component3D *

component

)

Retrieves a component from the 3D model of Archicad.

Parameters

component

[in/out] The typeID and the index field of the component header must be passed. You get the desired component data in the appropriate part of the union.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; component
• APIERR_REFUSEDCMD - The 3D model is not available in the current context, or The component type cannot be queried directly; no active body
• APIERR_BADID - The component type is invalid
• APIERR_BADINDEX - The component index is out of range
• APIERR_DELETED - In case of typeID is API_BodyID, you can get this error code, meaning the body has been removed from the 3D model because it was deleted, it is shadow body instead of a model one or it was eliminated during the model creation.

Remarks

This function is used to retrieve one component from the 3D data structure. The component is defined by the typeID and index fields in the header of the component parameter. If the typeID is API_BodyID you may get the error code APIERR_DELETED, meaning the body has been removed from the 3D model. It is very important to organize your algorithm on a loop based on the component API_BodyID (see example below) for the following reasons:

• Body indices are continuos in all cases, others are not.
• The 3D model also can have data from deleted floor plan elements. They can be identified only through the deleted bodies.
• Floor plan elements which have the same geometry may share the primitives of the 3D representation data, but not the bodies. All the bodies contain a transformation matrix which transforms the referenced shared vertices and normal vectors to the right places and directions. Once you have the definition of a body, you can set up sub loops to go through the primitives you are interested for. In the API_BodyType record you get the number of all internal components. Indices should start from 1. The light and material components can be obtained in their own loops, because they are global (not body relative) components of the 3D model. It is very important, that you get the data of the 3D model of Archicad that actually exists. This data is often not consistent with the floor plan elements. The update mechanism of the 3D window depends on many things, such as the switches in the preferences dialogs. As a general rule, you get the model which can be seen in the 3D window, if you use the above template.

Example

API_Component3D          comp3D;
Int32                    nBody, i;
 
err = ACAPI_ModelAccess_GetNum (API_BodyID, &nBody);
BNZeroMemory (&comp3D, sizeof (API_Component3D));
comp3D.header.typeID = API_BodyID;
for (i = 1; i <= nBody && err == NoError; i++) {
    comp3D.header.index = i;
    err = ACAPI_ModelAccess_GetComponent (&comp3D);
    if (err == NoError) {
        /* explode the body into pgon, vert etc... */
    }
    if (err == APIERR_DELETED)
        err = NoError;
}

ACAPI_ModelAccess_GetConnectionTable()

GSErrCode ACAPI_ModelAccess_GetConnectionTable	(	const GS::HashSet< API_Guid > &	elementList,
		API_ElementConnectionTable *	connectionTable
	)

Returns a table of connected elements and the connecting polygons.

Parameters

elementList	[in] List of API_Guids, referencing elements from the active sight. Archicad will search connections among these elements.
connectionTable	[out] The returned table which consists of pairs of element ids as keys, and an array of polygons representing the connecting surface between the respective pair of elements.

Returns

• NoError - The operation was successful.
• APIERR_REFUSEDCMD - The 3D model is not available in the current context.
• APIERR_GENERAL - Error regarding the active sight.

ACAPI_ModelAccess_GetNum()

GSErrCode ACAPI_ModelAccess_GetNum	(	API_3DTypeID	typeID,
		Int32 *	count
	)

Returns the number of existing 3D components.

Parameters

typeID	[in] Type of the 3D component.
count	[out] Number of component with the given type.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr ; count
• APIERR_REFUSEDCMD - The 3D model is not available in the current context
• APIERR_BADID - The component type is invalid
• APIERR_REFUSEDPAR - The component type cannot be queried directly

Remarks

This function is used to get the number of 3D components with a given type. Refer to the API_3DTypeID structure for the possible values. Only the API_BodyID, API_LghtID and API_UmatID type components can be addressed with this function. Model dependent components (API_PgonID, API_PedgID, API_EdgeID, API_VertID, API_VectID) are body dependent; direct access is prohibited. The number of these components can be determined from the API_BodyType type.

Example

See the example of the ACAPI_ModelAccess_GetComponent
function.

ACAPI_ModelAccess_GetTextureCoord()

GSErrCode ACAPI_ModelAccess_GetTextureCoord	(	API_TexCoordPars *	texCoordPars,
		API_UVCoord *	uvCoord
	)

Returns the texture coordinates of the given surface point.

Parameters

texCoordPars	[in] identifies the surface point
uvCoord	[out] the local (u, v) coordinate system of the texture

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - one or both of the parameters are nullptr
• APIERR_GENERAL - Couldn't get the texture coordinates