Skip to content

Using Apitrace

Jump to bottom
Robin Kertels edited this page Apr 27, 2024 · 2 revisions

Apitracing a game

This guide in detail describes how to create an apitrace capture of a game, which can be very useful for debugging purposes.

On Linux

  • Check whether the game is 64-bit or 32-bit.

To determine that on Linux, use file command in the terminal:

file /path/to/executable/program.exe

where /path/to/executable/ is an an actual location of the game's EXE file and program.exe is its actual name. If the game is 32-bit, you will see this in the output

PE32 executable (GUI) Intel 80386, for MS Windows

And if it's 64-bit, you will get this instead:

PE32+ executable (GUI) x86-64, for MS Windows

  • Open winecfg and add a native,builtin override for d3d9, d3d11 and dxgi.dll. Here's a GIF that showcases the process:

Peek 2020-04-09 17-32

  • Download prebuilt apitrace files:

If the game is 32-bit

https://github.com/apitrace/apitrace/releases/download/11.1/apitrace-11.1-win32.7z

And if it's 64-bit

https://github.com/apitrace/apitrace/releases/download/11.1/apitrace-11.1-win64.7z

  • Extract the archive.
  • Now you have to copy the appropriate d3d9.dll, d3d11.dll, dxgi.dll and dxgitrace.dll files.

If the game is 32-bit, choose the files located in

apitrace-msvc/x86/lib/wrappers

And if it's 64-bit, choose the file located in

apitrace-msvc/x64/lib/wrappers

  • Now copy those DLL files into the same folder as the game's .EXE.
  • Before the next step, make sure you disable or get rid of DXVK files first, as it's preferred that you use WineD3D to make an apitrace.
  • Launch the game and try to reproduce your issue as fast as possible, then exit the game after that (using ALT+F4 is fine).
  • Locate the .trace file. If you've done everything correctly, in wine, you can usually find it in /path/to/prefix/drive_c/users/USERNAME/Desktop, where /path/to/prefix is the location of your Wine prefix and USERNAME is your username in the system. The file should have the size of at least a few hundred megabytes (or at least one hundred if the game is very simple), quite often it's a few gigabytes. If the size is way less than that (like a few bytes or kilobytes) and/or the game crashed during the tracing process, then it means it's is not really traceable, at least on Linux. Make sure you mention this.
  • Compress the .trace file by either utilizing apitrace repack --brotli=2 <input>.trace <output>.trace (can be done with the Linux version) or with an external tool in a common file format like .tar.xz. Then share it using a common file sharing service like Google Drive or Mega. Don't use Firefox Send and other temporary file sharing services, as the link to the file may expire before the person it was made for can download it.

Once you've successfully created an apitrace, you can delete the apitrace dll files from the game folder and set the dll overrides back to n,b.

On Windows

If you have access to Windows, it's best that you perform the tracing on it rather than on Linux.

  • Check whether the game is 64-bit or 32-bit. To do that on Windows, right-click on the executable file you want to check, select “Properties”, then click the tab “Compatibility”.

If the first Windows version in the list is "Windows Vista", then it means the game is 64-bit.

If you see older Windows versions in that menu, like "Windows 98", then the game is 32-bit.

  • Download prebuilt apitrace files:

If the game is 32-bit

https://github.com/apitrace/apitrace/releases/download/11.1/apitrace-11.1-win32.7z

And if it's 64-bit

https://github.com/apitrace/apitrace/releases/download/11.1/apitrace-11.1-win64.7z

  • Extract the archive.
  • Now you have to copy the appropriate d3d9.dll, d3d11.dll, dxgi.dll and dxgitrace.dll files.

If the game is 32-bit, choose the files located in

apitrace-msvc/x86/lib/wrappers

And if it's 64-bit, choose the file located in

apitrace-msvc/x64/lib/wrappers

  • Now copy those DLL files into the same folder as the game's .EXE.
  • Launch the game and try to reproduce your issue as fast as possible, then exit the game after that (using ALT+F4 is fine).
  • The .trace file should be located on your Desktop.
  • Locate the .trace file. If you've done everything correctly, you can usually find it on your desktop. The file should have the size of at least a few hundred megabytes (or at least one hundred or so if the game is very simple), quite often it's a few gigabytes. If the size is way less than that (like a few bytes or kilobytes) and/or the game crashed during the tracing process, then it means it's is not really traceable, at least on Linux. Make sure you mention this.
  • Compress the .trace file by either utilizing apitrace repack --brotli=2 <input>.trace <output>.trace or with an external tool (like 7zip) in a common file format like .zip. Then share it using a common file sharing service like Google Drive or Mega. Don't use Firefox Send and other temporary file sharing services, as the link to the file may expire before the person it was made for can download it.

Advanced capturing via hooking the game exe

Some games don't load the apitrace DLLs from their working directory, so you can use apitrace to hook the graphics API you are interested in instead with the following command:

apitrace.exe trace -a <API> <game.exe>

Advanced capturing for games not loading local DLLS via path overrides

Some programs prevent apitrace DLLs to be loaded from next to their executable or directly load system DLLs. This means we have to put apitrace into the system folder, but this prevents apitrace from loading a proper DirectX implementation since it will try to load itself. Luckily apitrace has a feature to set a custom folder from which the DirectX DLLs will be loaded.

Be sure to use the appropriate architecture for the DLLs and the corresponding system folder. On 64bit Wine prefixes system32 corresponds to the 64bit and syswow64 to 32bit files.

Create a <custom_folder> somewhere which will contain the appropriate d3d9.dll, d3d11.dll, dxgi.dll, etc files. These can be Wine's stub DLLs copied from your prefix's system32/syswow64 folders or DXVK's DLLs, depending on the trace requirements. After preparing the <custom_folder> it is time to place the apitrace DLLs into the right system folder.

With all these preparations done its time to trace! All you have to do is to set the correct DLL overrides as described in the previous section and to export the following environment variable then can run your game and get a trace file from it.

export APITRACE_FORCE_MODULE_PATH="/home/<path_to>/<custom_folder>"

wine /path/to/executable/program.exe
Clone this wiki locally