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.