Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/icculus/altrace

An OpenAL debugging tool.
https://github.com/icculus/altrace

debugger debugger-visualizer openal

Last synced: 3 months ago
JSON representation

An OpenAL debugging tool.

Awesome Lists containing this project

README 

        
# alTrace



This is a tool for debugging OpenAL applications and implementations. It

lets you record, playback, and visualize an OpenAL call stream.



# Quick start:



- This work is funded by my Patreon! If you like it,

  [throw in a buck](https://patreon.com/icculus/)!

- 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](https://cmake.org/) to build. If you want the GUI,

  you'll need [wxWidgets](https://wxwidgets.org/). 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:

   ```sh

   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:

  ```sh

  altrace_cli MyGameName.altrace

  ```

- Want to see _everything_ we recorded, including state changes and OpenAL

  errors and such? Try --dump-all ...

  ```sh

  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.

  ```sh

  altrace_cli --run MyGameName.altrace

  ```

- If you built altrace_wx, you can run that for a GUI that lets you visualize

  the data:

  ```sh

  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: [email protected]



Thanks!



--ryan.