How to API Trace

Support for running, installing or compiling OpenMW

Before you submit a bug report for the first time, please read: Bug reporting guidelines
Post Reply
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

How to API Trace

Post by Ravenwing »

I've been trying to help AnyOldName3 diagnose a problem with the shadows branch and had to run an APITrace for him. As I'm sure many besides me also don't know how to run one, here's a short guide on how to do so. If anyone wants to add to the wiki, feel free, but it's pretty low on my list of priorities, so I probably won't be doing it. This is Windows specific, but hopefully will help others as well.

APITrace is a set of tools that will record all the graphics related calls OpenMW makes. This makes it easier to diagnose a problem as someone can read through exactly what the engine was trying to do at the time of a problem.

You can download APITrace here: http://apitrace.github.io/

In the download, find the binary in:

Code: Select all

...\apitrace-msvc\x64\bin\qapitrace.exe
The trick is to add this to your system paths so you can run it directly from PowerShell.
Do that by following this guide and adding the path up to ...\bin to Paths.

Now all you have to do is open PowerShell. Change your working directory to the location of openmw.exe using the "cd" command. For example:

Code: Select all

cd "G:\Program Files\OpenMW 0.44.0"
Quotes are necessary if you have spaces in your path. PowerShell should now reflect that you're in this directory. Now simply type:

Code: Select all

qapitrace.exe
The GUI for APITrace should now be open and you can make a new trace by going to new and selecting openmw.exe as the application. No arguments are needed. This will open OpenMW, but may take longer than normal. Then simply go through and recreate your graphics issue in game. Once you exit, the trace will be automatically saved to the OpenMW folder you were working in.

You can send this to whoever asked for it so they can try and diagnose the issue. Be warned, it's much larger than most places will allow you to post, so I had to make a shared folder on Google Drive and send him the link.

Hope this helps!

EDIT BY ANYOLDNAME3: Some of the information in later posts in this thread is helpful, too. Read all the posts.
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: How to API Trace

Post by AnyOldName3 »

Note: if you only think you're ever going to have to do this a few times, it might be easier to add APITrace to the system path variable from within PowerShell just for that one session with

Code: Select all

$env:Path = "path\to\apitrace;$env:Path"
Also, you can open PowerShell directly in a specific folder by holding shift and right-clicking on some empty space within the folder, then selecting "Open PowerShell window here"
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: How to API Trace

Post by Ravenwing »

Good info, thanks AnyOldName3! Although I suspect I’ll be able to use it to help in the future. If anyone else has any suggestions, feel free to post them here!
User avatar
silentthief
Posts: 456
Joined: 18 Apr 2013, 01:20
Location: Currently traversing the Ascadian Isles

Re: How to API Trace

Post by silentthief »

Powershell is a win 10 thingy, right? Or is that something that win 7 can do?

ST
User avatar
Lagahan
Posts: 47
Joined: 16 Aug 2014, 11:24
Location: Ireland

Re: How to API Trace

Post by Lagahan »

silentthief wrote: 03 Dec 2018, 16:05 Powershell is a win 10 thingy, right? Or is that something that win 7 can do?
Windows 7 has Powershell 2.0 built in, I believe its 4.0 or 5.0 by default Windows 10. You could probably run this from command prompt as well though if the .exe for APITrace was in your environment path.
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: How to API Trace

Post by AnyOldName3 »

The only difference between how this would work with CMD and PowerShell is that where PowerShell uses

Code: Select all

$env:Path = "path\to\apitrace;$env:Path"
CMD uses

Code: Select all

set PATH=path\to\apitrace;%PATH%
One of the updates for Windows 10 changed the default from CMD to PowerShell, but for basic tasks like this, there's not much difference between them.
User avatar
lysol
Posts: 1513
Joined: 26 Mar 2013, 01:48
Location: Sweden

Re: How to API Trace

Post by lysol »

I made this thread a sticky for future viewers.
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: How to API Trace

Post by AnyOldName3 »

I just realised this thread is missing some important information. APITraces can get very big, very quickly, so try and keep them short. Make a save where the issue is already visible or can be made visible quickly, skip the intro videos, and quit the game as fast as you can, too. It makes it easier to look through the trace and can be the difference between a 15 MB trace and a gigabyte one.
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: How to API Trace

Post by AnyOldName3 »

APITrace has a couple of changes that make it easier to use since this guide was written, so I'm going to write some new instructions and hopefully someone on the PR side can make them user-friendly and re-add the context the current instructions have so we can stick them in the first post.
  • Start by making sure you can reproduce the issue quickly. Traces can be big, and get bigger the longer they are and the more calls per frame. Tips include:
    • Having a save game where the issue can be seen from the first frame after loading.
    • Skipping the intro videos with Esc, loading a save quickly, and quitting as quickly as possible once the issue's happened.
    • Disabling settings that make the trace big like the water shader, shadows or a high view distance (unless obviously the issue is with the water shader, shadows, or a high view distance).
    • Disabling mods that make the trace big, like texture and mesh replacers (unless obviously the issue's with that mod).
    • Changing the resolution won't make the trace smaller, so it's good to stick to 1080p as that's the easiest for a developer to work with.
  • Download and extract APITrace from the link in the first post.
  • Don't bother adding it to the system path anymore.
  • Run QAPITrace.exe just like you'd run any other program.
  • Click File/New.
  • Make sure API is set to GL.
  • Click on the three dots next to the Application box to browse for openmw.exe.
  • Copy and paste the directory openmw.exe is in from the Application box to the Working directory box, e.g. if Application says C:\Program Files\OpenMW 0.47\openmw.exe, Working directory should say C:\Program Files\OpenMW 0.47.
  • Press OK to run OpenMW through APITrace.
  • Reproduce the issue and quit OpenMW.
  • Upload the trace somewhere. You might need to use a cloud storage provider like Google Drive, Dropbox or Mega as they're usually above the attachment size limit for most messaging services.
Post Reply