Intel® GPA tip: Interpreting API errors when using Intel GPA Frame Analyzer

Introduction

Saving a frame from your game for later analysis is one of the major features of Intel® Graphics Performance Analyzers (Intel® GPA). When Intel GPA creates a frame capture file, it saves the context of all Microsoft DirectX* API calls that were used to create the frame.


However, Intel GPA Frame Analyzer may report DirectX* API errors in the frame capture file, even though no errors were reported when running your game or when capturing the file. The rest of this article explains why you see these errors, and how to check whether they affect your analysis and optimization.


Situation #1 -- Playback Errors Occur when Creation and Playback Graphics Devices Are Different

First of all, we recommend that you always capture a frame and analyze it on the same platform. There are situations where performance issues on one platform may not exist on the other due to differences in the capabilities of the graphics device. For example, certain graphics operations may execute considerably faster on one platform, and in some cases  operations may be performed on the CPU instead of the GPU. Therefore, use the same device for capture and analysis so that performance "hot spots" that Intel GPA Frame Analyzer identifies reflect actual performance issues on that platform.

But if you need to capture a frame on one platform and analyze it on another, Intel GPA Frame Analyzer will print a warning message, but you do have the choice of continuing the analysis. However, you may see errors when you attempt to load that frame capture file, especially when the original graphics device has more capabilities than the device used for analyzing a specific frame. For example, when attempting to use proprietary textures or other device-specific capabilities that do not exist on the analysis platform, Intel GPA will print an error message highlighting the specific erg, which you can examine in the "API log" tab.

So here's a good "rule of thumb" if you must use a single frame capture file with multiple devices:
  • Capture the frame on the least capable device, since the more capable devices will likely provide all the capabilities of the original device.
  • Avoid using a frame capture file created on one vendor's system with another vendor's system, since it is more likely that they have various features and special unique capabilities that are not available across architectures.

Situation #2 -- Playback Errors are Expected and Can Be Ignored

The application code may make DirectX* API calls that result in errors that are non-fatal when running the game. However, when that frame capture file into loaded into Intel GPA Frame Analyzer, the tool may report an error message that one or more API errors were found.

The Intel GPA development team has seen this in a couple of cases. One game attempts to use a proprietary texture format, and if that texture map creation call fails it re-creates that texture in a "standard" format. In another situation a developer want to see whether a particular graphic resource exists; she checks the return code from a DirectX* API call that attempts to use that resource, and branches depending upon the return code.

So in both of these cases the user does not see any errors, but the original DirectX* API call appears in the frame capture file. Intel GPA Frame Analyzer sees these DirectX* errors when loading the capture file, and reports this back to the user. To verify that everything worked fine, open the "API Log" tab to examine the ergs with errors -- they will be highlighted in red. If all issues are expected, just ignore them. In other cases, the error may be severe enough that Intel GPA cannot continue, in which case you will need to fix the DirectX* call in your graphics application and re-create the frame capture file.


Conclusion

In this article we've provided information on identifying and resolving issues reported when loading a frame capture file. We've made some suggestions for minimizing the likelihood of an error when the original platform and the target platform are different, and showed where to check the severity of these errors in Intel GPA Frame Analyzer.

If you still have questions on this topic, please use the Intel GPA Support Forum to ask a question or describe an issue you are having with the product. We also welcome your feedback on how to improve the product to meet your specific needs.


* Other names and brands may be claimed as the property of others.
For more complete information about compiler optimizations, see our Optimization Notice.