• Technical Overview
  • Release Notes
  • Programming Guide
  • Reference Manual
  • HOOPS Visualize
TechSoft3d

HOOPS Visualize Troubleshooting Guide

1.0 Troubleshooting

  • 1.1 Problem Reproduction
  • 1.2 Performance Concerns
  • 1.3 Generic vs 3D-API Specific Problems

2.0 Application Settings

  • 2.1 Agnostic Driver Setting
  • 2.2 Manually Selecting a Driver
  • 2.3 Software Mode

3.0 Runtime Diagnostics

  • 3.1 Graphics Hardware Analysis
  • 3.2 Driver Configuration Files

 


1.0 Troubleshooting

1.1 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, support.techsoft3d.com. 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: Each HOOPS/GUI module includes a simple example application. If you have a dataset and an associated sequence of operations, you can modify the application's 'Run My Code' slots.
  • HOOPS Partviewer: When reporting a problem via the Partviewer, provide a list of 'Options' settings, a set of steps that will reproduce the problem, and a minimal dataset or scene-graph that reproduces the problem.
  • Code generation: The HOOPS/3DGS component 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.

1.2 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 are experiencing unreasonable performance, please consider the following areas:

  • Review Section 7.0 Performance Guidelines. Many performance issues are due to the scene graph containing an excessive number of segments compared to the number of graphical primitives, which can result in low GPU throughput and poor performance relative to what is expected. The performance guidelines review appropriate rendering settings, scene graph structure, and optimization settings.
  • Use the HOOPS Partviewer to explore your scene-graph structure via the segment browser, and test different rendering settings such as display lists, culling, and transparency options.
  • Use the Partviewer's "Test Performance" menu option to experiment with different drivers.

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), Partviewer reproduction steps, or sample code.

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

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

2.1 Agnostic Driver Setting

We recommend that you set your Visualize driver to '3d_driver' (available beginning in v20), which instructs Visualize to automatically choose the best 3D driver supported by the operating environment. Visualize will query the 3D capabilities on the end user's graphics card at runtime to help ensure that Visualize can provide maximum performance and leverage the full 3D API capabilities. See the Device Guide for more details on '3d_driver'.

Prior to v20, you may have grown accustomed to starting up the Visualize-based application with a specific 3D driver, perhaps assuming that a specific driver is the most stable or 'best' driver because application QA was performed using driver. However, the results of such testing are typically confined to a very small number of GPUs, and may not be indicative of the wider experience among end users. Additionally, as implied up above in the '3d_driver' notes, manually selecting a specific driver prevents Visualize from assessing the capabilities of the hardware. This could inhibit advanced rendering capabilities or performance benefits which would otherwise be supported by more current Visualize 3D drivers. In summary, the '3d_driver' setting is a benefit meant to insulate you from the runtime capabilities of the graphics-card

2.2 Manually Selecting a Driver

While HOOPS Visualize will automatically select a 3D driver using the above 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, DX9, etc...), via a driver pull-down list. This offers your end users greater runtime flexibility to potentially workaround 3D-API or GPU-specific problems. You can call Show_Device_Info and request the value for 'driver type' to determine which driver was selected by HOOPS Visualize.

2.3 Software Mode

You can instruct Visualize to perform software-only rendering, which you could also include as a choice in the aforementioned 'driver pull-down'. Performance will be greatly reduced when using software-only rendering, but it is graphics card independent and will allows an end user to workaround any severe problems/failures on their graphics card which may otherwise be unavoidable.

Software mode is supported via either the OpenGL or DX11 drivers. It is enabled by calling Define_Driver_Config, passing "opengl" or "dx11" as the driver, and specifying a configuration of FORCE_DEFAULT_SOFTWARE prior to creating your OpenGL or DX11 driver. For example:

HC_Define_Driver_Config("opengl","*","*","config=FORCE_DEFAULT_SOFTWARE");

Once this has been set up, you must create all driver instances under the "/driver/opengl/" or "/driver/dx11/" segment to remain in software mode.

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
  • the problem is due to a '3rd Party Bug' and cannot be worked around
  • the end user may have a laptop, and therefore, the problem cannot be isolated by swapping the GPU

In such cases, falling back to software-only rendering is typically the only way to address the issue, albeit at the cost of rendering performance.

3.0 Runtime Diagnostics

3.1 Graphics Hardware Analysis

If you or an end-user experiences a severe problem which appears to be GPU-specific as outlined above in Section 1.3, and you cannot provide Developer Support with a reproducible test case, runtime diagnostics may assist us with troubleshooting the issue and providing a workaround. Severe problems may include a crash, severely incorrect rendering result, or very poor performance. However, please recall that these issues are often identified as 3rd Party Bugs in the GPU's vendor-supplied drivers, and we make no guarantees that a workaround can be provided.

HOOPS Visualize comes with a graphics hardware analysis utility. This is a stand-alone executable that can be shipped with your application, or you may choose to provide it as-needed if an end user encounters a GPU-specific problem which neither your nor Tech Soft can reproduce. It is means of collecting some additional information about the graphics card in use. There is a version for each commercially supported 3D driver. The executable name follows this pattern:

gfx_hardware_analysis_<driver>_<hoops version>.exe

The graphics validator utility can be run with additional options. Please read the gfx_hardware_analysis_readme.txt for more details.

When the executable is run, a series of windows will appear in which a suite of graphics tests will be performed. When the program completes, the results of the tests will be written into a log file with a naming convention that follows this pattern:

gfx_hardware_analysis_<driver>_<hoops version>.txt

This file will be created in the same directory where the executable resides. This log file can be sent to Developer Support for further examination, and we will review whether there may be a workaround to the problem.

Note that the graphics card validator utility only runs on Microsoft Windows platforms.

3.2 Driver Configuration Files

If an end user experiences irregular or unstable behavior with your application, the diagnostic tools mentioned in the previous section *may* help with identifying the underlying issues. Once the diagnostic information is collected, we will consider whether you may be able to help your end user workaround problems.

One method of responding to issues with a problematic graphics card is to use a driver configuration file, which Developer Support may provide to you. This file is loaded during HOOPS initialization if the system option Define_Driver_Config set,as seen in the example below:

HC_Define_System_Options("driver config file = C:\\driver_config.txt");

You can also have your end user specify the above string via an environment variable called HOOPS_SYSTEM_OPTIONS. This is probably the most useful, since Visualize will read this value at runtime, and the Visualize-based application that already resides on the end user machine does not need to be modified.

In the sample above, the entire path and filename is specified. Visualize expects the driver configuration file to be a plain text file containing a list of entries that specify for a given driver, graphics card and version combination whether a set of options should be enabled or disabled. The available options correspond to the arguments that the Define_Driver_Config function takes.