Utilities
gpa-injector
Usage:
gpa-injector [--target-application,-t] <target app> [--layer <layer name>][--working-directory,-w <working directory>] [-- <target argument>...]
-a --attach Wait workload to start and attach
-C --attach-condition <string>
External cmd that returns 0 to attach, or search continues on positive (and cancells on negative) exit code. See attach-nth|regex-cmd for example. Usage: -C "attach-nth 3" OR -C "regex-cmd ^.*$" Quotes around are mandatory.
-F --attach-flavors <string>
Set of modificators for attach: "busy" - makes sure system is loaded to slow down new process starts, "snapshot" - use slower but more precise process listing, "strict" - don't attach when process went beyond 1st thread creation. Usage: -F busy+strict
--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)
--hook-d3d11on12 Intercept D3D12 calls from D3D11on12 (disabled by default). To profile Steam games with D3D11on12, make sure that steam overlay is disabled in the game settings.
--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 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. In attach mode can be wildcard.
-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-ddi-hook Disabled D3D12 DDI hook responsible for collecting RTX stateObject exports.
--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. The last valid value in the range is one less than number of frames in the stream.
-h --help Print this help information
-F --last-frame <int> Ignored if 'first-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 'first-frame'. The last valid value in the range is one less than number of frames in the stream.
-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 <int> Parallelization performance optimizations (mode 3 is recommended):
-p 1: one thread prepares draw-calls, main thread only draws them (big circular ring-buffer to achieve that).
-p 2: same as 1, but resource disposal moved to third thread.
-p 3: whole frame is prepared separately in parallel with other frames in multiple threads, but still each frame is played by main.
-p 4: same as p3 but every frame is played right in the thread that prepared it (serialized between threads to ensure order)
-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
--window <string> Window handler type; valid values are: gvk, win32, win32dpi (default: gvk)
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:
--call-index <int>
-c --compression-mode <string>
Sets the compression mode for the resources in the subcapture, if no mode is selected, subcapture will have same format
the parent stream is using, values are: none, LZ4.
-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> Specifies the path to the directory where subcapture stream files should be written to.
--disable-ddi-hook Disabled D3D12 DDI hook responsible for collecting RTX stateObject exports.
--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
--dxr-rtas-restore-mode <int>
Determine how RT acceleration structures are captured: (0) CopyBlob, (1) RebuildFromBlob, (2) RebuildFromHistory.
Default: (1) RebuildFromBlob
--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> Specifies the name of the generated subcapture stream.
-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.
--sub-cmd-list-key <int>
Key of the command list execute in call-index to subcapture from
--sub-cmd-list-range <string>
Range of calls to subcapture from the command list
-s --subcapture-range <string>
Subcapture ranges. Format: [start..end] or (start..end) or a mix of parentheses types, where [ is inclusive and ( is exclusive.Multiple ranges can be specified by separating them with a semicolon.
For example: (start..end);(start..end)The last valid value in the range is one less than number of frames in the stream.
-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-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 <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.
-b|--bottleneck-format Format collected metrics output in a manner useful for performing
bottleneck and hotspot analysis. Intended to be used with CSV output
file generation. Examples of changes include there only being a single
column header row, with no duplicate metrics included, and some renamed
header labels, as well as the data being transposed (like the
--transpose option).
-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. Has lower priority than specifying the GPU vendor ID and/or GPU
device ID.
GPU 0: Intel(R) UHD Graphics 630 (LUID high 0x0 low 0x818D)
--gpu-device-id <string> Device ID of GPU to use for metrics collection, specified using
hexadecimal notation with a leading "0x" prefix. Has priority over
specifying the GPU vendor ID and/or GPU index.
GPU 0: Intel(R) UHD Graphics 630 (DeviceID 0x3E9B)
--gpu-vendor-id <string> Vendor ID of GPU to use for metrics collection, specified using
hexadecimal notation with a leading "0x" prefix. Has priority over
specifying the GPU index, but not over the GPU device ID.
GPU 0: Intel(R) UHD Graphics 630 (VendorID 0x8086)
--gpu-warming-passes-count <int>
Used to change the number of passes spent warming the GPU, by performing
offscreen rendering of the requested frame(s), before the first metric
group collection pass is made. Must be in the range [0, UINT32_MAX].
Default value: "1".
-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
standard metrics to be collected (although no prototype metrics are
instantiated when available). The supported syntax is:
<string> <collection>(;<collection>)*
<collection> <group-name-metrics>|
<group-symbol-metrics>|
<group-names>|<group-symbols>|
<metric-names>|<metric-symbols>|
<prototype-name-metrics>|
<prototype-symbol-metrics>
<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.
<prototype-name-metrics> prototypeName:<prototype-name-metric>(,<prototype-name-metric>)*
<prototype-name-metric> "<prototype-name>"(#<prototype-options>)*
<prototype-name> An individual prototype metric name from the
current list of those available (if any)
that will be instantiated.
<prototype-symbol-metrics> prototypeSymbol:<prototype-symbol-metric>(,<prototype-symbol-metric>)*
<prototype-symbol-metric> "<prototype-symbol>"(#<prototype-options>)*
<prototype-symbol> An individual prototype metric symbol from
the current list of those available (if any)
that will be instantiated.
<prototype-options> <prototype-option>(&<prototype-option>)*
<prototype-option> "<prototype-option-symbol>"=<prototype-option-value>
<prototype-option-symbol> An individual prototype metric option symbol
from the list of those available (if any)
that will be used when configuring the
prototype metric during instantiation.
<prototype-option-value> One decimal or hexadecimal value from the
list of those supported by the associated
prototype metric option that will be used
when configuring the prototype metric during
instantiation.
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 <metric-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>, <metric-symbol>, <prototype-name>,
<prototype-symbol> or <prototype-option-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>, <metric-symbol>, <prototype-symbol> or
<prototype-option-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.
--query-quality-passes-count <int>
Used to change the maximum number of metrics collection passes that are
performed per metric group when metric value quality issues are detected
for the queries requested. Must be in the range [1, UINT32_MAX]. Default
value: "5".
-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.
Note: If an Intel(R) GPU is used that supports the instantiation of
metric prototypes for collection, they will be also be included in
the list along with any options that they support. If the logging
level is info, debug or trace, the prototype description, its
general grouping/classification, type 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.