ACAPI_​3D_​GetComponent

Retrieves a component from the 3D model of ARCHICAD.

    GSErrCode  ACAPI_3D_GetComponent (
        API_Component3D*     component
    );

 

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.

 

Return Values

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.

For other common API errors see the API Errors document.

 

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_3D_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_3D_GetComponent (&comp3D);
    if (err == NoError) {
        /* explode the body into pgon, vert etc... */
    }
    if (err == APIERR_DELETED)
        err = NoError;
}

 

Requirements

Version: API 1.3 or later
Header: ACAPinc.h

 

See Also

API_Component3D, API_BodyType, API_3DTypeID,
ACAPI_3D_GetNum,
3D Manager, API Functions