Debugging Applications#

The first step in debugging a PowerVR Framework application should always be to examine the log output. There are assertions, warnings, and error logs that should help find many common issues.

Exceptions#

All errors that are caught by the application will raise an exception. All exceptions inherit from a common base class, itself inheriting from std::runtime_error.

On a debug build, if a debugger is present and supported (such as when executing the application from an IDE) all PowerVR exceptions will cause a debugger break similar to a breakpoint immediately in their constructor. This makes it possible to immediately examine the situation and call stack where the exception was thrown.

In any case, if a std::runtime_exception is not caught anywhere else, it will be caught by PVRShell, and the application will quit. Its message (what()) will be displayed as a pop up with windowing systems, or a logged message with command line systems.

Additionally, API specific tools should be used to help identify a bug or other problem.

OpenGL ES#

OpenGL ES applications are usually debugged as a combination of CPU debugging and PVRTrace/PVRCarbon or other tools in order to trace and play back commands.

Vulkan/PVRVk#

The Vulkan implementation of the PowerVR Framework is thin and reasonably simple. Apart from CPU-side considerations like lifetime, API level debugging should be very similar to completely raw Vulkan. However, the complexity of the Vulkan API makes debugging not very easy in general.

The most important consideration here are the Vulkan Layers.

Layers#

Vulkan Layers sit between the application and the Vulkan implementation, performing many types of validation. They can be enabled globally (for example, in the registry) or locally (for example, in application code). PVRUtilsVk automatically enables the standard validation layers for debug builds. These provide invaluable information for debugging.

Check the LunarG Vulkan SDK for the default layers. They are valuable in tracking many kinds of incorrect API use. It is good practice to:

  • Inspect the log for any errors. This includes layers output on platforms that have them.

  • Inspect the Vulkan layers and fix any issues found, until they are clear of errors and warnings.

  • Continue with other methods of debugging such as the API dump layer, CPU or GPU debuggers, PVRCarbon, or any other method suitable to the error.