Utilities
gpa-injector
Usage:
gpa-injector [--target-application,-t] <target app> [--layer <layer name>][--working-directory,-w <working directory>] [-- <target argument>...]
--device-override <int>
Force use of a specific graphics device. Use "gpa-help --layer device-override"
to list available devices. This option loads the device-override gpa layer.
--disable-ac-detector
If provided, disables anti-cheat detector module (enabled by default).
--disable-io-redirect
If provided, disables standard input output redirection (enabled by default).
--disable-key-events If provided, disables publishing of keyboard events (enabled by default).
-K --enable-keyframes Enable keyframes (disabled by default). This feature is deprecated and will be removed in the 2023.1 release. Use deferred capture and gpa-subcapture-recorder.exe instead.
-e --exit-after-frame <int>
Exit process after reaching target frame index.
-h --help Print this help information
--hook-api <string> Comma separated list of apis to hook; valid gfx APIs: all, vulkan, opengl, opencl, d3dall, d3d10, d3d11, d3d12 (default: all)
--injection-mode <int>
0 - SetThreadContext, 1 - CreateRemoteThread (default: SetThreadContext)
-L --layer <string> Name of layer to insert; layers are inserted in order appearing on
command line (possible layers: api-debug, capture, logging,
hud-layer, screenshot, validation). Default: no layers.
Optional key value pairs can be provided to the layer
--layer name[:key=value,...]. Maximum length of args to any single
layer is 512 characters. Example: gpa-injector --layer capture:directory=\my-streams,name=my-stream
-l --log-file <string> Direct logging output to the specified file instead
of console (default: console-only).
"#PROC" replaced by attached process name
"#PID" replaced by attached process PID number
-v --log-level <string> Set log output severity level; valid values are: trace, debug,
info, warn, error, fatal (default: info)
-m --log-mask <string> Comma separated list of modules to filter in: generic, page-tracker
-p --page-tracker-mode <int>
0 - default, 1 - disabled, 2 - Use shadow buffer approach for
managed Metal buffers, 3 - Force shadow buffer approach for all
--skiplist-file <string>
A path to the skip-list txt file that
stores process names to skip during the injection.
-t --target-application <string>
The workload to capture
-V --version Print version and build info to the console, then exit
--waitfordebugger <string>
Waits for user input after injecting to a process of specified name.
Use "all" to wait on every new process. Provide process name without extension.
-w --working-directory <string>
Path to the working directory for the target application.
To use custom layers, set GPA_LAYER_PATH in your environment
to point to the location where the layers are installed.
This must be a properly formatted absolute path
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line args are missing or invalid
gpa-player
Usage: gpa-player [options] <stream filename>
Options:
-d --delimiters <string>
Set the list of range delimiter(s) in the format 'api:class::function'. The list of tokens are delimited by commas. Example: Metal:MTLCommandBuffer::presentDrawable,Vulkan:vkQueuePresentKHR (default: null)
--device-override <int>
Force use of a specific graphics device. Use "gpa-help --layer device-override" to list available devices. This option loads the device-override gpa layer.
--disable-pso-filtering
Create all pipeline state objects captured in stream. Pipeline state objects filtering is enabled by default.
--disable-sync-resolving
Disable command queue deadlocks resolving during playback.
--enable-cross-gpu Run player in cross GPU compatibility mode, this option requires additional time for pre-processing and not 100% guaranteed valid playback on another hardware.
-e --exit-after-frame <int>
Exit process after reaching target frame index.
-f --first-frame <int> Play only this frame, the number of times specified in repeat-count
-h --help Print this help information
-F --last-frame <int> Ignored if 'frame' option is not present; if set and valid, this option defines the last 'frame' in a multi-frame range to be played (and potentially repeated if 'repeat-count' is set). 'last-frame' must be strictly greater than 'frame'.
-l --log-file <string> Direct logging output to the specified file instead of console (default: console-only)
-v --log-level <string> Set log output severity level; valid values are: trace, debug, info, warn, error, fatal (default: info)
-o --offscreen Playback without visible window
--old-rtx-patching Forces old raytracing patching code path.
-p --parallel Switches the default Sequential mode into parallel producer->consumer with 100k API_Calls in the ring buffer.
-c --parallel_count <int>
Defines how many API_Calls to keep in the ring buffers. 100k if not set.
-s --play-from <int> Start at this percentage into the stream
--post-layer <string>
Name of layer to insert; post-layers are inserted after the implicit playback layer.
Default: no layers. See gpa-injector --layer argument description (--help) for more detail.
--pre-layer <string> Name of layer to insert; pre-layers are inserted before the implicit playback layer.
Default: no layers. See gpa-injector --layer argument description (--help) for more detail.
-r --repeat-count <int> Repeat playback of the selected frame this many times; only valid if 'frame' is specified
-V --version Print version and build info to the console, then exit
--waitfordebugger Waits for user input before start of playback
To use custom layers, set GPA_LAYER_PATH in your environment
to point to the location where the layers are installed.
This must be a properly formatted absolute path
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line args are missing or invalid
gpa-subcapture-recorder
Usage: subcapture-recorder [options] <stream filename>
Options:
-d --delimiters <string>
Set the list of range delimiter(s) in the format 'api:class::function'. The list of tokens are delimited by commas. Example: Metal:MTLCommandBuffer::presentDrawable,Vulkan:vkQueuePresentKHR (default: null)
--device-override <int>
Force use of a specific graphics device. Use "gpa-help --layer device-override" to list available devices. This option loads the device-override gpa layer.
--directory <string>
--disable-filtering Records restoration data for all the objects live at subcapture range start. Only objects actively used in the subcapture range are recorded by default
--enable-compression Stream data compression with LZ4 algorithm
--enable-cross-gpu Run player in cross GPU compatibility mode, this option requires additional time for pre-processing and not 100% guaranteed valid playback on another hardware.
-h --help Print this help information
--insert-virtual-present
Inserts artificial 'Present' call to mark state restoration as frame 0 in deferred and subcaptured stream. Default: false.
NOTE: This option offsets counting by 1 frame during playback. For example, frame 2 during capture will be referenced as frame 3.
-l --log-file <string> Direct logging output to the specified file instead of console (default: console-only)
-v --log-level <string> Set log output severity level; valid values are: trace, debug, info, warn, error, fatal (default: info)
--name <string>
-f --object-filtering [obsolete - enabled by default] Records restoration data for only for objects used in the subcapture range
-o --offscreen Playback without visible window
--old-rtx-patching Forces old raytracing patching code path. Option works only with disabled object filtering. Disabled by default for object filtering.
--post-layer <string>
Name of layer to insert; post-layers are inserted after the implicit playback layer.
Default: no layers. See gpa-injector --layer argument description (--help) for more detail.
--pre-layer <string> Name of layer to insert; pre-layers are inserted before the implicit playback layer.
Default: no layers. See gpa-injector --layer argument description (--help) for more detail.
-s --subcapture-range <string>
-V --version Print version and build info to the console, then exit
--waitfordebugger Waits for user input before start of playback
To use custom layers, set GPA_LAYER_PATH in your environment
to point to the location where the layers are installed.
This must be a properly formatted absolute path
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line args are missing or invalid
EOF
gpa-stream-info
Usage: gpa-stream-info.exe [options] <stream>
Displays stream information.
Options:
--csv Display only the header data in comma-separated tabular format
-h --help Print this help information
-k --key <string> Display only the value corresponding to the provided header key
-V --version Print version and build info to the console, then exit
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line args are missing or invalid
4: Data was found, but is corrupted or otherwise unreadable
gpa-stream-analyzer
Usage: gpa-stream-analyzer.exe [options] <stream>
Displays capture-time performance metrics (i.e. cpu_frame_ms) as a labeled csv data table
Options:
-d --duration <int> Stop after the specified number of frames (disabled by default: 0)
-f --frame <int> Start with the specified frame (default: 1)
-h --help Print this help information
-V --version Print version and build info to the console, then exit
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line args are missing or invalid
4: Data was found, but is corrupted or otherwise unreadable
gpa-cpp-generator
Usage: gpa-cpp-generator.exe <stream> [options]
Generates C++ source/project files for Stream playback using explicit API calls.
Options:
--directory <string> Generate output files into the specified directory (default: <stream>)
--disable-argument-literals
Setup call arguments using state buffers instead of literal values
-d --duration <int> Limit the generated C++ API calls to a specified number of frames (defaults to remaining frames: 0)
-f --frame <int> Generate explicit C++ API calls, starting with the specified frame ordinal (defaults to the first frame: 1)
-h --help Print this help information, then exit
-l --log-level <string> Set log output severity level; valid values are: trace, debug, info, warn, error, fatal (default: info)
-m --max-callables-per-file <int>
Split frames that contain more than the specified number of callables into separate source files. (default: 1000)
--offscreen Disable generation of source to needed to display visible window of final frame(s)
-V --version Print version and build info to the console, then exit
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
2: Execution failed with 'File Not Found'
3: One or more command-line arguments are missing or invalid
4: Data was found, but is corrupted or otherwise unreadable
gpa-help
Usage: gpaframework/bin/Release/gpa-help [options]
Display help information related to the GPA Framework.
Options:
-H --help Print this help information, then exit
--layer <string> Display help for the named layer (see --layers)
--layers Display a list of layer names, then exit
--markdown Display layer help in markdown format
-V --version Print version and build info to the console, then exit
Possible return codes:
0: Execution completed successfully and without error
1: Execution failed with unspecified error
3: One or more command-line args are missing or invalid
gpa-metrics-collector
Usage: gpa-metrics-collector.exe <stream path> --frame-index <index of frame in stream> [options]
Tool used to collect performance metrics from graphics calls in a frame of interest of a
previously captured stream. By default, it determines the minimal set of collection ranges that
span as many graphics calls in the frame as possible, and then collects and prints out the
available metrics for all of those ranges.
Note: The required parameters <stream path> and --frame-index can be placed in any order relative
to any options that are specified.
-f|--frame-index <int> Frame index to collect metrics from. The first frame (index
zero) is not supported. Must be in the range
[1, number of frames in stream).
Options:
-a|--api-debug-layer Enables the API debug layer during metrics collection.
-c|--csv <string> Output collected metrics to a CSV file rather than to the console
that is saved to the directory where the tool is located.
<string> can be one of the following:
- Path and file name of the CSV file to create/overwrite.
- A period character (".") to indicate that a default file name
should be generated for the CSV file based on the name of the
stream with a date and timestamp appended to it.
- A dash character ("-") to indicate that instead of a file, the
normal CSV output should be written to STDOUT.
Also generates a metadata file with the same basename as the CSV file
and a suffix/extension of .meta.txt, unless suppressed by the
--no-metadata option or the CSV output is written to STDOUT.
-e|--per-event Delimit graphics call collection ranges, that are used to measure
metrics, at GPU event boundaries (such as draw, dispatch, copy, resolve,
clear, ...). This option takes precedence over --per-pass.
-g|--gpu-index <int> Index of GPU to use for metrics collection. Note that the GPU
indices below may be different than those used by the
device-override layer.
<GPU indices will be displayed here on the platform used>
-h|--help Show only help info and exit app.
-m|--metrics-list <string> Explicit listing of metrics groups and/or individual metrics to
collect. If this option is not provided, the default is for all
metrics to be collected. The supported syntax is:
<string> <collection>(;<collection>)*
<collection> <group-name-metrics>|
<group-symbol-metrics>|
<group-names>|<group-symbols>|
<metrics-names>|<metrics-symbols>
<group-name-metrics> group:"<group-name>"((#(<metric-names>|<metric-symbols>))|(#!))+
<group-symbol-metrics> groupSymbol:"<group-symbol"((#(<metric-names>|<metric-symbols>))|(#!))+
<group-names> group:"<group-name>"(,"<group-name>")*
<group-name> An individual metric group name from the
current list of those available.
<group-symbols> groupSymbol:"<group-symbol>"(,"<group-symbol>")*
<group-symbol> An individual metric group symbol from the
current list of those available.
<metric-names> name:"<metric-name>"(,"<metric-name>")*
<metric-name> An individual metric name from the current
list of those available.
<metric-symbols> symbol:"<metric-symbol>"(,"<metric-symbol>")*
<metric-symbol> An individual metric symbol from the
current list of those available.
Notes:
- The --show-metrics option can be used to determine all of the
available metric groups (symbols and names) and their associated
metrics (symbols and names) that can be can be specified, for a
specific GPU, graphics API and the current graphics driver
version. All of them are case sensitive.
- For <group-names> and <group-symbols>, all of the individual
metrics contained in all of the metric groups listed will be
collected. If only a sub-grouping of metrics is desired, use
the <group-name-metrics> or <group-symbol-metrics> syntax.
- For <metrics-names> and <metric-symbols>, all of the individual
metrics listed will be collected in all of the metric groups
that contain them. If only a single instance of a metric is
desired, use the <group-name-metrics> or <group-symbol-metrics>
syntax.
- For <group-name-metrics> and <group-symbol-metrics>, specifying
a pound/hash sign then an exclamation mark ("#!") will exclude
all of the metrics names and/or metric symbols listed from those
collected in the specified metric group. Otherwise, only those
listed are collected.
- It is possible for any <group-name>, <group-symbol>,
<metric-name> or <metrics-symbol> to contain space characters.
hence the syntax having enclosing quotes. If there are no
spaces, the enclosing quotes do not need to be provided. There
is no known <group-symbol> or <metric-symbol> with spaces.
- Only the first metrics list option (-m|--metrics-list) is
recognized when multiple are specified on the command line.
Examples:
-m name:"GPU Core Clocks"
-m name:"GPU Core Clocks","GPU Time Elapsed"
-m symbol:GpuTime
-m symbol:GpuCoreClocks,GpuTime;name:"EU Stall"
-m group:"Render Metrics Basic set"
-m group:"Render Metrics Basic set","Compute Metrics Basic set"
-m group:"Compute Metrics Basic set";symbol:PixelsRendered;group:"Render Metrics Basic set"
-m group:"Compute Metrics Basic set"#symbol:GpuBusy,GpuCoreClocks#name:"GPU Time Elapsed"
Note: In the example above, only listed metrics are included.
-m group:"Compute Metrics Basic set"#!#symbol:GpuBusy,GpuCoreClocks#name:"GPU Time Elapsed"
Note: In the example above, all listed metrics are excluded.
-m groupSymbol:RenderBasic
-m groupSymbol:RenderBasic,ComputeBasic
-m groupSymbol:ComputeBasic;symbol:PixelsRendered;groupSymbol:RenderBasic
-m groupSymbol:Sampler#symbol:GpuTime,AvgGpuCoreFrequencyMHz#name:"GPU Core Clocks"
Note: In the example above, only listed metrics are included.
-m groupSymbol:Sampler#symbol:GpuTime,AvgGpuCoreFrequencyMHz#name:"GPU Core Clocks"#!
Note: In the example above, all listed metrics are excluded.
-m groupSymbol:Sampler#symbol:SamplesWritten,SamplesBlended;symbol:PixelsRendered
Note: In the example above, all instances of the
PixelsRendered metric are included (although only one exists)
and only listed metrics in the Sampler group are included.
-n|--frame-count <int> Number of frames to collect metrics from, beginning with the frame
identified by the --frame-index option. Must be in the range [1, number
of frames in stream - index of frame in stream). Default value: "1".
--no-metadata Suppresses output of the metadata file, that is normally generated
alongside the CSV file.
-p|--per-pass Delimit graphics call collection ranges, that are used to measure
metrics at pass boundaries.
-r|--range-aggregation-for-frame-results
Aggregates the metric values for all of the ranges queried and
reports a single "frame" result value for each metric collected.
-s|--show-metrics Show only a list of the available metrics to collect, for a given
input stream on a specific GPU. Primarly for usage with metrics
filtering (-m|--metrics-list). If the logging level is info, debug
or trace, the metric description and units are also included.
-t|--transpose Transpose the output results such that graphics call collection
ranges (or frame indices when performing aggregation) are shown one per
row, and the metrics collected are shown one per column.
-u|--include-units Include column with the type of units for each metric row. The
default is for no units column.
-v|--log-level <string> Set logging output severity level. Valid values from most severe to
least (and most verbose) are: "fatal", "error", "warn", "info",
"debug", "trace". Trace level is only available on debug builds.
Default value: "warn".
-w|--wait-for-debugger When process starts, pause and prompt the user to attach a
debugger before continuing.
gpa-system-info
This utility simply prints out information about the system it is run on, there are no command line options.