This is a tool for debugging OpenAL applications and implementations. It lets you record, playback, and visualize an OpenAL call stream.
- This work is funded by my Patreon! If you like it, throw in a buck!
- This is all brand new code, if something looks obviously broken it probably is. At this time, it definitely works on my computer, so feel free to come by and try it at my house if you have problems.
- This works on macOS and Linux (and other Unix systems, probably). Windows is currently unsupported (but can be in the future!).
- You'll need CMake to build. If you want the GUI, you'll need wxWidgets. The command line tools and trace recorder does not need wxWidgets. I built this with wxWidgets 3.0; if you're on macOS, you'll want to use at least 3.1 or Mojave's Dark Mode won't work.
- Build the thing with CMake:
cd altrace mkdir cmake-build cd cmake-build cmake -DCMAKE_BUILD_TYPE=Release .. make
- You'll end up with a libaltrace_record.so (or .dylib) file. Take that and make your game use it. It's a drop-in replacement for your usual OpenAL library, so either link against it directly, or dlopen it, or force it to load over the usual OpenAL with LD_PRELOAD.
- When your game runs, alTrace will write out a tracefile (something like
MyExecutableName.altrace
, or*.1.altrace
,*.2.altrace
, etc). Any time your game talks to OpenAL, the details are logged to the tracefile. - When you're done, quit your game.
- You can see the list of OpenAL calls made by your game and their results
with the command line tool:
altrace_cli MyGameName.altrace
- Want to see everything we recorded, including state changes and OpenAL
errors and such? Try --dump-all ...
altrace_cli --dump-all MyGameName.altrace
- (there are other command lines to make this less of a firehose, if you only want some specific pieces of information. Run altrace_cli with no arguments to see the list.)
- Want to replay the tracefile? This will run the same function calls back
through OpenAL (possibly a different OpenAL implementation, if you're into
that sort of thing). This is useful if you want to debug OpenAL itself and
want to ditch all the game logic and get a reproduction case: just run
altrace_cli under a debugger. :) Otherwise, someone can send you a
tracefile when your game, unrelated to the OpenAL implementation, got into
a weird state and you want to hear what happened.
altrace_cli --run MyGameName.altrace
- If you built altrace_wx, you can run that for a GUI that lets you visualize
the data:
altrace_wx MyGameName.altrace
- Need more clarity into the data? alTrace exposes an OpenAL extension that lets you label objects, annotate the stream of function calls, and group sections of calls together, so your app can cooperate to make the information more user-friendly.
- Future plans: support for more OpenAL extensions (mostly this is just core OpenAL 1.1 right now), Windows support, more features in the GUI, more help on tracking down problems, etc.
- Questions? Bug reports? Hit me up: icculus@icculus.org
Thanks!
--ryan.