Adds a polygon to the body data object.
GSErrCode ACAPI_Body_AddPolygon (
void* bodyData,
const GS::Array<Int32>& edges,
const Int32 polyNormal,
const API_OverriddenAttribute& material,
UInt32& index
);
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.
Return Values
NoError
- The function has completed with success.
APIERR_BADPARS
- The passed parameter is
nullptr
; bodyData
- There are less than 3 edges passed;
edges
For other common API errors see the
API Errors document.
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);
Requirements
- Version: API 16 or later
- Header: ACAPinc.h
See Also
ACAPI_Body_AddVertex,
ACAPI_Body_AddEdge,
ACAPI_Body_AddPolyNormal,
ACAPI_Body_Create,
ACAPI_Body_Finish,
ACAPI_Body_Dispose,
Body Manager,
API Functions