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:
extern
"C"
statements. A3D API handles these tasks:
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:
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.
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 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.
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.
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.
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.
A3DPrefixEntityNameGet |
<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 |
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:
Parameters:
Returns:
|
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.
You can define a set of callback functions to integrate HOOPS Exchange Library into your own environment. These functions can handle the following issues:
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.
In above sample code, A3DAsmPartDefinition is earlier obtained from the m_pPart member of a product occurrence.
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.
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.
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.
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). |
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.
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 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.
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.
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:
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?
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.