A3DSDKBase.h

Functions and structures that apply to all entities.

Author

Tech Soft 3D

Version

23.0

Date

January 2023

Copyright (c) 2010 - 2023 by Tech Soft 3D, Inc. All rights reserved.

Content

Type definitions

A3DCallbackMemoryAlloc	A callback function the library invokes to allocate memory.
A3DCallbackMemoryFree	A callback function the library invokes to free memory.
A3DCallbackReportMessage	A callback function the library invokes to report general messages.
A3DCallbackReportWarning	A callback function the library invokes to report warnings.
A3DCallbackReportError	A callback function the library invokes to report error messages.
A3DCallbackAPITrace	This callback function is invoked each time call to the API is made.
A3DCallbackProgressStart	A callback function the library invokes as it prepares to perform a potentially time-consuming process.
A3DCallbackProgressSize	A callback function the library invokes to report an approximate size of the PRC stream being processed.
A3DCallbackProgressIncrement	A callback function the library intermittently invokes while processing the PRC stream.
A3DCallbackProgressEnd	A callback function the library invokes when it finishes the process.
A3DCallbackProgressTitle	A callback function the library invokes to provide a text string relevant to the processing phase.

Functions

A3DDllInitialize()	Starts a session with the library.
A3DDisableHandleSIGSEGV()	Disables internal SIGSEGV handling (Linux only)
A3DEnableHandleSIGSEGV()	Enables internal SIGSEGV handling (Linux only)
A3DDllTerminate()	Terminates a session with the library.
A3DDllGetVersion()	Gets the version identifiers for the currently installed library.
A3DDllGetBuildInformation()	Gets information relative to build.
A3DDllIsInitialized()	Gets the status of the library initialization library.
A3DDllSetCallbacksMemory()	Specifies custom memory-allocation functions This function specifies callback functions the library uses for memory allocation and and deallocation.
A3DDllSetCallbacksReport()	Specifies custom functions the library uses for reporting messages, warnings and errors.
A3DDllSetCallbackAPITrace()	Sets the callback function for API Trace.
A3DDllSetCallbacksProgress()	Sets callbacks for progress bar facility.

Type definitions

typedef A3DPtr (*A3DCallbackMemoryAlloc)(size_t)

A callback function the library invokes to allocate memory.

Version

2.0

typedef A3DVoid (*A3DCallbackMemoryFree)(A3DPtr)

A callback function the library invokes to free memory.

Version

2.0

typedef A3DInt32 (*A3DCallbackReportMessage)(A3DUTF8Char*)

A callback function the library invokes to report general messages.

These messages are English only.

If this callback function is not provided, the library sends warning messages to the null device.

Version

2.0

typedef A3DInt32 (*A3DCallbackReportWarning)(A3DUTF8Char*, A3DUTF8Char*)

A callback function the library invokes to report warnings.

The returned message begins with a unique error code, which you can use for localization. In some cases, the second argument provides additional information about the warning. These messages are English only.

If this callback function is not provided, the library sends warning messages to the null device.

Version

2.0

typedef A3DInt32 (*A3DCallbackReportError)(A3DUTF8Char*, A3DUTF8Char*)

A callback function the library invokes to report error messages.

The returned message begins with a unique error code, which you can use for localization. In some cases, the second argument provides additional information about the error. These messages are English only.

If this callback function is not provided, the library sends error messages to the null device.

Version

2.0

typedef A3DVoid (*A3DCallbackAPITrace)(const A3DUTF8Char*, A3DUns32, const A3DUTF8Char**, const A3DUTF8Char*)

This callback function is invoked each time call to the API is made.

This allows you to check every call to the API and write them in the standard output or apply any other treatment you wish.

typedef A3DVoid (*A3DCallbackProgressStart)(A3DInt32)

A callback function the library invokes as it prepares to perform a potentially time-consuming process.

The argument identifies the processing phase, as follows:

Processing phase	Description
0	Undefined.
1	Parsing the file
2	Writing file
3	Reading or building the model, which follows parsing the file (processing phase 1)

Version

2.0

typedef A3DVoid (*A3DCallbackProgressSize)(A3DInt32)

A callback function the library invokes to report an approximate size of the PRC stream being processed.

The size is independent of units and is bounded only by the limit of the A3DInt32 type.

Version

2.0

typedef A3DVoid (*A3DCallbackProgressIncrement)(A3DInt32)

A callback function the library intermittently invokes while processing the PRC stream.

As processing proceeds, the argument increments from 0 to a maximum of Size, where Size is the argument provided in A3DCallbackProgressSize.

Version

2.0

typedef A3DVoid (*A3DCallbackProgressEnd)()

A callback function the library invokes when it finishes the process.

Version

2.0

typedef A3DVoid (*A3DCallbackProgressTitle)(A3DUTF8Char *msg)

A callback function the library invokes to provide a text string relevant to the processing phase.

In the case of reading PRC data from a file, the argument provides the name of the file containing the PRC stream.

Version

2.0

Functions

A3DStatus A3DDllInitialize(A3DInt32 iMajorVersion, A3DInt32 iMinorVersion)

Starts a session with the library.

This function initializes the internal structures in the library.

A3DInt32 iErr = A3D_SUCCESS;
A3DInt32 iMajorVersion = 0, iMinorVersion = 0;

iErr = A3DDllGetVersion( &iMajorVersion, &iMinorVersion );
if( iMajorVersion != A3D_DLL_MAJORVERSION ) 

    iErr = A3D_ERROR;

else if( iMinorVersion < A3D_DLL_MINORVERSION ) 

    iErr = A3D_ERROR;



if( iErr == A3D_SUCCESS ) 
{
    iErr = A3DDllInitialize( A3D_DLL_MAJORVERSION, A3D_DLL_MAJORVERSION );
    if ( iErr == A3D_SUCCESS )
    {
        /* Insert your own code to create/read models */
        /* ... */
        /* At end of process, terminate the DLL use */
        iErr = A3DDllTerminate();
    }
}

Version

2.0

Sample code

Warning

You must call this function before calling any other functions in the HOOPS Exchange, with these exceptions:

• You can call A3DDllGetVersion anytime.

• To have the library produce an XML trace file, you must call A3DDllActivateXMLTrace before calling this function.

Parameters

• iMajorVersion – The major version of the HOOPS Exchange. Set this value to A3D_DLL_MAJORVERSION

• iMinorVersion – The minor version of the HOOPS Exchange. Set this value to A3D_DLL_MINORVERSION

Return values

• <tt>A3D_INITIALIZE_ALREADY_CALLED</tt> –

• <tt>A3D_SUCCESS</tt> –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDisableHandleSIGSEGV()

Disables internal SIGSEGV handling (Linux only)

This function deactivates the handling of the SIGSEGV signal on Linux. By default, SIGSEGV is handled and an exception is thrown to return A3D_EXCEPTION.

Deprecated:

the default behavior has changed with 11.2 to disable the SIGSEGV handling

Warning

You must call this function before A3DDllInitialize

Return values

• A3D_SUCCESS –

• A3D_ERROR – if not on Linux

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DEnableHandleSIGSEGV()

Enables internal SIGSEGV handling (Linux only)

This function activates the handling of the SIGSEGV signal on Linux. When this function is activated, SIGSEGV is handled and an exception is thrown to return A3D_EXCEPTION.

Warning

You must call this function before A3DDllInitialize

Return values

• A3D_SUCCESS –

• A3D_ERROR – if not on Linux

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllTerminate()

Terminates a session with the library.

This function terminates a session with the library. It deallocates memory it has previously allocated for its internal use.

You must call this function to end a session with the library.

Version

2.0

Warning

You can call this function only after successfully calling A3DDllInitialize.

Warning

When your process is done with A3DLIBS.dll (after calling A3DDllTerminate), you MUST unload that DLL, as shown in the sample code for A3DDllInitialize. Unloading the DLL helps to avoid conflicts that can occur when multiple processes use A3DLIBS.dll.

Warning

Processes must avoid parallel access to A3DLIBS.dll.

Return values

• A3D_INITIALIZE_NOT_CALLED –

• A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllGetVersion(A3DInt32 *piMajorVersion, A3DInt32 *piMinorVersion)

Gets the version identifiers for the currently installed library.

This function returns the version of the currently installed library. Use these version identifiers to determine whether that library is compatible with your application. The value returned through the piMajorVersion argument is identical to the Acrobat version identifier. The value returned through the piMinorVersion argument is specific to the library.

To ensure compatibility, the A3D_DLL_MAJORVERSION must be identical to the major version of currently installed library, and the A3D_DLL_MINORVERSION must be less than or equal to the minor version of the currently installed library.

You can call A3DDllGetVersion anytime, even before calling A3DDllInitialize and after calling A3DDllTerminate. This function does not allocate memory.

Version

2.0

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllGetBuildInformation(A3DUTF8Char **ppBuildInformation)

Gets information relative to build.

This function returns build information. This can be asked by support to help solving problem. This function does not allocate memory.

Version

14.2

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllIsInitialized()

Gets the status of the library initialization library.

This function returns the status of the library initialization library.

This function does not allocate memory.

Version

11.0

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllSetCallbacksMemory(A3DCallbackMemoryAlloc, A3DCallbackMemoryFree)

Specifies custom memory-allocation functions This function specifies callback functions the library uses for memory allocation and and deallocation.

If this function is not called, the standard malloc and free functions are used for memory allocation and deallocation.

Version

2.0

Sample code

A3DPtr my_alloc(A3DUns32 uiSize) { return malloc(uiSize); }
A3Dvoid my_free(A3DPtr ptr) { if (ptr) free(ptr); }

A3DInt32 iErr = A3D_SUCCESS;
A3DInt32 iMajorVersion,iMinorVersion = 0;

iErr = A3DDllGetVersion( &iMajorVersion, &iMinorVersion );
iErr = A3DDllInitialize( A3D_DLL_MAJORVERSION, A3D_DLL_MAJORVERSION );
if ( iErr == A3D_SUCCESS )
{
    iErr = A3DDllSetCallbacksMemory( my_alloc , my_free );
    iErr = A3DDllTerminate();
}

Return values

• A3D_INITIALIZE_NOT_CALLED –

• A3D_CALLBACK_MEMORY_FUNCTIONS_ALREADY_SET –

• A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllSetCallbacksReport(A3DCallbackReportMessage, A3DCallbackReportWarning, A3DCallbackReportError)

Specifies custom functions the library uses for reporting messages, warnings and errors.

This function configures the library with the callback functions the library uses for reporting messages, warnings and errors.

To ensure your callback is aware of early-occurring messages, call the A3DDllSetCallbacksReport function immediately after the A3DDllInitialize function is successfully called.

Version

2.0

Sample code

A3DInt32 my_message(A3DUTF8Char *msg) { _tprintf(_T("%s"),msg); return fflush(stdout); }
A3DInt32 my_warning(A3DUTF8Char* pcCode, A3DUTF8Char *msg) { _tprintf(_T("WARNING #%s:"),pcCode); return my_message(msg); }
A3DInt32 my_error(A3DUTF8Char* pcCode, A3DUTF8Char *msg) { _tprintf(_T("ERROR #%s:"),pcCode); return my_message(msg); }

A3DInt32 iErr = A3D_SUCCESS;
A3DInt32 iMajorVersion,iMinorVersion = 0;

iErr = A3DDllGetVersion( &iMajorVersion, &iMinorVersion );
iErr = A3DDllInitialize( A3D_DLL_MAJORVERSION, A3D_DLL_MAJORVERSION );
if ( iErr == A3D_SUCCESS )
{
    iErr = A3DDllSetCallbacksReport( my_message , my_warning , my_error );
    iErr = A3DDllTerminate();
}

Warning

If you do not call this function, the library sends all messages to the null device. The first string returned by the two functions above corresponds to a unique error code. You can use that code to localize messages supplied to your users.

Return values

• A3D_INITIALIZE_NOT_CALLED –

• A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DDllSetCallbackAPITrace(A3DCallbackAPITrace)

Sets the callback function for API Trace.

If API Trace is enabled, the library will call the given function of type

See also

A3DCallbackAPITrace for each call made by client code to API functions.

A3DStatus A3DDllSetCallbacksProgress(A3DCallbackProgressStart, A3DCallbackProgressSize, A3DCallbackProgressIncrement, A3DCallbackProgressEnd, A3DCallbackProgressTitle, A3DInt32*)

Sets callbacks for progress bar facility.

This function configures the library with the callback functions that implement a custom progress indicator, such as a status bar.

The last argument passed to this function sets a break. The library checks this variable at every significant step in processing the PRC. If the value is non-zero, the library stops processing the PRC data.

Version

2.0

Attention

The library stops processing the PRC data if the last argument passed to this function is non-zero.

Sample code

A3DVoid my_start(A3DInt32 iType) { _tprintf(_T("STARTING PROCESS #%d"), iType); fflush(stdout); }
static A3DInt32 stiSize = 0;
A3DVoid my_size(A3DInt32 iSize) { stiSize = iSize; }
A3DVoid my_increment(A3DInt32 i) { _tprintf(_T("PROCESS %d / %d"), i, stiSize); fflush(stdout); }
A3DVoid my_end() { stiSize = 0; }
A3DVoid my_title(A3DUTF8Char* msg)
{
#ifdef _MSC_VER
    A3DUniChar acUTF16FileName[MAX_PATH*4];
    A3DMiscUTF8ToUTF16(msg, acUTF16FileName);
    _tprintf(_T("CURRENT FILE %s\n"), acUTF16FileName);
#else
    _tprintf(_T("CURRENT FILE %s\n"), msg);
#endif
    fflush(stdout);
}

A3DInt32 iErr = A3D_SUCCESS;
A3DInt32 iMajorVersion,iMinorVersion = 0;
A3DInt32 my_break = 0;

iErr = A3DDllGetVersion(&iMajorVersion, &iMinorVersion);
iErr = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MAJORVERSION );
if (iErr == A3D_SUCCESS)
{
    iErr = A3DDllSetCallbacksProgress(my_start, my_size, my_increment, my_end, my_title, &my_break);
    iErr = A3DDllTerminate();
}

Return values

• A3D_INITIALIZE_NOT_CALLED –

• A3D_CALLBACK_INVALID_BREAK_VALUE –

• A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code