< Home

< Programming Guide

< Supported File Formats

REFERENCE MANUAL

API Conventions



General Overview

The HOOPS Exchange Library lets you develop applications that create and access data in a PRC stream.

Using HOOPS Exchange Library, you can fully access the 3D data that comprise PRC files, including geometry information, structure, and Product and Manufacturing Information (PMI).

The A3D API defines the public interface within the HOOPS Exchange Library. The API provides dedicated functions, types, and other API features that have self-documenting names.

The A3D API has these architectural characteristics:

A3D API handles these tasks:

Capabilities

HOOPS Exchange Library reading capabilities

The HOOPS Exchange Library enables an application to load PRC files into memory, and then to access the data in specific PRC entities.

The HOOPS Exchange Library provides these features:

A3D API querying capabilities

The A3D API provides a range of functions you can use to obtain information about the PRC data. Here are examples of the types of PRC data you can access:

The A3D API does not provide access to arbitrary user data embedded in the PRC data.

A3D API writing capabilities

The A3D API provides functions that let you create 3D models, which you then export to PRC files. These functions let you create the following types of entities:

You can embed the PRC files you produce in PDF files and create 3D Annots that reference those embedded PRC files.

Memory allocation

Memory allocation is done using the A3D API memory allocation functions, which are the A3DCallbackMemoryAlloc and A3DCallbackMemoryFree functions; however, you can override these with custom memory-allocation functions.

Functions, Callback Functions, and PRC Entity References

Typedefs, Data Structures, Functions and Function returns

The HOOPS Exchange Library exposes functions and the structures and other types that those functions accept as arguments.

Typedefs

The following table describes the typedefs defined for each PRC entity. The entries in this table use the italics font face to indicate placeholder names.

Typedef Name
Description
A3DPrefixEntityName An opaque structure for the PRC entity. This is a void* type in which the HOOPS Exchange Library stores a private copy of the entity (for example, the typedef for a planar surface is A3DSurfPlane).

Data Structures

The following table describes the structures defined for each PRC entity. The entries in this table use the italics font face to indicate placeholder names.

C Structure Name
Description
A3DPrefixEntityNameData Public data for the PRC entity, with the data made available as members or as cascaded attributes (see Miscellaneous Cascaded Attributes). For example, the typedef for the public data in a planar surface is A3DSurfPlaneData.

Functions

The following table describes the functions for use with most A3DPrefixEntityName objects.

Function name
Description
A3DPrefixEntityNameGet
A3DStatus A3DPrefixEntityNameGet ( const A3DPrefixEntityNamepEntity,
A3DPrefixEntityNameData *  pData,
)
     <p> Given a pointer to the PRC entity, this type of function populates (or frees) a Data structure. This type of function is used to parse PRC data. 
     Whether these function create or free structures depends on the value of the input pointer: </p>

     <ul>
        <li>If the input pointer A3D<em>Prefix<b>EntityName</b></em> is non-NULL, then the function fills the structure A3D<em>Prefix<b>EntityName</b></em>Data 
        with appropriate information stored in A3D<em>Prefix<b>EntityName</b></em> entity. </li>
        <li>If the input pointer A3D<em>Prefix<b>EntityName</b></em> is NULL, then the function frees the whole structure A3D<em>Prefix<b>EntityName</b></em>Data. 
        Every kind of information below is then lost.  </li>
     </ul>

     <p>For example, given the \ref A3DSurfPlane, the \ref A3DSurfPlaneGet function populates the \ref A3DSurfPlaneData structure with information about the planar
     surface.  </p>

     <p><b>Attention:</b></p>
     <ul class="OptionsList">
        <li>Before invoking an <span class="courier">A3d<em>Prefix<b>EntityName</b></em>Get()</span> function, you must initialize the structure that the function will populate 
        by using the macro A3D_INITIALIZE_DATA. If you do not initialize the structure, the function returns A3D_INITIALIZE_NOT_CALLED and does not return the 
        requested data. See the following sample code.</li>
     </ul>

     <p><b>Parameters:</b> </p>
     <table>
        <tr>
           <td><span class="courier">[in]</span></td>
           <td><em>A3DPrefix<b>EntityName</b></em></td>
           <td>the pointer to the PRC entity.  </td>
        </tr>
        <tr>
           <td><span class="courier">[in, out]</span></td>
           <td><em>A3DPrefix<b>EntityName</b>Data</em></td>
           <td>the Data structure to populate. The function may allocate memory that you will be responsible to free.  </td>
        </tr>
     </table>

     <p><b>Returns:</b> </p>
     <ul class="OptionsList">
        <li>A3D_INITIALIZE_NOT_CALLED</li>
        <li>A3D_INVALID_DATA_STRUCT_NULL</li>
        <li>A3D_INVALID_DATA_STRUCT_SIZE</li>
     </ul>
     </td>

A3DPrefixEntityNameCreate

A3DStatus A3DPrefixEntityNameCreate ( const A3DPrefixEntityNameData *  pData,
A3DPrefixEntityName **  ppEntity,
)

Given a pointer to a Data structure, this category of function creates a PRC entity. This type of function is used to create PRC data. For example, given a populated A3DSurfPlaneData, the A3DSurfPlaneCreate function creates the A3DSurfPlane PRC entity.

Attention:

  • Before invoking an A3dPrefixEntityNameCreate() function, you must initialize the structure that the function will consume by using the macro A3D_INITIALIZE_DATA. Also, the HOOPS Exchange Library performs internal checks before creating the entity. If it detects an error, it returns an error code to the A3dPrefixEntityNameCreate() function. You must modify the input data accordingly.

Parameters:

[in] A3DPrefixEntityNameData the Data structure used to define the entity.
[in, out] A3DPrefixEntityName the address of the pointer to the newly created PRC entity. The function allocates memory but you are responsible for freeing this entity.

Returns:

  • A3D_INITIALIZE_NOT_CALLED
  • A3D_INVALID_DATA_STRUCT_NULL
  • A3D_INVALID_DATA_STRUCT_SIZE

Function returns

Unless specified, all functions return an error code (A3DStatus) with the value A3D_SUCCESS in case of success and a negative value in case of error. All possible error codes are listed for each function and related meanings are in the A3DSDKErrorCodes.h file.

Callback functions

You can define a set of callback functions to integrate HOOPS Exchange Library into your own environment. These functions can handle the following issues:

References to PRC entities

The HOOPS Exchange Library creates and interprets the unique identifiers the PRC format uses to to reference PRC entities.

The PRC format describes the use of unique identifiers to reference PRC entities. Every PRC entity can be referenced by other PRC entities, provided those references conform to the conventions specified in the PRC Format Specification.

The HOOPS Exchange Library manages the references between PRC entities, saving you from creating and resolving those unique identifiers. More specifically, a A3DPrefixEntityNameGet function takes as an argument a pointer to another PRC entity. The pointer is an opaque structure that the HOOPS Exchange Library resolves to the PRC entity of interest.

In the following sample code, the A3DAsmPartDefinitionGet function takes as an argument a pointer to a PRC part definition. The pointer is an opaque structure that includes that part definition's unique identifier. A3DAsmPartDefinitionGet resolves the pointer into an object that represents that part definition.

Sample code

The following sample code shows the creation and initialization of the A3DPrefixEntityName and A3DPrefixEntityNameData structures. It also shows the invocation of the A3DAsmPartDefinitionGet function. The A3D_INITIALIZE_DATA macro initializes the A3DAsmPartDefinitionData structure. You must use that macro to initialize any A3D API data structure used in your application.

/* code to get data from a pointer on a part definition so called A3DAsmPartDefinition* */
A3DAsmPartDefinition* pPartDefinition;
if (A3DAsmPartDefinitionGet(pPartDefinition,&sData) == A3D_SUCCESS)
{
/* work with sData... and finally free the structure */
A3DAsmPartDefinitionGet( NULL, &sData );
}

In above sample code, A3DAsmPartDefinition is earlier obtained from the m_pPart member of a product occurrence.

Naming Conventions

The A3D API uses naming conventions that are self-documenting. The names of all declared items (types, functions, structures, and structure members) express the category of declaration they represent and the type of PRC entity they represent or operate on. By understanding the A3D API naming conventions, your programming effort will be much easier.

Identifying items declared by the A3D API

The A3D API naming conventions use prefixes to identify all items it declares. This convention distinguishes items declared by A3D API from items declared by any other libraries you are using. This convention also enables portability.

The following table summarizes the general prefix naming convention.

Category
Format
Description
Scalar types A3DType Types unique to A3D API are prefixed with A3D to facilitate portability (for example the A3DDouble type). Types adopted from the Acrobat SDK are prefixed with AS.
Entities A3DPrefixEntityName

The Prefix indicates the entity category (for example the A3DCrvCircle entity defines a portion of a curve (an arc) that is based on a circle; the prefix is Crv, indicating that the entity is grouped with other entities that also define curves).

Functions A3DPrefixEntityNameAction A3DPrefixEntityName identifies the entity, and Action indicates the action performed by the function. (for example, A3DCrvCircleCreate and A3DCrvCircleGet are two functions implemented for the entity A3DCrvCircle).
"C" Structures A3DPrefixEntityNameData A3DPrefixEntityName identifies the entity, and Data indicates that the structure contains data associated with the entity.
Enumerates kA3DPrefixEntityNameAttribute The k indicates that the item is an enumerated value (for example kA3DGraphicsShow).

Structure members

All structures members are prefixed with m_ followed by one or more lowercase letters representing the type of data, as shown in the following table.

Prefix
Description
m_b Value of type A3DBool (for example the A3DMiscCascadedAttributesData::m_bShow member).
m_c Value of type A3DInt8 (for example the A3DFontKeyData::m_cAttributes member). The A3DInt8 type is equivalent to the char type in the C standard library.
m_d Value of type A3DDouble (for example the A3DCrvHelixPitchVarData::m_dRatioU member).
m_e Enumerated value (for example the A3DMkpMarkupData::m_eType member).
m_i Value of type A3DInt32 (for example the A3DFontKeyData::m_iFontFamilyIndex member).
m_p Generic pointer (for example the A3DMkpLeaderData::m_pLinkedItem member).
m_s Generic structure (for example the A3DMiscCartesianTransformationData::m_sOrigin.
m_uc Value of type A3DUns8 (for example the A3DGraphTextureDefinitionData::m_ucTextureDimension member). The A3DUns8 type is equivalent to the unsigned char type in the C standard library.
m_ui Value of type A3DUns32 (for example the A3DGlobalData::m_uiColorsSize member). The A3DUns32 type is equivalent to the unsigned int type in the C standard library.
m_us Value of type A3DUns16 (for example the A3DTessFaceData::m_usStructSize member). The A3DUns16 type is equivalent to the unsigned short type in the C standard library.

Pointer and array structure members

Some pointer and array structure members include an additional prefix letter that indicates the type of structure they reference, as described in the following table.

Prefix
Description
m_ad Array of A3DDouble values, for example the A3DMathFct3DLinearData::m_adMatrix member.
m_pc Pointer to an A3DUTF8Char character string (for example the A3DFontData::m_pcFamilyName member).
m_pd Pointer to an A3DDouble (for example the A3DTessBaseData::m_pdCoords member).
m_pp Pointer to an array of pointers (for example the A3DRootBaseData::m_ppAttributes member).
m_ps Pointer to a structure (for example the A3DTess3DData::m_psFaceTessData member).

Entity Base Attributes

The attributes for a PRC entity includes data specific to the entity and data specified in base entities or abstract classes inherited by that entity. You access the data specific to the entity using the get and set functions specific to the entity. These functions have the form A3DEntity_nameGet and A3DEntity_nameSet or A3DEntity_nameCreate. How you get or set the data specified in a base entity or an inherited class depends on the entity, as described in this table.

Name of Abstract Class
Application
Description
A3DRootBase All PRC entities A root entity that represents a name and (optionally) a hierarchy of names and/or modeler data. Get this data with the A3DRootBaseGet function. Set this data and associate it with the PRC entity by invoking the A3DRootBaseSet function.
A3DRootBaseWithGraphics Any entity with graphics An abstract class that references an A3DGraphics entity, which in turn can specify a layer index, style index and inheritance behavior. Get this data using the Miscellaneous Cascaded Attributes facility, which uses the inheritance settings to determine whether to return the settings for the entity, its parent, or its child. (See Miscellaneous Cascaded Attributes.) Set this data using the functions from derived classes.
A3DGlobal All PRC entities This entity is not a root entity or an abstract class. Instead, it is used for associating attributes with indexes. Other entities use these indexes to specify the attribute characteristic. This ensures a standard definition for attributes and provides a more efficient storage.
A3DRiRepresentationItem Entities in the Representation Items Module A root entity that contains data common to all representation items. Get this data with the A3DRiRepresentationItemGet function, determine the type of the derived class it represents, and then invoke the function for that representation item. Set this data with the derived class such as the A3DRiBrepModelCreate function.
A3DTopoBody Entities in the Topology Module A root entity that contains data common to all entities in the Topology Module, such as a coordinate system entity (A3DRiCoordinateSystem). This class describes topology behavior (inheritance) and context (granularity, thickness, and scale). Get the data in this base class with the A3DTopoBodyGet function. Set the data in this base class with the derived class, such as theA3DTopoSingleWireBodyCreate function.
A3DTessBase Entities in the Tessellation Module An abstract class common to all tessellation entities. Unlike the other root entities, this one does not provide data common to all tessellation entities The data returned by the A3DRiRepresentationItemGet function contains a pointer to this abstract class. Use the A3DEntityGetType function to determine the type of the derived class, and then use appropriate function to obtain the data. These specific functions are A3DTess3DGet, A3DTess3DWireData, and A3DTessMarkupData.

Miscellaneous Cascaded Attributes

Miscellaneous cascaded attributes is a facility that reconciles the inheritable graphics data that can be applied to a PRC entity. Such inheritable data includes the show and removed settings, style attributes (such as color and pattern), layer attributes, and coordinate system transformations.

Graphics attributes and inheritance

The A3DGraphicsCreate function lets you set the graphics data applied to an entity. It also lets you set inheritance behavior for the attributes. These bits can specify that an attribute be inherited from a child entity or from a parent entity.

If the data supplied to the A3DGraphicsCreate function specifies inheritance of a particular attribute, then the attribute specified for the entity is ignored and only the inherited attribute is used. For example, if a graphic entity has the kA3DGraphicsShow setting and the kA3DGraphicsSonHeritShow setting, then the kA3DGraphicsShow setting is ignored.

The A3DGraphicsGet function obtains the graphics data for a particular PRC entity; however, it does not honor inheritance settings.

See also
Graphics

Using cascaded attributes to get graphics attributes for an entity

Because cascaded attributes include inheritable attributes, the HOOPS Exchange Library implements a stack architecture in which you store miscellaneous cascaded attributes, where the bottom entry in the stack is the model file. As your code recurses through the PRC entities that comprise the PRC model file, you invoke the PRC function to add cascaded attributes to the stack, as described in the following sample code. The first entry is for the model file and the next is the first product occurrence entity.

Sample code

Here are the main tasks performed in the following sample code:

  1. A3DMiscCascadedAttributesCreate creates an empty structure in which the cascaded attributes are to be stored.
  2. A3DMiscCascadedAttributesPush populates that structure with the miscellaneous cascaded attributes for the PRC entity and pushes the parent cascaded attribute structure onto the stack. One of the A3DMiscCascadedAttributesPush arguments is a pointer to the parent entity A3DMiscCascadedAttributes stack location.
  3. A3DMiscCascadedAttributesGet populates a structure with the miscellaneous cascaded attributes. You can access members in the A3DMiscCascadedAttributesData structure.
  4. A3DMiscCascadedAttributesDelete deletes the previously created A3DMiscCascadedAttributes structure.
/* Code to get the attributes of a part definition */
/* pFatherAttr is the cascaded attributes coming from the product occurrence */
A3DInt32 BrowsePartDefinition(const A3DAsmPartDefinition* pPart, const A3DMiscCascadedAttributes* pFatherAttr)
{
A3DMiscCascadedAttributesPush(pPart, pFatherAttr, pAttr);
A3D_INITIALIZE_DATA(&sAttrData);
A3DMiscCascadedAttributesGet(pAttr, &sAttrData));
/* use sAttrData which describes the part definition */
return A3D_SUCCESS;
}

Frequently Asked Questions

Navigating the A3D API Reference (this reference)

Question

I can't find information about an entity that appears as an argument. When I click the name of an entity, I see only a void type declaration. I want to see the data the entity represents. For example, when I click on the A3DAsmModelFile argument in the following declaration:

For example, when I click on the A3DAsmModelFile argument in the following declaration:

I see a void type definition, such as the one that follows. How can I see the data in this entity?

typedef void A3DAsmModelFile

Answer

The void type declarations specify a type whose structure is concealed. But you can see the data used to construct the type by examining the A3DEntity-nameData structure. You can find that structure in this reference by navigating to the Data Structures tab of this document and then selecting the structure of interest.

PRC entities also have other attributes depending on their membership to a module, as described in Miscellaneous Cascaded Attributes.

See also
contents