Skip to content

Commit ee46737

Browse files
fredemmottfredemmott
committed
Reorder README
1 parent dff8072 commit ee46737

File tree

1 file changed

+109
-108
lines changed

1 file changed

+109
-108
lines changed

‎README.md‎

Lines changed: 109 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,109 @@
1-
# OpenXR-Tracing
2-
3-
Windows [Trace Logging] ([ETW]) as an OpenXR API layer.
4-
5-
## Prebuilt binaries
6-
7-
Prebuilt binaries are available in [the latest release](https://github.com/fredemmott/OpenXR-Tracing/releases/latest).
8-
9-
You may need to install the latest Microsoft C++ runtime libraries:
10-
11-
- x86: https://aka.ms/vs/17/release/vc_redist.x86.exe
12-
- x64: https://aka.ms/vs/17/release/vc_redist.x64.exe
13-
14-
## Dependencies
15-
16-
- **Python**: installing from the MS store or `winget` should be fine.
17-
18-
Python is used to generate most of the code of this project, based on the OpenXR specification; the API specification is an XML file, and the OpenXR SDK source includes Python classes for processing this XML file.
19-
20-
- **Visual Studio 2022, C++ compilers, and clang tools**
21-
22-
## Building
23-
24-
1. Open "x64 Native Tools Command Prompt for VS 2022" (or "x86 Native Tools ...."); **DO NOT** use "Developer Powershell for VS xxxx" or "Developer Command Prompt for VS xxxx"
25-
2. `cd /path/to/your/checkout`
26-
3. Fetch submodules: `git submodule update --init`
27-
4. Run `pwsh ./build.ps1`
28-
29-
`build.ps1` supports two flags:
30-
- `-Clang`: use `clang-cl.exe` instead of `cl.exe`
31-
- `-SkipCodegen`: don't create or update the `gen/` directory
32-
- `-SkipCompile`: create or update the `gen/` directory, but don't build
33-
34-
## Usage
35-
36-
Two API layers are generated:
37-
- `XR_APILAYER_FREDEMMOTT_OXRTracing`
38-
- `XR_APILAYER_FREDEMMOTT_OXRTracing_Alternate`
39-
40-
These are identical, except for the name, which is included in the trace data; this allows tracing both sides of another OpenXR API layer.
41-
42-
Each of these layers has its' own DLL and json file in `out\` after building; uou may want to disable the layer when you're not actively using this layer - it has not been optimized for performance.
43-
44-
### Enabling the layers
45-
46-
You can manually add the .json file to the registry like any other layer, or use `install.ps1` and `wrap.ps1` as administrator. You might find [list-openxr-layers] handy.
47-
48-
With administrator powershell:
49-
50-
install.ps1 -Mode First
51-
52-
Or, last:
53-
54-
install.ps1 -Mode Last
55-
56-
You can also install the layer immediately `Before` or `After` another layer:
57-
58-
install.ps1 -Mode Before -RelativeTo C:\Path\To\Other\APILayer.json
59-
60-
You can `Enable`, `Disable`, or `Remove` the layer:
61-
62-
install.ps1 -Mode Disable
63-
64-
You can install both layers, on either side of another layer:
65-
66-
wrap.ps1 -RelativeTo C:\Path\To\Other\APILayer.json
67-
68-
To change the secondary layer (or any other API layer):
69-
70-
install.ps1 -Mode Disable -LayerPath (Get-Item out\APILayer_Alternate.json).FullName
71-
72-
### Collecting trace data
73-
74-
To start collecting data, as administrator:
75-
76-
wpr -start OXRTracing.wprp -filemode
77-
78-
To finish collecting data and write an ETL file:
79-
80-
wpr -stop MyTraceFile.etl
81-
82-
If you're looking for an event log rather than profiling information, I recommend [Tabnalysis].
83-
84-
## Rationale
85-
86-
While the OpenXR SDK source does include a dumping layer:
87-
88-
- OpenXR-Tracing produces ETL files; tools for ETL files like Tabnalysis and Windows Performance Analyzer are designed to deal with extremely large amounts of structured data, and work much better than browsers for this
89-
- OpenXR-Tracing produces more detailed information, such as:
90-
- both string and handles are shown for `XrPath`, `XrAction`, and `XrActionSet`
91-
- arrays are walked, e.g. composition layers, subaction paths
92-
93-
![example output from hello_xr.exe](screenshot.png)
94-
95-
On the other hand, the layer included with the OpenXR SDK source has some advantages:
96-
97-
- OpenXR-Tracing uses Windows-specific features, so can not be used on other platforms
98-
- OpenXR-Tracing currently will not handle invalid structs well, and may crash
99-
100-
## License
101-
102-
This project is [MIT licensed](LICENSE)
103-
104-
[list-openxr-layers]: https://github.com/fredemmott/list-openxr-layers/releases
105-
[Trace Logging]: https://learn.microsoft.com/en-us/windows/win32/tracelogging/trace-logging-portal
106-
[ETW]: https://learn.microsoft.com/en-us/windows/win32/etw/about-event-tracing
107-
[Tabnalysis]: https://apps.microsoft.com/store/detail/tabnalysis/9NQLK2M4RP4J
108-
1+
# OpenXR-Tracing
2+
3+
Windows [Trace Logging] ([ETW]) as an OpenXR API layer.
4+
5+
## Why?
6+
7+
While the OpenXR SDK source does include a dumping layer:
8+
9+
- OpenXR-Tracing produces ETL files; tools for ETL files like Tabnalysis and Windows Performance Analyzer are designed to deal with extremely large amounts of structured data, and work much better than browsers for this
10+
- OpenXR-Tracing produces more detailed information, such as:
11+
- both string and handles are shown for `XrPath`, `XrAction`, and `XrActionSet`
12+
- arrays are walked, e.g. composition layers, subaction paths
13+
14+
![example output from hello_xr.exe](screenshot.png)
15+
16+
On the other hand, the layer included with the OpenXR SDK source has some advantages:
17+
18+
- OpenXR-Tracing uses Windows-specific features, so can not be used on other platforms
19+
- OpenXR-Tracing currently will not handle invalid structs well, and may crash
20+
21+
22+
## Prebuilt binaries
23+
24+
Prebuilt binaries are available in [the latest release](https://github.com/fredemmott/OpenXR-Tracing/releases/latest).
25+
26+
You may need to install the latest Microsoft C++ runtime libraries:
27+
28+
- x86: https://aka.ms/vs/17/release/vc_redist.x86.exe
29+
- x64: https://aka.ms/vs/17/release/vc_redist.x64.exe
30+
31+
## Dependencies
32+
33+
- **Python**: installing from the MS store or `winget` should be fine.
34+
35+
Python is used to generate most of the code of this project, based on the OpenXR specification; the API specification is an XML file, and the OpenXR SDK source includes Python classes for processing this XML file.
36+
37+
- **Visual Studio 2022, C++ compilers, and clang tools**
38+
39+
## Building
40+
41+
1. Open "x64 Native Tools Command Prompt for VS 2022" (or "x86 Native Tools ...."); **DO NOT** use "Developer Powershell for VS xxxx" or "Developer Command Prompt for VS xxxx"
42+
2. `cd /path/to/your/checkout`
43+
3. Fetch submodules: `git submodule update --init`
44+
4. Run `pwsh ./build.ps1`
45+
46+
`build.ps1` supports two flags:
47+
- `-Clang`: use `clang-cl.exe` instead of `cl.exe`
48+
- `-SkipCodegen`: don't create or update the `gen/` directory
49+
- `-SkipCompile`: create or update the `gen/` directory, but don't build
50+
51+
## Usage
52+
53+
Two API layers are generated:
54+
- `XR_APILAYER_FREDEMMOTT_OXRTracing`
55+
- `XR_APILAYER_FREDEMMOTT_OXRTracing_Alternate`
56+
57+
These are identical, except for the name, which is included in the trace data; this allows tracing both sides of another OpenXR API layer.
58+
59+
Each of these layers has its' own DLL and json file in `out\` after building; uou may want to disable the layer when you're not actively using this layer - it has not been optimized for performance.
60+
61+
### Enabling the layers
62+
63+
You can manually add the .json file to the registry like any other layer, or use `install.ps1` and `wrap.ps1` as administrator. You might find [list-openxr-layers] handy.
64+
65+
With administrator powershell:
66+
67+
install.ps1 -Mode First
68+
69+
Or, last:
70+
71+
install.ps1 -Mode Last
72+
73+
You can also install the layer immediately `Before` or `After` another layer:
74+
75+
install.ps1 -Mode Before -RelativeTo C:\Path\To\Other\APILayer.json
76+
77+
You can `Enable`, `Disable`, or `Remove` the layer:
78+
79+
install.ps1 -Mode Disable
80+
81+
You can install both layers, on either side of another layer:
82+
83+
wrap.ps1 -RelativeTo C:\Path\To\Other\APILayer.json
84+
85+
To change the secondary layer (or any other API layer):
86+
87+
install.ps1 -Mode Disable -LayerPath (Get-Item out\APILayer_Alternate.json).FullName
88+
89+
### Collecting trace data
90+
91+
To start collecting data, as administrator:
92+
93+
wpr -start OXRTracing.wprp -filemode
94+
95+
To finish collecting data and write an ETL file:
96+
97+
wpr -stop MyTraceFile.etl
98+
99+
If you're looking for an event log rather than profiling information, I recommend [Tabnalysis].
100+
101+
## License
102+
103+
This project is [MIT licensed](LICENSE)
104+
105+
[list-openxr-layers]: https://github.com/fredemmott/list-openxr-layers/releases
106+
[Trace Logging]: https://learn.microsoft.com/en-us/windows/win32/tracelogging/trace-logging-portal
107+
[ETW]: https://learn.microsoft.com/en-us/windows/win32/etw/about-event-tracing
108+
[Tabnalysis]: https://apps.microsoft.com/store/detail/tabnalysis/9NQLK2M4RP4J
109+

0 commit comments

Comments
 (0)