Troubleshooting

First, see Contact Us for more information about how to contact us.

Problem Reproduction

If you believe that you’ve encountered a bug in the Visualize software, it is important that you provide a reproducible test case to Developer Support. In the vast majority of cases, we need to debug into a reproducible test case in order to fix a bug.

The most efficient way to report a bug is through our support website. The Problem Report Template should be filled out so that we have a clear sense of your expectations, and one of the following tools should ideally be used to provide a test case:

A customized ‘simple’ app: Visualize includes simple example applications such as the mfc_sandbox and qt_sandbox projects. If you have a dataset and an associated sequence of operations, you can modify the application’s “OnUserCode” slots.
Code generation: Visualize provides code-generation support. Please ensure that your code-gen is based on the minimum sequence of applications steps and the smallest possible dataset or scene-graph which reproduces the problem.

Performance Concerns

Performance concerns generally arise when results are not matching expectations, and therefore, the initial focus is to review the performance that you are expecting.

There are a wide variety of factors that influence performance. Some areas are under the control of Visualize, such as how efficiently it traverses a given scene graph, or the efficiency with which the Visualize drivers leverage GPU capabilities. Other factors lie in the hands of the application developer, such as how your application code is interacting with the scene graph, what rendering options are in use, etc. Finally, the graphics hardware itself may have limitations in terms of how it supports certain render modes and visual attributes, such as textures, transparency, shadows, and anti-aliasing.

If you have reviewed your usage per the guidelines above and feel that HOOPS Visualize has a performance issue which is preventing better GPU throughput, please submit your performance expectations, test dataset(s), reproduction steps, or sample code.

Generic vs 3D API Specific Problems

Generic problems are those that occur with more than one Visualize driver or on more than one graphics card, and typically reside in the Visualize software. We’ll attempt to reproduce the problem, and potentially target a fix depending on the severity.

Not all problems reside in the Visualize software, but rather in the lower-level 3D graphics API layer or graphics hardware. Here are some guidelines about how to identify and potentially workaround such issues:

Does the problem occur with only one Visualize 3D-API driver type:

yes:

does it appear to occur with a specific GPU?

yes: This is most likely a bug in the GPU vendor's driver implementation and will be logged as a '3rd Party Bug'. An alternate 3D Visualize driver should be used as a workaround. See Section 2.0 below for suggestions about offering your end users a way to choose between different Visualize 3D-API drivers.
no: This is potentially a Visualize bug. Tech Soft Developer Support may attempt to reproduce and further investigate depending on severity. An alternate 3D Visualize driver should be used as a workaround.

no:

does it appear to occur with a specific GPU?

yes: This is most likely a bug in the GPU vendor's driver implementation and will be logged as a '3rd Party Bug'. Depending on severity, a potential workaround may be investigated. See Section 2.0 below for suggestions about offering your end users a software-only fallback to workaround any severe graphics-card issues.
no: This is likely to be a generic Visualize software bug, and may be targeted for correction in an upcoming Service Pack depending on severity.

If you cannot reproduce a 3D-API specific problem or cannot provide a reproducible test case to Developer Support, you should use an alternate 3D Visualize driver to potentially address the issue (Section 2.0 below). If that does not help, you can refer to the Runtime Diagnostics section below, which may further troubleshoot the problem. Please be aware that there may be situations where a GPU or driver-specific issue cannot be addressed. For example, the following situations may occur:

the end user updates their graphics card driver and finds no improvement
using an alternate 3D driver doesn’t address the problem
neither you nor Tech Soft Developer Support are able to reproduce the problem (only your end-user can reproduce)
the problem is due to a ‘3rd Party Bug’ and there is no workaround

Application Settings

HOOPS Visualize is designed to maximize rendering performance while producing consistent rendering results across different 3D-API interfaces, GPUs, and operating systems. Visualize is tested on a wide range of graphics cards to ensure that Visualize’s own 3D API interfaces covered in the Device Guide function properly. The list of cards are contained on the Graphics Devices page. However, capabilities, reliability, and performance may still vary depending on the 3D API interface being used, along with the end user’s GPU.

GPUs may contain defects in their lower-level drivers, firmware, or hardware. Attempts are made to workaround such flaws whenever possible, but unavoidable problems may still exist. The guidelines below will help you provide flexibility to your end users.

Automatic Driver Setting

We strongly recommend that you set your Visualize driver to HPS::Window::Driver::Default3D for your on-screen viewports, which instructs Visualize to automatically choose the best 3D driver supported by the operating environment.

Manually Selecting a Driver

While HOOPS Visualize will automatically select a 3D driver using the above HPS::Window::Driver::Default3D setting, we suggest that you also provide your end users with the ability to manually select one of the supported Visualize 3D-API drivers (OpenGL2, DX11, etc…), via a driver pull-down list. This offers your end users greater runtime flexibility to potentially work around 3D-API or GPU-specific problems. You can call HPS::ApplicationWindowOptionsControl::ShowDriver to determine which driver was selected by HOOPS Visualize.

Runtime Diagnostics

Driver Configuration Files

One method of responding to issues with a problematic graphics card is to use a driver configuration file, which Developer Support may provide for certain cases. This file must be specified using HPS::World::SetDriverConfigFile prior to creating the driver:

SetDriverConfigFile("C:\\driver_config.txt");

Code Generation

Users typically only enable code generation in coordination with a Tech Soft 3D support engineer, as a part of the process of resolving a customer-reported bug. Our support staff will, in this case, contact the customer with detailed instructions on how to obtain code generation for their case and how to submit it to Tech Soft 3D.

Code generation works by logging calls to every HPS public function made during the execution of an application. As a result, a reduction in performance is expected while code generation is active. Code generation is activated using the second argument in the HPS::World constructor. For example:

HPS::World::World _world(HOOPS_LICENSE, in_code_generation_directory);

The in_code_generation_directory argument represents the directory where code generation will output files. The directory should already exist before calling the HPS::World constructor.

Code generation will be automatically turned off when Visualize exits. It can also be turned off explicitly by calling the HPS::World::StopCodeGeneration function.

To minimize the amount of output, we suggest that you turn off code generation immediately after the problem occurs in your application.

You can add strings that will show up in the code generation as comments by calling the HPS::World::AddCodeGenerationComment function. This is useful to help pinpoint the start of a problem area.

After code generation terminates, the output directory will contain a number of files. It will always contain the following files: codegen_main.h, codegen_main.cpp and cg.cpp. Additionally, it may contain more cg_#.cpp files, depending on how long your code generation is.

The user should send all the contents of the output code generation directory to support, including any files which were loaded into HOOPS Visualize while code generation was active.

Limitations of Code Generation

There are a few limitations to be aware of:

Customers using the D3DImage driver cannot take advantage of the code generation feature at this moment. (The generated code would draw to an offscreen window in this case). They can change their driver type while running code generation if possible, to get around this limitation.
Issues which are not rooted within the HPS::Object core library (for example, a bug in one of our sprocket modules) will not be directly caught by code generation.
Issues which are due to data races might not be reproduced by code generation.