Two forms of the RenderWare library are available. The retail version, with which all final, retail quality systems should be linked and the debugging version which aids in the development of RenderWare applications.
Although slower than the retail version, the debugging version performs more error checking and issues messages to alert the application programmer to potential problems. A set of API functions are provided to control the type of tracing and debugging information generated. In the retail version of the library, these functions are simply null operations. Applications can, therefore, switch between debugging and production libraries by simply re-linking or, for DLL users, by simply switching DLLs.
Debugging messages are associated with three levels of severity:
The above are listed in ascending order of severity. The items in the list correspond to values (rwINFORM, rwWARNING, and rwERROR) of the enumerated type RwDebugSeverity. The messages dispatched to the debugging stream may be filtered according to their severity by setting the minimum severity level. For example, setting the severity level to rwWARNING would filter out informational messages whilst retaining warning and error messages.
There are four categories of debugging messages:
All messages share the following format:
RW
<severity level> [xx:yyyy:RwFunctionName] <text
of the message>
The <xx:yyyy> is a code comprising a two- and four-digit number. This code is of no significance to the application programmer, but is informative to RenderWare’s technical support staff when investigating problems. If the function generating the message is a RenderWare API function then the function name will also appear in the message. All other internal functions will have a reported name of RwInternal.
I. Assertion Failure Messages
These messages report the failure of assertions made within the library functions. For example, the RwCreateCamera() function asserts that its maximum width and height arguments should have positive values. If either the width or height is negative the assertion fails and a message is issued.
An assertion failure message takes one of the following two forms:
RW INFORM
[xx:yyyy:RwCreateCamera] ASSERT FAILED
RW WARNING
[xx:yyyy:RwCreateCamera] ASSERT FAILED
Assertion failure messages can have either informational or warning level severity.
Assertion failure messages are informative to RenderWare’s technical support staff but contain no significant information for the application programmer.
Note that the execution of an API function continues after the detection of an assertion failure. The debugging version of the library behaves in the same way as the standard version.
II. Scripting Trace Messages
These messages trace the parsing of a script file. This is useful in finding problems in script files that fail to load.
The format of a scripting trace message is:
RW INFORM
[xx:yyyy] SCRIPT Line <line number>: Parsing
<scripting keyword>
For example:
RW INFORM
[12:3324] SCRIPT Line:25 Parsing ClumpEnd
Note that scripting trace messages always have severity level rwINFORM.
III. Miscellaneous Messages
Several of the debugging and tracing messages (including all API level errors) fall into this category. Two examples are:
RW ERROR
[15:8463:RwSetLightBrightness] E_RW_INV_LIGHT: Invalid
light type passed to library function
RW INFORM
[92:3425:RwCurrentMatrix] RwCurrentMatrix is obsolete.
Please use RwScratchMatrix.
Miscellaneous messages can be of any severity level. API level error messages are always at severity level rwERROR.
The above message classes can be enabled or disabled individually or collectively. By default, assertion failure and miscellaneous messages are enabled whilst script trace messages are disabled.
IV. API Function Tracing Messages
These messages trace function calls made to the RenderWare library. A message for each entry into and for each exit from an API function is produced.
Example API function tracing messages are:
RW INFORM
[92:3425:RwCurrentMatrix] ENTER
RW INFORM
[92:3425:RwCurrentMatrix] EXIT
Note that API function tracing messages always have severity level rwINFORM.
Some example scenarios for controlling debugging messages are given below:
Scenario 1: Report Everything
RwSetDebugSeverity(rwINFORM);
RwSetDebugOutputState(rwENABLE);
Scenario 2: Report Only API-level Errors
RwSetDebugSeverity(rwERROR);
RwSetDebugOutputState(rwENABLE);
Scenario 3: Report Only Script Tracing Information
RwSetDebugSeverity(rwINFORM);
RwSetDebugAssertionState(rwDISABLE);
RwSetDebugMessageState(rwDISABLE);
RwSetDebugTraceState(rwENABLE);
Scenario 4: Report All Warnings and Errors
RwSetDebugSeverity(rwWARNING);
RwSetDebugOutputState(rwENABLE);