(Download) ApiTrace 1.0: OpenGL and Direct3D Trace Generator and Analyzer

ApiTrace 1.0: OpenGL and Direct3D Debugger

ApiTrace is a major evolution of glretrace. glretrace is a tool to trace OpenGL (GL 2, 3 and 4) and Direct3D (D3D 8, 9, 10) API calls. There is a wrapper for each API (opengl32.dll, d3d9.dll, etc.) and to use glretrace, just place the right right wrapper in the folder of your application (I compiled the OpenGL wrapper, you can download it farther in this post 😉 ). The wrapper will generate a big trace file which can be viewed using a command line tool called tracedump.exe.

ApiTrace is a Qt-based graphical user interface (GUI) for glretrace. And according to José Fonseca, the father of glretrace, ApiTrace is not a simple GUI:

And recently Zack Rusin offered to write a QT-based GUI for glretrace, also on his personal time. Warning: this GUI is not the cherry on top of the cake, it’s the whole sugar coating and it will make you salivate like a rabid dog! It allows to view the traced calls, view the state (parameters, shaders, textures, etc) at any call, and edit the calls, and more. Pretty amazing stuff, useful both for GL users and implementers, and I’m sure Zack will write up about it very soon.

The trace file can be viewed with tracedump.exe or with the GUI. The GUI allows the following things:

  • inspect the state frame by frame, draw call by draw call
  • replay the trace file
  • check every bound texture, framebuffer, vertex buffer or shader
  • see if OpenGL threw an error at any point during the replay and if so what was it
  • edit any shader, any uniform and large chunks of the state to immediately see the effects it would have on the rendering
    • ApiTrace 1.0: OpenGL and Direct3D Debugger

      More information about ApiTrace can be found HERE.

      You can download the source code of ApiTrace here: ApiTrace @ github. There is no binary so to make our life a bit easier, I compiled the project and packed all glretace files (I don’t have Qt in my system so no GUI for the moment).

      glretrace pack

      You can download the glretrace pack here:

      Notes for the compilation:

      1 – I have vs2005 and oddly the function DebugMessage() in os_win32.cpp generates an error because of the IsDebuggerPresent() function (part of the Win32 API). I don’t have the time to see why vs2005 does not find this function so I just put in comment the related code.

      2 – In glretrace_gl.cpp, some functions are useless like the following one, due to the return keyword that is a bit misplaced:

      static void retrace_glNamedBufferDataEXT(Trace::Call &call) {
          GLuint buffer;
          buffer = call.arg(0);
          GLsizeiptr size;
          size = call.arg(1);
          GLvoid * data;
          data = 0; // FIXME
          GLenum usage;
          usage = call.arg(3);
          if (retrace::verbosity >= 0)
              std::cerr << "warning: unsupported call glNamedBufferDataEXT\n";
          glNamedBufferDataEXT(buffer, size, data, usage);

      As you can see, glNamedBufferDataEXT() will be never called.

      But the trick is that glretrace_gl.cpp is generated by the retace.py Python script. In this script you can find a function called fail_function() that is the guilty:

      def fail_function(self, function):
          print '    if (retrace::verbosity >= 0)'
          print '        std::cerr << "warning: unsupported call %s\\n";' % function.name
          print '    return;'

      I just modified this function by adding a pair of {}:

      def fail_function(self, function):
          print '    if (retrace::verbosity >= 0) {'
          print '        std::cerr << "warning: unsupported call %s\\n";' % function.name
          print '    return; }'

      With this mod, the function glNamedBufferDataEXT() in retrace_glNamedBufferDataEXT() is now reachable. The OpenGL wrapper available in the pack comes with this fix.

5 thoughts on “(Download) ApiTrace 1.0: OpenGL and Direct3D Trace Generator and Analyzer”

  1. horte

    To keep the IsDebuggerPresent() feature

    add this line in CmakeList.txt Line 43

    add_definitions (-D_WIN32_WINNT=0x0400 )

  2. Toto

    I don’t understand why they don’t offer official Windows binaries. It’s so simple for the developer, and saves so much troubles for the user!

  3. Gaming

    I’d like to request a Direct3D -> OpenGL wrapper. Should be possible using this tool, I believe. Thanks.

  4. Jose Fonseca

    I’m one of the co-authors of this tool, and I’m glad to see it caught your interest.

    @Geeks3d: Regarding notes for compilation, the early return statement is there as a safeguard because the “data” parameter is not being captured properly in the trace (note the “FIXME” comment). Your change will work if data is NULL, but to handle cases where data is non-zero it is necessary to change “data” arg in glNamedBufferDataEXT’s description in glapi.py from an opaque pointer to a blob, so that the wrapper writes the bytes being passed in that argument.

    GL API (including extensions) is massive — apitrace already knows about around 2000 GL functions — but there are several cases it doesn’t record enough information to replay.

    I’ve pushed a commit that fixes glNamedBufferDataEXT’s, and I’ll try to get other GL_EXT_direct_state_access functions in shape. I don’t know any app that uses GL_EXT_direct_state_access, so if you still run into problems then please file an issue about it on github.

    @Toto: I hope to distribute Windows binaries eventually, but neither me or Zack have been developing the GUI on Windows. I just need to get an devel environment setup.

    @Gaming: API conversion is beyond the scope of this tool. One day we might support Direct3D retracing, but Microsoft PIX does that already, so there’s little incentive. For Direct3D -> OpenGL wrapper see http://www.nongnu.org/wined3d/

  5. shuker

    In the picture, we can see a list of opengl api call, so I want to know whether we can dump the model in an opengl application? thank you!

Comments are closed.