apitrace

apitrace

apitrace is a tool used for OpenGL debugging.

Installation

Linux

Install apitrace using default package manager:

sudo apt install apitrace apitrace-gui
sudo ln -sf /usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/ /usr/bin/

QtWebEngine embedded in Webots (to display the robot windows and the offline documentation) may cause issues to interpret the apitrace results and/or imply crashes when running apitrace. Therefore, it is better to run Webots with the --disable-gpu argument, and to disable the initialization of QtWebEngine using the following patch:

diff --git a/src/webots/gui/WbDocumentation.cpp b/src/webots/gui/WbDocumentation.cpp
index d091aba38..3b8034043 100644
--- a/src/webots/gui/WbDocumentation.cpp
+++ b/src/webots/gui/WbDocumentation.cpp
@@ -113,6 +113,8 @@ WbDocumentation::WbDocumentation(QWidget *parent) : WbDockWidget(parent), mWebVi
   setTabbedTitle("Documentation");
   setObjectName("Documentation");
 
+  return;
+
   mWebView = new DocumentationWebView(this);
   setWidget(mWebView);
 
@@ -129,6 +131,7 @@ WbDocumentation::~WbDocumentation() {
 }
 
 void WbDocumentation::open(const QString &book, const QString &page, bool visible) {
+  return;
   /*
   // Debug code: uncomment to show a web inspector for QtWebKit.
   static QWebInspector *inspector = NULL;
diff --git a/src/webots/gui/WbMainWindow.cpp b/src/webots/gui/WbMainWindow.cpp
index f42bc04af..c1e41fd82 100644
--- a/src/webots/gui/WbMainWindow.cpp
+++ b/src/webots/gui/WbMainWindow.cpp
@@ -97,7 +97,7 @@
 #ifdef _WIN32
 #include <QtWebKit/QWebSettings>
 #else
-#include <QtWebEngineWidgets/QWebEngineProfile>
+// #include <QtWebEngineWidgets/QWebEngineProfile>
 #endif
 
 #include <wren/gl_state.h>
@@ -1291,7 +1291,7 @@ void WbMainWindow::updateAfterWorldLoading(bool reloading, bool firstLoad) {
 #ifdef _WIN32
   QWebSettings::globalSettings()->clearMemoryCaches();
 #else
-  QWebEngineProfile::defaultProfile()->clearHttpCache();
+  // QWebEngineProfile::defaultProfile()->clearHttpCache();
 #endif
   WbRenderingDeviceWindowFactory::reset();
   restorePerspective(reloading, firstLoad, false);

Typical command to run apitrace:

cd $WEBOTS_HOME
export LD_LIBRARY_PATH=$(pwd)/lib/webots
apitrace trace ./bin/webots-bin --disable-gpu --mode=pause
qapitrace webots-bin.1.trace

Windows

Download the precompiled apitrace build from https://people.freedesktop.org/~jrfonseca/apitrace/apitrace-msvc-latest.7z and extract it in your software folder.

Then, add the following line to the end of your PATH in your .bash_profile:

~/software/apitrace-msvc/x64/bin

Now you can launch apitrace with apitrace.exe and the gui with qapitrace.exe.

macOS

Install Qt5 as documented here: https://github.com/cyberbotics/webots/wiki/Qt-compilation (note, you can skip QtWebKit and only install the macOS Qt component in the installer).

Then:

cd ~/software
git clone git://github.com/apitrace/apitrace.git
cd apitrace
mkdir build
cd build
cmake ..  -DCMAKE_PREFIX_PATH=~/Qt5.11.2/5.11.2/clang_64/
make
echo '[Paths]
Prefix = /Users/[your username]/Qt5.11.2/5.11.2/clang_64' > qt.conf

Run:

export QT_QPA_PLATFORMTHEME=qt5ct  # On Mojave, forcing the Qt light theme.
export VENDOR=AMD  # On MacBook Pro 2018, select the right GPU.
qapitrace ....

Usage

Generate a trace like this: apitrace trace [Webots executable]

Then open the Trace in the GUI to view results for each call, or each frame etc.

Note: in the preferences you can choose to only display draw events, this is very helpful to cut through extraneous OpenGL calls while debugging.