Warning
This is preliminary software. Don't expect anything to work. Also see issues.
As this accesses your Xbox hardware directly, it could do permanent damage. Use at your own risk, don't do anything stupid.
It is also known to be unstable and can behave randomly.
nv2a-trace
nv2a-trace is similar to apitrace, but targeting the Xbox GPU instead of desktop graphics APIs.
nv2a-trace runs remotely on a development machine. It allows you to stop your Xbox GPU command stream and inspect each GPU method before execution. It uses xboxpy to connect to a target Xbox.
nv2a-trace can dump intermediate rendering steps like this:
Currently, most output will be send to PNG files in the "out" folder. Additionally a "debug.html" will be created which shows the captured commands. This output format is a temporary solution. Eventually there'll be one of the following:
- GUI, and tracing and UI will be largely decoupled.
- Parsable output ASCII format which automatically acts as UI.
There is currently no parsable trace-file output, and replaying traces is not possible.
Usage
This project uses xboxpy. Please read its documentation to find out how to install and configure it for your Xbox.
Afterwards, you can run these commands:
git clone https://github.com/XboxDev/nv2a-trace.git
cd nv2a-trace
python3 -u nv2a-trace.py
The last line will run nv2a-trace and connect to your Xbox. It will automatically start tracing.
This tool may also (temporarily) corrupt the state of your Xbox. If this tool does not work, please retry a couple of times.
Contributing
This project uses Black for automatic formatting.
You can use the pre-commit in the githooks directory to reformat any changes on commit
or run the tool manually prior to creating a PR. In cases where you feel readability is
significantly better with manual formatting, you may surround the code with
# fmt: off / # fmt: on comments, but this should be a rare exception.
(C) 2018 XboxDev maintainers