Archicad 27 C++ API
Loading...
Searching...
No Matches
Functions
Bodies

This function family gives support to create or modify the body of a morph element. More...

Functions

GSErrCode __ACENV_CALL ACAPI_Body_Create (const Modeler::MeshBody *body, const API_OverriddenAttribute *bodyMaterialMapTable, void **bodyData)
 Initializes a new body data object for editing.
 
GSErrCode __ACENV_CALL ACAPI_Body_Finish (void *bodyData, Modeler::MeshBody **body, API_OverriddenAttribute **bodyMaterialMapTable)
 Converts the body data object to a format, that can be passed to an API_ElementMemo structure.
 
GSErrCode __ACENV_CALL ACAPI_Body_Dispose (void **bodyData)
 Disposes the body data object.
 
GSErrCode __ACENV_CALL ACAPI_Body_AddVertex (void *bodyData, const API_Coord3D &coord, UInt32 &index)
 Adds a vertex to the body data object.
 
GSErrCode __ACENV_CALL ACAPI_Body_AddEdge (void *bodyData, const UInt32 vertex1, const UInt32 vertex2, Int32 &index)
 Adds a vertex to the body data object.
 
GSErrCode __ACENV_CALL ACAPI_Body_AddPolyNormal (void *bodyData, const API_Vector3D &normal, Int32 &index)
 Adds a polygon normal vector to the body data object.
 
GSErrCode __ACENV_CALL ACAPI_Body_AddPolygon (void *bodyData, const GS::Array< Int32 > &edges, const Int32 polyNormal, const API_OverriddenAttribute &material, UInt32 &index)
 Adds a polygon to the body data object.
 

Detailed Description

This function family gives support to create or modify the body of a morph element.

Function Documentation

◆ ACAPI_Body_AddEdge()

GSErrCode __ACENV_CALL ACAPI_Body_AddEdge ( void *  bodyData,
const UInt32  vertex1,
const UInt32  vertex2,
Int32 &  index 
)

Adds a vertex to the body data object.

Parameters
bodyData[in] The body data object to add the edge to.
vertex1[in] Index of the first vertex of the edge.
vertex2[in] Index of the second vertex of the edge.
index[out] The index of the created edge, can be used later to create polygons.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed parameter is nullptr for bodyData. The index is out of range for vertex1, vertex2.
Remarks
This function is used to add an edge to a body data object. The vertex1 and vertex2 parameters shall be valid vertex indices provided by the ACAPI_Body_AddVertex function. The edge can be used with at most 2 polygons, and in that case it has to be passed with opposite directions. The returned index can be used to create polygons with the ACAPI_Body_AddPolygon function.
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);
ACAPI_Body_Create
GSErrCode __ACENV_CALL ACAPI_Body_Create(const Modeler::MeshBody *body, const API_OverriddenAttribute *bodyMaterialMapTable, void **bodyData)
Initializes a new body data object for editing.
ACAPI_Body_AddPolyNormal
GSErrCode __ACENV_CALL ACAPI_Body_AddPolyNormal(void *bodyData, const API_Vector3D &normal, Int32 &index)
Adds a polygon normal vector to the body data object.
ACAPI_Body_Dispose
GSErrCode __ACENV_CALL ACAPI_Body_Dispose(void **bodyData)
Disposes the body data object.
ACAPI_Body_AddEdge
GSErrCode __ACENV_CALL ACAPI_Body_AddEdge(void *bodyData, const UInt32 vertex1, const UInt32 vertex2, Int32 &index)
Adds a vertex to the body data object.
ACAPI_Body_AddPolygon
GSErrCode __ACENV_CALL ACAPI_Body_AddPolygon(void *bodyData, const GS::Array< Int32 > &edges, const Int32 polyNormal, const API_OverriddenAttribute &material, UInt32 &index)
Adds a polygon to the body data object.
ACAPI_Body_AddVertex
GSErrCode __ACENV_CALL ACAPI_Body_AddVertex(void *bodyData, const API_Coord3D &coord, UInt32 &index)
Adds a vertex to the body data object.
ACAPI_Body_Finish
GSErrCode __ACENV_CALL ACAPI_Body_Finish(void *bodyData, Modeler::MeshBody **body, API_OverriddenAttribute **bodyMaterialMapTable)
Converts the body data object to a format, that can be passed to an API_ElementMemo structure.
ACAPI_CallUndoableCommand
GSErrCode __ACENV_CALL ACAPI_CallUndoableCommand(const GS::UniString &undoString, const std::function< GSErrCode()> &command)
Performs an undoable operation.
ACAPI_Element_Create
GSErrCode __ACENV_CALL ACAPI_Element_Create(API_Element *element, API_ElementMemo *memo)
Places a new element into current database.
ACAPI_Element_GetDefaults
GSErrCode __ACENV_CALL ACAPI_Element_GetDefaults(API_Element *element, API_ElementMemo *memo)
Retrieves the actual default settings for the element of type.
ACAPI_DisposeElemMemoHdls
GSErrCode __ACENV_CALL ACAPI_DisposeElemMemoHdls(API_ElementMemo *memo)
Frees the memory occupied by all of the allocated memo handles.
API_Coord3D
Real (Cartesian) 3D coordinates of a three-dimensional space.
Definition: APIdefs_Base.h:100
API_Coord3D::x
double x
The x factor.
Definition: APIdefs_Base.h:104
API_Coord3D::z
double z
The z factor.
Definition: APIdefs_Base.h:114
API_Coord3D::y
double y
The y factor.
Definition: APIdefs_Base.h:109
API_Elem_Head::type
API_ElemType type
The type of the element.
Definition: APIdefs_Elements.h:367
API_ElementMemo
Describes the variable length additional data of elements.
Definition: APIdefs_Elements.h:13856
API_ElementMemo::morphBody
Modeler::MeshBody * morphBody
Morph element.
Definition: APIdefs_Elements.h:14275
API_ElementMemo::morphMaterialMapTable
API_OverriddenAttribute * morphMaterialMapTable
Morph element.
Definition: APIdefs_Elements.h:14280
API_Element
A union collecting all known element types.
Definition: APIdefs_Elements.h:13390
API_Element::header
API_Elem_Head header
General element header.
Definition: APIdefs_Elements.h:13395

◆ ACAPI_Body_AddPolygon()

GSErrCode __ACENV_CALL ACAPI_Body_AddPolygon ( void *  bodyData,
const GS::Array< Int32 > &  edges,
const Int32  polyNormal,
const API_OverriddenAttribute &  material,
UInt32 &  index 
)

Adds a polygon to the body data object.

Parameters
bodyData[in] The body data object to add the polygon to.
edges[in] List of the edges of the polygon.
polyNormal[in] Signed index of the normal vector.
material[in] Material override structure of the polygon.
index[out] The index of the created polygon.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed bodyData parameter is nullptr. There are less than 3 edges passed.
Remarks
This function is used to add a polygon to a body data object. The edges list contains edge indices returned by the ACAPI_Body_AddEdge function. The list shall look like the following:
  • First pass the indices of contour edges as they sorruond the polygon counterclockwise. (An edge can be used backwards with a negative index)
  • For each hole pass a 0, then the indices of hole contour edges clockwise. polyNormal is the index of a normal vector returned by the ACAPI_Body_AddPolyNormal function.
  • A negative value indicates, that the vector is used in the opposite direction. (So a cube can be created making 3 normal vectors instead of 6)
  • If you pass 0, the normal vector is calculated automatically, but doing so, the same vector may be created multiple times, as duplicates are not detected. (A plane containing many polygons generates the same normal for each polygon)
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);

◆ ACAPI_Body_AddPolyNormal()

GSErrCode __ACENV_CALL ACAPI_Body_AddPolyNormal ( void *  bodyData,
const API_Vector3D &  normal,
Int32 &  index 
)

Adds a polygon normal vector to the body data object.

Parameters
bodyData[in] The body data object to add the normal vector to.
normal[in] The normal vector to add.
index[out] The index of the created normal vector, can be used later to create polygons.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed bodyData parameter is nullptr. The normal vector length is 0;
Remarks
This function is used to add a normal vector to a body data object. A normal vector can be used for multiple polygons and can be passed with positive and negative direction too. The normal vector is perpendicular to the polygon plane and points the direction you want to see the polygon from. (In case of a complete body, the normal vectors point ot of the body) The returned index can be used to create polygons with the ACAPI_Body_AddPolygon function.
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);

◆ ACAPI_Body_AddVertex()

GSErrCode __ACENV_CALL ACAPI_Body_AddVertex ( void *  bodyData,
const API_Coord3D &  coord,
UInt32 &  index 
)

Adds a vertex to the body data object.

Parameters
bodyData[in] The body data object to add the vertex to.
coord[in] Position of the vertex to add.
index[out] The index of the created vertex, can be used later to define edges.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed bodyData parameter is nullptr.
Remarks
This function is used to add a vertex to a body data object. The returned index can be used to create edges with the ACAPI_Body_AddEdge function.
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);

◆ ACAPI_Body_Create()

GSErrCode __ACENV_CALL ACAPI_Body_Create ( const Modeler::MeshBody *  body,
const API_OverriddenAttribute *  bodyMaterialMapTable,
void **  bodyData 
)

Initializes a new body data object for editing.

Parameters
body[in] The body object to start the editing with. nullptr can be passed to create a new body.
bodyMaterialMapTable[in] The initial material override structure list of the polygons of the body. nullptr can be passed in case of a new body.
bodyData[out] The body data object, that shall be passed to further editing functions.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed bodyData parameter is nullptr.
Remarks
This function is used to create a body data object for further editing. Input parameters can be nullptr, but can be passed from the API_ElementMemo of a morph element.
Example
API_ElementMemo memo = {};
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create (nullptr, nullptr, &bodyData);
/* add vertices, edges and polygons here... */
// insert the resulting body, pens and materials to the memo
err = ACAPI_Body_Finish (bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// dispose the body data object
err = ACAPI_Body_Dispose (&bodyData);
/* create the new morph object from the memo... */

◆ ACAPI_Body_Dispose()

GSErrCode __ACENV_CALL ACAPI_Body_Dispose ( void **  bodyData)

Disposes the body data object.

Parameters
bodyData[in] The body data object to dispose.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed parameter in bodyData is nullptr.
Remarks
This function is used to dispose a body data object.
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);

◆ ACAPI_Body_Finish()

GSErrCode __ACENV_CALL ACAPI_Body_Finish ( void *  bodyData,
Modeler::MeshBody **  body,
API_OverriddenAttribute **  bodyMaterialMapTable 
)

Converts the body data object to a format, that can be passed to an API_ElementMemo structure.

Parameters
bodyData[in] The body data object to convert.
body[out] The body object to put the resulting body to.
bodyMaterialMapTable[out] The material override structure list of the polygons of the body.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - The passed bodyData parameter is nullptr.
Remarks
This function is used to convert a body data object to data, that can be passed to an API_ElementMemo structure and create a morph element.
Example
// setup a new morph element
API_Element element;
BNZeroMemory (&element, sizeof (API_Element));
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);
// setup a new memo
API_ElementMemo memo;
BNZeroMemory (&memo, sizeof (API_ElementMemo));
// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);
API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
// add vertices of square countour
coord.x = -2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[0]);
coord.x = 2.0; coord.y = -2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[1]);
coord.x = 2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[2]);
coord.x = -2.0; coord.y = 2.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[3]);
// add vertices of square hole
coord.x = -1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[4]);
coord.x = 1.0; coord.y = -1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[5]);
coord.x = 1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[6]);
coord.x = -1.0; coord.y = 1.0; coord.z = 0.0;
err = ACAPI_Body_AddVertex(bodyData, coord, vertices[7]);
// add edges of square countour
err = ACAPI_Body_AddEdge(bodyData, vertices[0], vertices[1], edges[0]);
err = ACAPI_Body_AddEdge(bodyData, vertices[1], vertices[2], edges[1]);
err = ACAPI_Body_AddEdge(bodyData, vertices[2], vertices[3], edges[2]);
err = ACAPI_Body_AddEdge(bodyData, vertices[3], vertices[0], edges[3]);
// add edges of square hole
err = ACAPI_Body_AddEdge(bodyData, vertices[4], vertices[5], edges[4]);
err = ACAPI_Body_AddEdge(bodyData, vertices[5], vertices[6], edges[5]);
err = ACAPI_Body_AddEdge(bodyData, vertices[6], vertices[7], edges[6]);
err = ACAPI_Body_AddEdge(bodyData, vertices[7], vertices[4], edges[7]);
// add normal vector
API_Vector3D normal;
normal.x = normal.y = 0.0; normal.z = 1.0;
err = ACAPI_Body_AddPolyNormal(bodyData, normal, polyNormals[0]);
// add square polygon with square hole (with surface material override enabled)
GS::Array<Int32>& polyEdges[] = {
edges[0],
edges[1],
edges[2],
edges[3],
0,
-edges[7],
-edges[6],
-edges[5],
-edges[4]
};
API_OverriddenAttribute material;
material.attributeIndex = 1;
material.overridden = true;
err = ACAPI_Body_AddPolygon(bodyData, polyEdges, polyNormals[0], material, polygons[0]);
// insert the resulting body and materials to the memo
err = ACAPI_Body_Finish(bodyData, &memo.morphBody, &memo.morphMaterialMapTable);
// create the morph element
err = ACAPI_CallUndoableCommand("Create morph", [&]() -> GSErrCode {
return ACAPI_Element_Create (&element, &memo);
});
// dispose the body data object & the memo
err = ACAPI_Body_Dispose(&bodyData);
err = ACAPI_DisposeElemMemoHdls (&memo);