Error Tracking

HOOPS Luminate uses a mechanism of error codes to report problems. Mainly there are two types of problems: misusages of the HOOPS Luminate API or errors from HOOPS Luminate itself. Both mechanisms are based on RED_RC returned values from most of the HOOPS Luminate API calls. A typical HOOPS Luminate API method uses several parameters and returns a RED_RC value.

HOOPS Luminate uses return codes for several reasons, among which the wish to not interfere with the hosting application exception policy: HOOPS Luminate won’t trap system exceptions, segmentation faults or other low level signals that can be emitted on critical errors, letting the hosting application decide on the behavior to use.

Therefore it’s critical to check all HOOPS Luminate functions and method return values to detect errors as soon as they arise.

Debug Output

In addition to this, HOOPS Luminate features an error callback mechanism similar to a debug output system to gather extra informations on errors:

Setup an Error Callback

An error callback can be set through the RED::IResourceManager interface:

// Access the resource manager:
RED::Object* resmgr = RED::Factory::CreateInstance( CID_REDResourceManager );
if( resmgr )
{
    RED::IResourceManager* iresmgr = resmgr->As< RED::IResourceManager >();
    RC_TEST( iresmgr->SetErrorCallback( MyErrorCallback, NULL ) );
}

Whenever an error gets raised by HOOPS Luminate, the callback gets called with all the available informations:

  1. The return code identifying the error in the first place.

  2. The calling method or function; This will point to internal HOOPS Luminate method names, but this can still provide valuable informations, and this can be also very useful to transmit this information to the HOOPS Luminate support.

  3. A relevant object address. This can point to an internal HOOPS Luminate object, or to a user object address, which was involved in raising the error.

  4. An extra expression field, that can contain a string value with the failing expression (generally used for 3rd party API calls such as OpenGL).

  5. An extra information field that can help diagnosing the error source.

  6. Extra user data that can be setup using RED::IResourceManager::SetErrorCallback.

In addition to this, it’s possible to gather a text file that dumps all errors produced by HOOPS Luminate. For this simply create a ‘redsdk_error.txt’ file in the current folder of the application. This file will concatenate all errors produced by HOOPS Luminate. This file will be filled with all error informations, regardless of the existence of an error callback or not being set in the application.

Please note that if repeated errors arise (for instance a non critical error that happens every rendered frame), the size of the ‘redsdk_error.txt’ file may grow up quickly. So please don’t forget to remove this file once the problem has been diagnosed.

The folder in which the “redsdk_error.txt” file is written to can be setup using RED::IResourceManager::SetErrorFilePath.