Polygons

Functions to change the shape of a polygon. These polygons are always provided through API_ElementMemo. More...

Classes
struct	API_RegularizedPoly
	Structure for regularizing polygon or polyline. More...

Enumerations
enum	API_SurfaceTypeID {   APISurfaceType_NotSpecified = 0 , APISurfaceType_BeamFirst = 0x1000 , APISurfaceType_BeamRight = 0x1000 , APISurfaceType_BeamLeft ,   APISurfaceType_BeamSide , APISurfaceType_BeamTop , APISurfaceType_BeamBottom , APISurfaceType_BeamCut ,   APISurfaceType_BeamLast = APISurfaceType_BeamCut , APISurfaceType_ColumnFisrt = 0x2000 , APISurfaceType_ColumnTop = 0x2000 , APISurfaceType_ColumnBottom ,   APISurfaceType_ColumnCoreSide , APISurfaceType_ColumnVeneerSide , APISurfaceType_ColumnCut , APISurfaceType_ColumnLast = APISurfaceType_ColumnCut ,   APISurfaceType_SlabFirst = 0x3000 , APISurfaceType_SlabTop = 0x3000 , APISurfaceType_SlabBottom , APISurfaceType_SlabSide ,   APISurfaceType_SlabCut , APISurfaceType_SlabLast = APISurfaceType_SlabCut , APISurfaceType_WallFirst = 0x4000 , APISurfaceType_WallRefSide = 0x4000 ,   APISurfaceType_WallOppSide , APISurfaceType_WallSide , APISurfaceType_WallCut , APISurfaceType_WallLast = APISurfaceType_WallCut ,   APISurfaceType_ShellReferenceFirst = 0x5000 , APISurfaceType_ShellReferenceSide = 0x5000 , APISurfaceType_ShellOppositeSide , APISurfaceType_ShellRidge ,   APISurfaceType_ShellValley , APISurfaceType_ShellGable , APISurfaceType_ShellHip , APISurfaceType_ShellEaves ,   APISurfaceType_ShellPeak , APISurfaceType_ShellSideWall , APISurfaceType_ShellEndWall , APISurfaceType_ShellRTDome ,   APISurfaceType_ShellRTHollow , APISurfaceType_ShellSide , APISurfaceType_ShellCut , APISurfaceType_ShellInnerReferenceSide ,   APISurfaceType_ShellInnerOppositeSide , APISurfaceType_ShellLast = APISurfaceType_ShellInnerOppositeSide , APISurfaceType_PlaneRoofFirst = 0x6000 , APISurfaceType_PlaneRoofTop = 0x6000 ,   APISurfaceType_PlaneRoofBottom , APISurfaceType_PlaneRoofRidge , APISurfaceType_PlaneRoofValley , APISurfaceType_PlaneRoofGable ,   APISurfaceType_PlaneRoofHip , APISurfaceType_PlaneRoofEaves , APISurfaceType_PlaneRoofPeak , APISurfaceType_PlaneRoofSideWall ,   APISurfaceType_PlaneRoofEndWall , APISurfaceType_PlaneRoofRTDome , APISurfaceType_PlaneRoofRTHollow , APISurfaceType_PlaneRoofSide ,   APISurfaceType_PlaneRoofCut , APISurfaceType_PlaneRoofLast = APISurfaceType_PlaneRoofCut , APISurfaceType_PolyRoofFirst = 0x7000 , APISurfaceType_PolyRoofTop = 0x7000 ,   APISurfaceType_PolyRoofBottom , APISurfaceType_PolyRoofRidge , APISurfaceType_PolyRoofValley , APISurfaceType_PolyRoofGable ,   APISurfaceType_PolyRoofHip , APISurfaceType_PolyRoofEaves , APISurfaceType_PolyRoofPeak , APISurfaceType_PolyRoofSideWall ,   APISurfaceType_PolyRoofEndWall , APISurfaceType_PolyRoofRTDome , APISurfaceType_PolyRoofRTHollow , APISurfaceType_PolyRoofUndefined ,   APISurfaceType_PolyRoofInner , APISurfaceType_PolyRoofCut , APISurfaceType_PolyRoofLast = APISurfaceType_PolyRoofCut }
	Possible types of a surface.

Functions
GSErrCode	ACAPI_Polygon_InsertPolyNode (API_ElementMemo *elementMemo, Int32 *nodeIndex, API_Coord *coord)
	Inserts a node into a polygon.
GSErrCode	ACAPI_Polygon_DeletePolyNode (API_ElementMemo *memo, Int32 *inIndex)
	Deletes a node from a polygon.
GSErrCode	ACAPI_Polygon_InsertSubPoly (API_ElementMemo *memo, API_ElementMemo *insMemo)
	Inserts a whole subpolygon (hole) into a polygon.
GSErrCode	ACAPI_Polygon_DeleteSubPoly (API_ElementMemo *elementMemo, Int32 *subPolyIndex)
	Deletes a whole subpolygon (hole) from a polygon.
GSErrCode	ACAPI_Polygon_RegularizePolygon (const API_RegularizedPoly *polygon, Int32 *nResult, API_RegularizedPoly ***regularizedPolygons)
	Regularizes a polygon and returns the regularized polygons.
GSErrCode	ACAPI_Polygon_RegularizePolyline (const API_RegularizedPoly *polyline, API_RegularizedPoly *regularizedPolyline)
	Regularizes a polyline and returns the regularized polyline.
GSErrCode	ACAPI_Polygon_DisposeRegularizedPoly (API_RegularizedPoly *regularizedPoly)
	Deallocates handles in an API_RegularizedPoly struct.
GSErrCode	ACAPI_Polygon_TriangulatePoly (API_ElementMemo *memo, API_Coord ***coords)
	Decomposes a polygon into triangles.
GSErrCode	ACAPI_Polygon_PolygonId2SurfaceType (const API_Element *elem=nullptr, const Int32 *polygonId=nullptr, API_SurfaceTypeID *surfaceType=nullptr)
	Converts a picture into another image format.

Detailed Description

Functions to change the shape of a polygon. These polygons are always provided through API_ElementMemo.

Function Documentation

ACAPI_Polygon_DeletePolyNode()

GSErrCode ACAPI_Polygon_DeletePolyNode	(	API_ElementMemo *	memo,
		Int32 *	inIndex
	)

Deletes a node from a polygon.

Parameters

memo	[in/out] The polygon data.
inIndex	[in] node index (subindex of the element) to delete

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or invalid nodeIndex passed or memo is not initialized
• APIERR_MEMFULL - low memory condition
• APIERR_IRREGULARPOLY - Input polygon or polyline is irregular.

Remarks

This function is used to delete a node from a polygon passed in an API_ElementMemo structure. Refer to the API_Polygon structure to have more details on the polygon data structure. The coords, pends, parcs and vertexIDs handles in the API_ElementMemo structure must be initialized. Note that other memo handles are not touched. In the case the polygon belongs to a roof with side angles initialized, it must be aligned manually.

Example

/*----------------------------------------------------------**
** Insert a new node into the clicked poly edge             **
**----------------------------------------------------------*/
static void    Do_Poly_DeleteNode (void)
 
{   API_ElementMemo      memo;
    API_Neig             neig;
    API_ElemTypeID       idElem;
    Int32                nodeInd;
    Int32                nSubPolys, i, begInd, endInd;
    GSErrCode            err;
 
    if (!ClickAnElem ("Click a node to delete", API_ZombieElemID, &neig, nullptr, nullptr, nullptr)) {
        GiveMessage ("Please click a polygon node", true);
        return;
    }
 
    if (neig.neigID != APINeig_Ceil && neig.neigID != APINeig_Roof) {
        GiveMessage ("Please click a ceil or roof node", true);
        return;
    }
 
    idElem = Neig_To_ElemID (neig.neigID);
    err = ACAPI_Element_GetMemo (neig.guid, &memo);
    if (err) {
        GiveMessage_Err ("ACAPI_Element_GetMemo", err);
        return;
    }
 
    nodeInd = neig.inIndex;
    err = ACAPI_Goodies (APIAny_DeletePolyNodeID, &memo, &nodeInd);
    if (!err) {
        switch (idElem) {
            case API_SlabID:
                /* nothing to do */
                break;
            case API_RoofID:
                if (memo.roofSides != nullptr && *memo.roofSides != nullptr) {
                    /* delete roofSide rec; [nodeInd] */
                }
 
            default:
                return; /* never got there */
        }
        err = ACAPI_Element_ChangeMemo (neig.guid, APIMemoMask_Polygon, &memo);
        if (err)
            GiveMessage_Err ("ACAPI_Element_ChangeMemo", err);
    } else
        GiveMessage_Err ("APIAny_DeletePolyNodeID", err);
 
    ACAPI_DisposeElemMemoHdls (&memo);
 
    return;
}

ACAPI_Polygon_DeleteSubPoly()

GSErrCode ACAPI_Polygon_DeleteSubPoly	(	API_ElementMemo *	elementMemo,
		Int32 *	subPolyIndex
	)

Deletes a whole subpolygon (hole) from a polygon.

Parameters

elementMemo	[in/out] The polygon data.
subPolyIndex	[in] subpolygon index to delete

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or invalid subPolyIndex passed
• APIERR_MEMFULL - low memory condition
• APIERR_IRREGULARPOLY - Input polygon is irregular.

Remarks

This function is used to delete a whole subpolygon (hole) from a polygon passed in an API_ElementMemo structure. Refer to the API_Polygon structure to have more details on the polygon data structure. The coords, pends, parcs and vertexIDs handles in the API_ElementMemo structure must be initialized. Note that other memo handles are not touched. In the case the polygon belongs to a roof with side angles initialized, it must be aligned manually.

Example

GSErrCode DeleteSubPoly (const API_Guid& guid)
{
    API_ElementMemo   memo;
    Int32             lastSubPoly;
    GSErrCode         err;
 
    err = ACAPI_Element_GetMemo (guid, &memo);
    if (err) {
        lastSubPoly = BMGetHandleSize ((GSHandle) memo.pends) / sizeof (Int32) - 1;
        if (lastSubPoly > 1)
            err = ACAPI_Goodies (APIAny_DeleteSubPolyID, &memo, &lastSubPoly);
    }
    return err;
}

ACAPI_Polygon_DisposeRegularizedPoly()

GSErrCode ACAPI_Polygon_DisposeRegularizedPoly

(

API_RegularizedPoly *

regularizedPoly

)

Deallocates handles in an API_RegularizedPoly struct.

Parameters

regularizedPoly

[in] The polygon or polyline data to dipose.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or memo or insMemo is not initialized
• APIERR_MEMFULL - low memory condition

ACAPI_Polygon_InsertPolyNode()

GSErrCode ACAPI_Polygon_InsertPolyNode	(	API_ElementMemo *	elementMemo,
		Int32 *	nodeIndex,
		API_Coord *	coord
	)

Inserts a node into a polygon.

Parameters

elementMemo	[in/out] The polygon data.
nodeIndex	[in] node index (subindex of the element) to insert a new node after
coord	[in] The coordinate of the new node.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or invalid nodeIndex passed or memo is not initialized
• APIERR_MEMFULL - low memory condition
• APIERR_IRREGULARPOLY - Input polygon or polyline is irregular.

Remarks

This function is used to insert a new node into a polygon passed in an API_ElementMemo structure. This function inserts the given coordinate into the right place. Refer to the API_Polygon structure to have more details on the polygon data structure. The coords, pends, parcs and vertexIDs handles in the API_ElementMemo structure must be initialized. Note that other memo handles are not touched. In the case the polygon belongs to a roof with side angles initialized, it must be aligned manually.

Example

/*----------------------------------------------------------**
** Insert a new node into the clicked poly edge             **
**----------------------------------------------------------*/
static void             Do_Poly_InsertNode (void)
 
{   API_ElementMemo     memo;
    API_Neig            neig;
    API_ElemTypeID      idElem;
    API_Coord3D         begC;
    API_EdgeTrim        edgeTrim;
    Int32               nodeInd;
    GSErrCode           err;
 
    if (!ClickAnElem ("Click an edge to insert new node", API_ZombieElemID, &neig, nullptr, nullptr, &begC)) {
        GiveMessage ("Please click a polygon node", true);
        return;
    }
 
    if (neig.neigID != APINeig_CeilOn && neig.neigID != APINeig_RoofOn) {
        GiveMessage ("Please click a ceil or roof edge", true);
        return;
    }
 
    idElem = Neig_To_ElemID (neig.neigID);
    err = ACAPI_Element_GetMemo (neig.guid, &memo);
    if (err) {
        GiveMessage_Err ("ACAPI_Element_GetMemo", err);
        return;
    }
 
    nodeInd = neig.inIndex + 1;
    err = ACAPI_Goodies (APIAny_InsertPolyNodeID, &memo, &nodeInd, (API_Coord*)(&begC));
    if (!err) {
        switch (idElem) {
            case API_SlabID:
                /* nothing to do */
                break;
            case API_RoofID:
                if (memo.edgeTrims != nullptr && *memo.edgeTrims != nullptr) {
                    /* insert edgeTrim rec; [neig.inIndex] */
                }
                break;
            default:
                return; /* never got there */
        }
        err = ACAPI_Element_ChangeMemo (neig.guid, APIMemoMask_Polygon, &memo);
        if (err)
            GiveMessage_Err ("ACAPI_Element_ChangeMemo", err);
    } else
        GiveMessage_Err ("APIAny_InsertPolyNodeID", err);
 
    ACAPI_DisposeElemMemoHdls (&memo);
 
    return;
}

ACAPI_Polygon_InsertSubPoly()

GSErrCode ACAPI_Polygon_InsertSubPoly	(	API_ElementMemo *	memo,
		API_ElementMemo *	insMemo
	)

Inserts a whole subpolygon (hole) into a polygon.

Parameters

memo	[in/out] The polygon data.
insMemo	[in] Data of the new subpolygon.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or memo or insMemo is not initialized
• APIERR_MEMFULL - low memory condition
• APIERR_IRREGULARPOLY - Input polygon is irregular.

Remarks

This function is used to insert a new subpolygon (hole) into a polygon passed in an API_ElementMemo structure. The shape of the new hole should be passed in the insMemo parameter. Refer to the API_Polygon structure to have more details on the polygon data structure. The coords, pends, parcs and vertexIDs handles in the API_ElementMemo structure must be initialized in the case of the memo parameter. The vertexID and pends handles are ignored in the insMemo parameter. The function places the new hole to the and of the contour list. Note that other memo handles are not touched. In the case the polygon belongs to a roof with side angles initialized, it must be aligned manually.

ACAPI_Polygon_PolygonId2SurfaceType()

GSErrCode ACAPI_Polygon_PolygonId2SurfaceType	(	const API_Element *	elem = nullptr,
		const Int32 *	polygonId = nullptr,
		API_SurfaceTypeID *	surfaceType = nullptr
	)

Converts a picture into another image format.

Parameters

elem	[in] Parameter elem for element type identification. Give elem.header.guid or elem.header.typeId. For roofs specify elem.roof.roofClass also.
polygonId	[in] Parameter polygonId.
surfaceType	[out] Parameter surfaceType.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - parameters are nullptr or invalid
• APIERR_BADID - elemGuid does not refer to a valid element in the database.

Remarks

This function is used to convert a polygonId returned by ModelerAPI::Polygon::GetPolygonId to a API_SurfaceTypeID.

ACAPI_Polygon_RegularizePolygon()

GSErrCode ACAPI_Polygon_RegularizePolygon	(	const API_RegularizedPoly *	polygon,
		Int32 *	nResult,
		API_RegularizedPoly ***	regularizedPolygons
	)

Regularizes a polygon and returns the regularized polygons.

Parameters

polygon	[in] The polygon to regularize.
nResult	[out] The number of resulting regularized polygons.
regularizedPolygons	[out] The result of regularization.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or polygon or regularizedPolygons is not initialized
• APIERR_MEMFULL - low memory condition

Remarks

This function is used to regularize a polygon. The result may be 0, 1 or more regularized polygons. Refer to the API_RegularizedPoly structure to have more details on the polygon data structure.

ACAPI_Polygon_RegularizePolyline()

GSErrCode ACAPI_Polygon_RegularizePolyline	(	const API_RegularizedPoly *	polyline,
		API_RegularizedPoly *	regularizedPolyline
	)

Regularizes a polyline and returns the regularized polyline.

Parameters

polyline	[in] The polyline to regularize.
regularizedPolyline	[out] The result of regularization.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr or polyline or regularizedPolyline is not initialized
• APIERR_MEMFULL - low memory condition

Remarks

This function is used to regularize a polyline. A polyline is considered irregular when two or more consecutive vertices in the coord array are the same. The result may be an empty polyline. Refer to the API_RegularizedPoly structure to have more details on the polyline data structure.

ACAPI_Polygon_TriangulatePoly()

GSErrCode ACAPI_Polygon_TriangulatePoly	(	API_ElementMemo *	memo,
		API_Coord ***	coords
	)

Decomposes a polygon into triangles.

Parameters

memo	[in] Parameters of an polygon. The coordinates of the polygon and the subpolygon endpoints must be coords handle and pends handle in the memo.
coords	[out] Coordinates of the triangles

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr
• APIERR_REFUSEDPAR - Arc in the polygon
• APIERR_MEMFULL - Not enough memory to complete the operation
• APIERR_IRREGULARPOLY - Input polygon is irregular.

Remarks

This function is used to decompose a polygon into triangles. The coords handle will be allocated by the server application and filled with coordinates. The number of generated triangles should be determined based on the returned handle size. The function accept only polygons which has no arc segments. Do not forget to dispose the coords handle if it is not needed any more.

Example

#include  "GSBase.h"      /* BMhKill */
 
GSErrCode TriangulateSlab (const API_Guid& slabGuid)
{
    API_Element       element;
    API_ElementMemo   memo;
    API_Coord         **coords;
    Int32             nTriangles;
    GSErrCode         err;
 
    BNZeroMemory (&memo, sizeof (API_ElementMemo));
    BNZeroMemory (&element, sizeof (API_Element));
    element.header.guid = slabGuid;
 
    err = ACAPI_Element_Get (&element);
    if (!err) {
        if (element.slab.poly.nArcs > 0)
            return APIERR_REFUSEDPAR;
            err = ACAPI_Element_GetMemo (element.header.guid, &memo);
            if (!err) {
            err = ACAPI_Goodies (APIAny_TriangulatePolyID, &memo, &coords);
            if (!err) {
                nTriangles = BMGetHandleSize ((GSHandle) coords) / (3 * sizeof (API_Coord));
                /* ... */
                BMKillHandle ((GSHandle *) &coords);
            }
            ACAPI_DisposeElemMemoHdls (&memo);
        }
    }
 
    return err;
}