ACAPI_Body_AddPolygon |

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

Parameters

Return Values

Remarks

Example

Requirements

See Also