Debugging

In the course of application development, you might encounter unexpected behavior while interacting with the HOOPS/3dGS library. To facilitate debugging activities, HOOPS provides several mechanisms for further investigation of the situation. In system options, you can turn on code generation with the function Define_System_Options("code generation=on"). When this setting is enabled, HOOPS Visualize tracks all the calls to 3dGS functions and creates a trace file from it. The file, named code.c, is a compilable C program that lists the calls made to HOOPS Visualize in sequential order. Note that code generation may create more than one file in which case you would see files with the names code[#].c. One way to keep your trace files organized is to set the “code generation directory” option. This driver option lets you specify where HOOPS Visualize should create the trace files. The following code snippet shows how to enable code generation.

    HC_Define_System_Options("code generation=on");

If you would like to insert comments at specific places in the call stack, you can use the “code generation comment” option. Simply call Define_System_Options with the “code generation comment” option set to your comment as seen the code sample below:

    HC_Define_System_Options("code generation comment= 'Inserting circle'");
    HC_Insert_Circle(point1, point2, point3);

The “code generation” and “code generation comment” options help you get a clearer idea of what may be generating the unexpected behavior. Another piece of information that can also facilitate the debugging process is examining the state of the HOOPS database in a readable file format. To do this, call Write_Metafile. You can pass in a file name and a number of options like “follow cross-references” and “save state”. By default, the metafile will be written to the current directory. If you want to specify a specific location for your metafiles, you can call Define_System_Options and set the “metafile directory” option with a directory path.

    HC_Write_Metafile(".", "MyScene.hmf", "save state=texture, follow cross-references");

The sample code above shows a call to Write_Metafile requesting that the currently open segment and its children be written out to a file called MyScene.hmf. The “save state=texture” option requests that HOOPS write the name of defined textures while “follow cross-references” tells HOOPS to write out included segments instead of simply writing their names.