=========
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.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0006.cpp
		   :start-after: //! [code_generation1]
		   :end-before: //! [code_generation1]

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:  

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0006.cpp
		   :start-after: //! [code_generation2]
		   :end-before: //! [code_generation2]

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.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0006.cpp
		   :start-after: //! [write_metafile]
		   :end-before: //! [write_metafile]

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.
