Graphic engine debugging

From SIMboxWiki
Jump to navigation Jump to search

During the course of product development, one may encounter situation in which extra help is required to debug the developed product. The graphic engine contains many functions that allow for easier debugging. This is especially true for debugging issues concerned with AGIs.

The graphic engine debugging functions are accessible through the graphic engine settings API. Note that most of the settings listed here are advanced settings. Clicking the show advanced options may be necessary to locate some of these settings.

TriD

Show stats

One of the most commonly used debugging setting is the Debug \ Show Stats parameter. Setting the value of this parameter to true will display rendering status information. This information includes: framerate, polygon count and batch count.

TriD debug operation

Located under Debug \ TriD \ Debug Operation this parameters allows printing various logs on created objects or cameras of information The debug operation:

Log objects
Once selected, the graphic engine will log (into a file) information on all the existing 3D models currently loaded in the graphic engine. Information will include the model id, name, location, size, visibility, and whether they are attached to other objects.
The log file containing this information will be saved to c:\temp\TriDDebug-Objects.log.
Log effects
Once selected, the graphic engine will log (into a file) all the existing effects. The log file will contain information such as: id, location, state and parent object.
The log file containing this information will be saved to c:\temp\TriDDebug-Effects.log.
Log cameras
Once selected, the graphic engine will log (into a file) all existing camera information. The log file will contain information such as: id, location, type, terrain load status and clipping information.
The log file containing this information will be saved to c:\temp\TriDDebug-Cameras.log.

AGI

Locating AGIs

Sometimes you may find that AGIs you've created are difficult to locate. This can be caused because of clip regions, bad surface locations or a badly constructed console.

Debug \ Console \ Show console
Setting this option to false will hide the 3D model of the console. Making it easier to see the AGIs you've constructed.
Debug \ Agi \ Enable clip regions
Setting this option to false will disable all clip region. Any part of an AGI that is hidden by a clip region will reappear. AGIs defined as clip regions will appear as normal geometric AGI objects.

AGI debug operations

Similar to the TriD the AGI system also has a debug operation settings. This settings allows for 2 main functions. Exploring the AGI system structure and data. And, triggering breakpoints to debug certain AGI calls.

The setting for controlling the debug operation is called Debug \ AGI \ Debug Operation. Another setting that is sometimes used in conjunction with it is the settings Debug \ AGI \ Debug Param.

AGI structure exploration

The following options are used to explore the AGI system structure and data. Most do this by writing to log files.

Note that certain options here are affected by the AGI batching system. This means that several AGIs are combined together. In this case each batch will be represented by a single AGI from within the batch.

To turn the batching system off set the advanced setting Agi \ Batching \ Batching Technique to none. Note that setting this option will decrease framerate.

Log entire hierarchy
When selected a log of all AGIs in the system will be saved to a file under c:\temp\AgiDebug-VisibleHeirarchy.log. This log will contain information such as: id numbers, names, rendering values, and more. The file will be structured in a way that shows the hierarchy in which the AGIs are arranged.
Log visible hierarchy
When selected, a log of the AGI tree being processed for rendering will be saved to a file under c:\temp\AgiDebug-VisibleHierarchy. Note that this will include the entire heirarchy that the graphic engine goes through including elements which are not rendered, such as abstracts, canvases or gauge AGIs.
The format of the file will be similar to the one saved by the log-entire-hierarchy option.
Log Drawn
When seleted, the system will log AGIs that are being rendered by the system. Unlike the log visible hierarchy option, only renderable AGIs will be included in the log file. The log file will be saved under c:\temp\AgiDebug-Drawn.
Note that this option is influenced by the AGI batching system.
Log dangling
When seleted, the system will log all AGIs that are not attached to any surface or cockpit. Meaning, AGIs that do not take part in the rendering process. This log file will be saved under c:\temp\AgiDebug-Dangling.
This feature can be used to locate resource leaks caused by improperly deleted AGIs.
Log textures
When selected, the system will log all textures in the AGI system. The log will also include on which AGIs are using which textures. This log file will be saved under c:\temp\AgiDebug-Textures.
Flicker AGI
When selected, the system will toggles an AGIs visibility on and off. The AGI to be toggled will be the AGI whose id is set in the companion setting "debug param". This feature will allow identifying AGIs being rendered.
Note that this feature is influenced by the AGI batching system.

Breakpoint triggers

The following options allow the developer to produce breakpoint for certain conditions. When a breakpoint condition is met the graphic engine will produce a message box announcing that fact and asking whether to break the program. If you intend to break the program you must attach a debugger at this point. Failing to do so will cause the simulation to crash.

It is important to note that some of the options here are only useful if AGI id assignment is consistent between runs. This is how the system works. As long as the same AGIs are created between runs, they will receive the same ids.

Break on create
Setting this function will trigger a breakpoint once an AGI of a given id is created. The AGI id for which this breakpoint is triggered can be set in the debug param setting.
Break on join scene
Setting this function will trigger a breakpoint once an AGI of a specific id is added to the scene. The AGI id for which this breakpoint is triggered can be set in the debug param setting. Note that the breakpoint may be triggered even in cases in which the AGI is not added by its own id to the rendering hierarchy. For example, if an AGI has a parent that is being attached to the rendering hierarchy, the breakpoint can be triggered both for that AGI and it's parent.
Break on detach from scene
Similar to break on join scene but for detach operations
Break on delete
Setting this function will trigger a breakpoint once an AGI of a specific id is deleted. The AGI id for which this breakpoint is triggered can be set in the debug param setting. Note that the breakpoint may be triggered even in cases in which the AGI is not deleted by its own id. For example, an AGI being deleted will delete all child AGIs attached to it that do not have other parents. This can trigger breakpoints, in the process, for the child AGIs.
Break on show
Setting this function will trigger a breakpoint if a an AGI with its visibility turned off is set to on. The AGI id for which this breakpoint is triggered can be set in the debug param setting.
Break on hide
Setting this function will trigger a breakpoint if a an AGI with its visibility turned on is set to off. The AGI id for which this breakpoint is triggered can be set in the debug param setting.
Break on invalid attach
Similar to break on invalid call but only for function calls to Agi::Add.
Break on invalid call
When set, any call to an AGI function with an id of an AGI that does not exist in the system will trigger a breakpoint. The purpose of this option is to locate AGI function calls that use uninitialized parameters. If your system shows random AGI behavior where AGI disappear unexpectedly, it is likely you are dealing with a problem of uninitialized parameters. This option can be used to locate and fix such coding issues.