1.2 API Conventions

The HOOPS Exchange library is written in the C++ programming language. However, all C++ interfaces are hidden and the library is exposed as a C API. See the initialization section for information on how to set up HOOPS Exchange.

Naming conventions

All HOOPS Exchange functions and data structures start with the A3D prefix. Some enums start with the kA3D prefix. Whenever possible, a secondary prefix is also employed. For example, if you are using a data structure that represents a representation item, it will have the secondary prefix Ri:

// data structure for representation item
A3DRiRepresentationItemData myData;
// calling a function that handles representation items
A3DRiCurveCreate(myCurveData, myRICrv);

This paradigm is extended to most data structures and functions. You can use these abbreviations to quickly discover what the data structure or function operates on:

Sometimes, you will encounter a data structure of a generalized form. For example, the A3DRiRepresentationItemData structure has the field m_pTessBase, which is of type A3DTessBase. At some point, you will find it necessary to discover the exact type of this object. This is done in the following way:

A3DEEntityType entityType;
A3DEntityGetType(baseType, &entityType);

You then test the returned type against all possible types:

switch (entityType)
{
case kA3DTypeTess3D:
// it is of type A3DTess3D
case kA3DTypeTess3DWire:
// it is of type A3DTypeTess3DWire
case kA3DTypeTessFace:
// it is of type A3DTypeTessFace

Finally, after you know the type, you can get the tessellation data. For an example of how to get data associated with an entity, see the next subsection on "Getting node data".

Getting node data

In a HOOPS Exchange assembly tree, data associated with a node is stored separately from the node itself. While traversing the tree, you will be traversing its nodes only. Therefore, when you need a node's associated data, you must explicitly populate it before it can be used. For example, assuming you have a reference to a part definition node called partDefNode, the general sequence for getting the data associated with a part definition is as follows:

A3DAsmPartDefinition* partDefNode = // ... get part definition reference
// 'partDefData' holds the node's data
A3DAsmPartDefinitionData partDefData;
// initialize the 'partDefData' memory
A3D_INITIALIZE_DATA(A3DAsmPartDefinitionData, partDefData);
// fill 'partDefData' with the data from 'partDefNode'
A3DAsmPartDefinitionGet(partDefNode, &partDefData);
// partDefData now has the data associated with the node 'partDefNode'

Other node types follow a similar pattern. If the initialized entity contains arrays, A3D_INITIALIZE_DATA will allocate memory for those arrays. For these entities, you are responsible for freeing the memory by calling the initialization function again with a NULL parameter:

A3DAsmPartDefinitionGet(NULL, &partDefData);

NOTE: For simplicity and brevity, the code samples in this manual do not always explicitly show allocated memory being released. However, this should always be done for structures that allocate additional memory for arrays. If you do not delete your structures in this way, you will have a memory leak.

This pattern of A3D<OBJECTNAME>Get is used to initialize structures for many HOOPS Exchange objects. Additionally, the pattern extends to object creation: A3D<OBJECTNAME>Create can be used to create nodes or attributes, when necessary. When creating objects, it is your responsibility to also delete them using the corresponding function A3D<OBJECTNAME>Delete. For example:

A3DMiscCascadedAttributes* pAttr;
A3DMiscCascadedAttributesCreate(&pAttr);
// ...
A3DMiscCascadedAttributesDelete(pAttr);

When a producing data function fails, there's no need to explicitely call the the associated delete function.

Data types and field names

In order to ensure type size is consistent across systems, HOOPS Exchange uses substitutes for primitive types. For example, the double primitive has been replaced by A3DDouble and bool has been replaced by A3DBool. If a type represents unsigned data, it will include the Uns prefix. In certain cases, the type length is also included. For example, a 16-bit unsigned type will take the form A3DUns16.

The primitive types are defined in A3DSDKTypes.h and include:

In general, Hungarian notation is used for field names. Field names are also prefixed by m_. For example, the field m_uiViewsSize indicates this member is an unsigned integer, and m_ppViews is a pointer to a pointer of views.

Compatibility with different PRC format versions

HOOPS Exchange provides backward compatibility with other PRC format versions.

In a major release, the HOOPS Exchange support for PRC is backward compatible. Each new version of the software can read PRC files that conform to an earlier PRC format version.

In terms of HOOPS Exchange itself, we have a policy when making API changes. First, a function is marked as deprecated, and it remains that way for a major release cycle before finally being removed. In this way, old source code will still compile for a limited time even with new versions of HOOPS Exchange.

Character encoding

HOOPS Exchange uses UTF-8 character encoding. The API provides these functions for Unicode conversion:

Handling errors

Most HOOPS Exchange functions return an integer return code. Your code should always check that a function was successful before continuing. If a function terminates without error, it will return A3D_SUCCESS. All error codes are defined in A3DSDKErrorCodes.h.

top_level:1 prog_guide:0