Drawing Primitives

Functions providing access to the geometrical primitive-level drawing data of elements. More...

Classes
struct	API_ShapePrimsParams
	Shape primitive parameters. More...
struct	API_PrimArc
	A primitive arc. More...
struct	API_PrimText
	A primitive text. More...
struct	API_PrimPoly
	A primitive polygon. More...
struct	API_PrimPict
	A picture inside a placed drawing. More...
union	API_PrimElement
	A union containing all drawing primitives used with ACAPI_DrawingPrimitive_ShapePrims and ACAPI_LibraryPart_ShapePrims. More...

Typedefs
typedef GSErrCode	ShapePrimsProc(const API_PrimElement *primElem, const void *par1, const void *par2, const void *par3)
	Primitive drawing function for elements and library parts.

Functions
GSErrCode	ACAPI_DrawingPrimitive_DrawStoryControl (API_DatabaseUnId *databaseUnId, ShapePrimsProc *shapePrimsProc)
	Draws the primitives of the Story Level Control elements on the given Section/Elevation database.
GSErrCode	ACAPI_DrawingPrimitive_ShapePrims (const API_Elem_Head &elemHead, ShapePrimsProc *shapePrimsProc)
	Virtually draws the shape of an element.
GSErrCode	ACAPI_DrawingPrimitive_ShapePrimsExt (const API_Elem_Head &elemHead, ShapePrimsProc *shapePrimsProc, API_ShapePrimsParams *shapePrimsParams)
	Virtually draws the shape of an element.

Detailed Description

Functions providing access to the geometrical primitive-level drawing data of elements.

Typedef Documentation

ShapePrimsProc

typedef GSErrCode ShapePrimsProc(const API_PrimElement *primElem, const void *par1, const void *par2, const void *par3)

Primitive drawing function for elements and library parts.

Parameters

primElem	The primitive element to draw; can also contain control codes.
par1	First parameter for drawing the element (can be nullptr).
par2	Second parameter for drawing the element (can be nullptr).
par3	Third parameter for drawing the element (can be nullptr).

Returns

• NoError - The element was drawn successfully.
• APINOTIFY_NODATA - Supress hierarchical decomposition.
• APINOTIFY_OWN_MEMORY_HANDLER - Tells the API that your add-on took over the ownership of the passed coords, pends and parcs array. For lines, polylines and polygons only.
• APIERR_GENERAL - Any user-defined error can be returned.

Remarks

This function is used to draw the primitive elements. As such, it plugs into the server application's drawing routines. It can also be used to save the contents of a plan into an external file.

API_PrimTypeID	par1	par2	par3
API_PrimPointID	nullptr	nullptr	nullptr
API_PrimLineID	nullptr	nullptr	nullptr
API_PrimArcID	nullptr	nullptr	nullptr
API_PrimTextID	nullptr	(unsigned short*) pointer to the text (UniCode string) or nullptr	nullptr
API_PrimPLineID	(API_Coord*) coordinates	nullptr	(API_PolyArc*) arcs
API_PrimTriID	nullptr	nullptr	nullptr
API_PrimPolyID	(API_Coord*) coordinates	(Int32*) subpolygon endpoints	(API_PolyArc*) arcs
API_PrimCtrl_BegID	nullptr	nullptr	nullptr
API_PrimCtrl_HatchBorderBegID	(API_PrimHatchBorder*) border	nullptr	nullptr
API_PrimCtrl_HatchBorderEndID	nullptr	nullptr	nullptr
API_PrimCtrl_HatchLinesBegID	nullptr	nullptr	nullptr
API_PrimCtrl_HatchLinesEndID	nullptr	nullptr	nullptr
API_PrimCtrl_HoledimLinesBegID	nullptr	nullptr	nullptr
API_PrimCtrl_HoledimLinesEndID	nullptr	nullptr	nullptr
API_PrimCtrl_ArrowBegID	nullptr	nullptr	nullptr
API_PrimCtrl_ArrowEndID	nullptr	nullptr	nullptr
API_PrimCtrl_ElementRefID	(API_PrimElemRef*) reference	nullptr	nullptr
API_PrimCtrl_EndID	nullptr	nullptr	nullptr
API_PrimCtrl_PlacedBorderBegID	nullptr	nullptr	nullptr
API_PrimCtrl_PlacedBorderEndID	nullptr	nullptr	nullptr
API_PrimCtrl_TextBegID	nullptr	nullptr	nullptr
API_PrimCtrl_TextEndID	nullptr	nullptr	nullptr
API_PrimCtrl_BackgroundFillBegID	nullptr	nullptr	nullptr
API_PrimCtrl_BackgroundFillEndID	nullptr	nullptr	nullptr
API_PrimCtrl_FrameBegID	nullptr	nullptr	nullptr
API_PrimCtrl_FrameEndID	nullptr	nullptr	nullptr

Function Documentation

ACAPI_DrawingPrimitive_DrawStoryControl()

GSErrCode ACAPI_DrawingPrimitive_DrawStoryControl	(	API_DatabaseUnId *	databaseUnId,
		ShapePrimsProc *	shapePrimsProc )

Draws the primitives of the Story Level Control elements on the given Section/Elevation database.

Parameters

databaseUnId	[in] The unique ID of the database
shapePrimsProc	[in] The function to be called to process the element primitives

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed dbUnID or the shapePrimsProc parameter nullptr,

Remarks

Use this function to export the primitives of the Story Level Control of a Section/Elevation database. Similarly to ACAPI_DrawingPrimitive_ShapePrims and ACAPI_LibraryPart_ShapePrims it calls back the passed handler function with each drawing primitive part of the Story Level Handler. Since the Story Level Handler is not a separate element type in API, it is referenced by the database unique ID of the Section/Elevation the Story Levels are displayed on. The settings of the Story Level lines and Markers can be accessed via the API_CutPlaneType structure. Note that the primitives are sent only when the value of API_StoryHandleAppearance is APICutPl_SHAAll in the settings of the Cut Plane element.

Example

API_DatabaseInfo databaseInfo {};
 
GSErrCode err = ACAPI_Database_GetCurrentDatabase (&databaseInfo);
 
if (err == NoError && databaseInfo.typeID == APIWind_SectionID)
    ACAPI_DrawingPrimitive_DrawStoryControl (&(databaseInfo.databaseUnId), MyDrawShapePrimsProc);

ACAPI_DrawingPrimitive_ShapePrims()

GSErrCode ACAPI_DrawingPrimitive_ShapePrims	(	const API_Elem_Head &	elemHead,
		ShapePrimsProc *	shapePrimsProc )

Virtually draws the shape of an element.

Parameters

elemHead	[in] Identifies the element to be processed.
shapePrimsProc	[in] The function to be called to process the element primitives.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameter is nullptr; element
• APIERR_BADDATABASE - Not the appropriate database was open for the operation. For example you tried to access a 2D element while the 3D window - and also the 3D database - was active.
• APIERR_BADID - The element type is invalid,

Remarks

This function draws the element from drawing primitives (see API_PrimElement), using the shapePrimsProc function. The API_PrimElement (the first parameter of ShapePrimsProc) can also contain a control code; these codes mark the beginning and the end of the drawing of sub-parts. It can also contain information on connected elements (e.g. for walls, you get the indices of windows and doors in that wall). These drawing procedures can not be nested. To enable Renovation Overrides or Graphical Overrides see ACAPI_GraphicalOverride_EnableRenovationOverride and ACAPI_GraphicalOverride_EnableVisualOverride. The API_PrimElement (the first parameter of ShapePrimsProc) can also contain a control code; these codes mark the beginning and the end of the drawing of sub-parts. It can also contain information on connected elements (e.g. for walls, you get the indices of windows and doors in that wall). These drawing procedures can not be nested. To enable Renovation Overrides or Graphical Overrides see ACAPI_GraphicalOverride_EnableRenovationOverride and ACAPI_GraphicalOverride_EnableVisualOverride.

Example

The following example shows the usage of ACAPI_DrawingPrimitive_ShapePrims and a sample ShapePrimsProc functions

static GSErrCode Own_DrawElementPrim (const API_PrimElement *primElem,
                                      const void *par1,
                                      const void *par2,
                                      const void *par3)
{
    switch (primElem->header.typeID) {
    case API_PrimPointID:   Own_DrawPrimPoint (&primElem->point); break;
    case API_PrimLineID:    Own_DrawPrimLine (&primElem->line); break;
    case API_PrimArcID:     Own_DrawPrimArc (&primElem->arc); break;
    case API_PrimTextID:    Own_DrawPrimText (&primElem->text,par1); break;
    case API_PrimPLineID:   Own_DrawPrimPLine (&primElem->pline, par1, par2); break;
    case API_PrimTriID:     Own_DrawPrimTri (&primElem->tri); break;
    case API_PrimPolyID:    Own_DrawPrimPoly (&primElem->poly, par1, par2, par3); break;
 
    case API_PrimCtrl_HatchBorderBegID: gHatchBrdMode = true; break;
    case API_PrimCtrl_HatchBorderEndID: gHatchBrdMode = false; break;
    case API_PrimCtrl_HatchLinesBegID:  gHatchLinesMode = true; break;
    case API_PrimCtrl_HatchLinesEndID:  gHatchLinesMode = false; break;
    default: break;
    }
 
    return NoError;
}

In the main program

API_Elem_Head header;
for (GS::Array<API_Guid>::ConstIterator it = elemList.Enumerate (); it != nullptr && !lastErr; ++it) {
    header = {};
    header.guid = *it;
    lastErr = ACAPI_DrawingPrimitive_ShapePrims (header, Own_DrawElementPrim);
}

ACAPI_DrawingPrimitive_ShapePrimsExt()

GSErrCode ACAPI_DrawingPrimitive_ShapePrimsExt	(	const API_Elem_Head &	elemHead,
		ShapePrimsProc *	shapePrimsProc,
		API_ShapePrimsParams *	shapePrimsParams )

Virtually draws the shape of an element.

Parameters

elemHead	[in] Identifies the element to be processed.
shapePrimsProc	[in] The function to be called to process the element primitives.
shapePrimsParams	[in] Shape primitives parameters structure to process the shape primitives by.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - Not the appropriate database was open for the operation. For example you tried to access a 2D element while the 3D window - and also the 3D database - was active.
• APIERR_BADID - The element type is invalid, or the element guid is invalid, or the element type is not supported by the server application
• APIERR_REFUSEDCMD - This error code is returned when the element specified by the guid parameter is not on the current floor.
• APIERR_REFUSEDPAR - Elements that cannot be drawn from primitives were specified in the type parameter, for example API_CamSetID in Archicad.

Remarks

This function draws the element from drawing primitives (see API_PrimElement), using the shapePrimsProc function. The API_PrimElement (the first parameter of ShapePrimsProc) can also contain a control code; these codes mark the beginning and the end of the drawing of sub-parts. It can also contain information on connected elements (e.g. for walls, you get the indices of windows and doors in that wall). These drawing procedures can not be nested. To enable Renovation Overrides or Graphical Overrides see ACAPI_GraphicalOverride_EnableRenovationOverride and ACAPI_GraphicalOverride_EnableVisualOverride. The API_PrimElement (the first parameter of ShapePrimsProc) can also contain a control code; these codes mark the beginning and the end of the drawing of sub-parts. It can also contain information on connected elements (e.g. for walls, you get the indices of windows and doors in that wall). These drawing procedures can not be nested. To enable Renovation Overrides or Graphical Overrides see ACAPI_GraphicalOverride_EnableRenovationOverride and ACAPI_GraphicalOverride_EnableVisualOverride.