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.
     --event-bridge       Enable event bridge shim-injector communication
  -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>     Switches the default Sequential mode into parallel producer->consumer with 100k API_Calls in the ring buffer. 1 for one bg thread, 2 for two
  -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) Iris(R) Plus Graphics (LUID high 0x0 low 0xAC7A)

--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) Iris(R) Plus Graphics (DeviceID 0x8A51)

--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) Iris(R) Plus Graphics (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.

   --gpu-freq-percent <int>    
                               Used to change the maximum GPU frequency to percent of maximum available
                               GPU frequency. Must be in the range [0, 100]. Default
                               value: "0" means that no GPU frequency override is applied.

gpa-system-info

This utility simply prints out information about the system it is run on, there are no command line options.