< Home

< Programming Guide

< Supported File Formats

REFERENCE MANUAL

API Conventions



Memory allocation

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

Functions, Callback Functions, and Publish Entity References

Typedefs, Data Structures, Functions and Function returns

The HOOPS Publish 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 Publish entity. The entries in this table use the italics font face to indicate placeholder names.

Typedef Name
Description
A3DPDFPrefixEntityName An opaque structure for the Publish entity. This is a void* type in which the HOOPS Publish Library stores a private copy of the entity (for example, the typedef for a document is A3DPDFDocument).

Data Structures

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

C Structure Name
Description
A3DPDFPrefixEntityNameData Public data for the Publish entity, with the data made available as members. For example, the typedef for the public data in a page is A3DPDFPageData.

Functions

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

Function name
Description

A3DPDFPrefixEntityNameCreate

A3DStatus A3DPDFPrefixEntityNameCreate ( const A3DPDFPrefixEntityNameData *  pData,
A3DPDFPrefixEntityName **  ppEntity,
)

Given a pointer to a Data structure, this category of function creates a Publish entity. This type of function is used to create Publish data. For example, given a populated A3DPDFTextData, the A3DPDFTextCreate function creates the A3DPDFText Publish entity.

Attention:

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

Parameters:

[in] A3DPDFPrefixEntityNameData the Data structure used to define the entity.
[in, out] A3DPDFPrefixEntityName the address of the pointer to the newly created Publish 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 A3DPDFErrorCodes.h file.

Callback functions

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

Naming Conventions

The HOOPS Publish 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 Publish entity they represent or operate on. By understanding the HOOPS Publish API naming conventions, your programming effort will be much easier.

Identifying items declared by the HOOPS Publish API

The HOOPS Publish API naming conventions use prefixes to identify all items it declares. This convention distinguishes items declared by HOOPS Publish 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 HOOPS Publish API are prefixed with A3D to facilitate portability (for example the A3DDouble type).
Entities A3DPDFEntityName A3DPDFEntityName identifies the entity (for example the A3DPDFPage entity defines a document page)..
Functions A3DPDFEntityNameAction A3DEntityName identifies the entity, and Action indicates the action performed by the function. (for example, A3DPDF3DArtworkAddView is a function implemented for the entity A3DPDF3DArtwork).
"C" Structures A3DPDFEntityNameData A3DPDFEntityName identifies the entity, and Data indicates that the structure contains data associated with the entity.
Enumerates kA3DPDFPrefixAttribute The k indicates that the item is an enumerated value (for example kA3DPDFImageFormatJpg).

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 A3DPDF3DAnnotData::m_bShowToolbar member).
m_c Value of type A3DInt8. The A3DInt8 type is equivalent to the char type in the C standard library.
m_d Value of type A3DDouble (for example the A3DPDFViewData::m_dZoomFactor member).
m_e Enumerated value (for example the A3DPDF3DAnnotData::m_eLighting member).
m_i Value of type A3DInt32 (for example the A3DPDFRectData::m_iLeft member).
m_p Generic pointer (for example the A3DPDF3DArtworkData::m_pStream member).
m_s Generic structure (for example the A3DPDFViewData::m_sPosition.
m_uc Value of type A3DUns8. The A3DUns8 type is equivalent to the unsigned char type in the C standard library.
m_ui Value of type A3DUns32. The A3DUns32 type is equivalent to the unsigned int type in the C standard library.
m_us Value of type A3DUns16. 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.
m_pc Pointer to an A3DUTF8Char character string (for example the A3DPDFTextData::m_pcTextString member).
m_pd Pointer to an A3DDouble.
m_pp Pointer to an array of pointers.
m_ps Pointer to a structure.

Frequently Asked Questions

Navigating the HOOPS Publish 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 A3DPDFDocument 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 A3DPDFDocument

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.