Layers

capture

Capture Layer

Usage : Use to capture a stream of a workload

Arguments:
	directory	Specifies the path to the directory where stream files should be written to.
	name	Specifies the name of the stream directory; default is <process name>-<timestamp>-<process id>. 
		If the stream directory already exists, a suffix in the format '-<num>' is appended to the stream name.
	keyframe-trigger-type	Sets what kind of condition triggers capturing a keyframe. Options: time, 
		keypress.  Can be repeated to specify multiple triggers.  Default: time
	time-interval	Set how many seconds should elapse between each keyframe if time is enabled for the 
		keyframe-trigger-type.  Default: 4.0
	deferred	Indicate that the user wishes to start capture at arbitrary time. Default: false 
		(normal capture to disk)
	insert-virtual-present	Inserts artificial 'Present' call to mark state restoration 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.
	captured-frames	If deferred capture is enabled, specifies the range of frames that should be captured. 
		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)
	fixed-frame-count	Set how many frames should be captured when deferred capture is triggered. 
		Default: unlimited
	compression	Enables compression. Options: lz4
	dxr-rtas-restore-mode	Determine how RT acceleration structures are captured in the restoriation points:                                       
		 (0) CopyBlob - a serialized driver specific blob (driver specific playback)                                       
		 (1) RebuildFromBlob - rebuild reconstructed from the serialized blob (platform agnostic playback, Intel only capture)                                       
		 (2) RebuildFromHistory - rebuild calls recorded in AS history tracking (platfrom agnostic playback, possible overhead).                                       
		Default: (0) CopyBlob
	disable-rashistory	Disables RT acceleration structure build history.
	disable-stream-recording-message	Disables "Stream recording" status message.

If you are using the --layer capture:keyframe-trigger-type=keypress, make sure to inspect the 
bin/Release/actions.keymap file. It contains the hotkey mappings and will allow you to set any supported key as the 
trigger key. Look for the CreateKeyframe setting.

Supported key strings: 
[A-Z]
[0-9]
[SHIFT]
[LSHIFT]
[RSHIFT]
[CTRL]
[LCTRL]
[RCTRL]
[CAPS]
[TAB]
[LALT]
[RALT]
[INS]
[SPACE]
[HOME]
[DEL]
[END]
[UP]
[DOWN]
[LEFT]
[RIGHT]
[ESC]
[BACK]
[ENTER]
[F1]
[F2]
[F3]
[F4]
[F5]
[F6]
[F7]
[F8]
[F9]
[F10]
[F11]
[F12]

screenshot

Screenshot Layer

Usage : Use to capture a screenshot of a workload during capture or playback

Arguments:
	frames	Specify frames to capture in screenshots. Frame numbers begin at 1. All values must be positive. 
		Interval capture can be specified using standard 'range' notation, where ( and ) indicate 'open' 
		range endpoints, and [ and ] indicate 'closed' range endpoints. Ranges may include an optional 
		step value, appended to the end of the range, for example: (10..100]:10, to indicate every tenth frame 
		in the range 10 to 100 (not including 10). The default step value is 1.
		Individual frames are specified as integers separated by semicolons, for example: 1;10;100. Individual 
		frames and range specifications can be mixed in any order, for example: 1;(50..70]:5;10;100.
		when using the open range endpoints ( and ), remember to wrap the entire argument in quotes to prevent 
		certain shells from treating the symbol as a subshell. For example frames="(10..199):10)"
		
		There is a risk of unusually high memory consumption, if user requests a high number of screenshots 
		without specifying a reasonable step. It is suggested to use async=false flag to prevent from the out 
		of memory errors in such case. High memory consumption might occur, if asynchronous screenshot 
		download to disk thread (enabled by default) cannot keep up with the rate of screenshot requests.

	path	Override default output directory for screenshots. When using in conjunction with the capture layer, the 
		template string _CAPTURE_ is supported. Any instance of this string in the 'path' argument will be replaced 
		by the location of the current stream capture directory, when a new capture is begun. This includes multiple 
		deferred capture triggers. If the _CAPTURE_ template is present but the capture path has not been set (for example, 
		when using the screenshot layer without the capture layer, or when using the capture layer in deferred mode but  
		no capture has been triggered), then no screenshots will be saved. Default: "<User's Documents folder>/GPA". 

	time-interval	Specify number of seconds (wall-clock time) between screenshots. On non-Windows platforms, the timer begins 
		running when the application begins, not when the first API call is made. On Windows platforms, the timer begins 
		when the first 'present' call happens. Interval is in units of milliseconds, so '4 seconds' would be 
		4000 milliseconds.
	async	Whether or not screenshot capture should be asynchronous. The default is "true". 

	wait-on-shutdown	Whether or not screenshot capture should wait for remaining asynchronous screenshots on shutdown. 
		The default is "true". 

	file-format	Override default screenshot file format (png). Available formats are [jpg,png,bmp]

	show-capture-frames	If set to true (default), the frame count saved in the filename will be reset when stream capture begins. 
		If set to false, the frame count will not reset.

Implemented for Vulkan and DirectX

hud-layer

Hud Layer

Usage : Use to display certain information during capture or playback 

Arguments:
	show-capture-frames	If set to true (default), the displayed frame count will be reset when stream capture begins. If set to false, the frame count will not reset.

displays FPS, fps min, fps max, and the in use API

logging

Logging Layer

Usage : Use to dump out a log of every graphics API call your target application makes

Arguments:
	verbose	set verbose=1 to enable more detailed logging, certain structs or arrays may be represented by (embedded)
	callindex	set callindex=1 to enable printing call index
	usegpalog	set usegpalog=1 to print verbose log with default GPA log library; Verbose log is directed to cout by default
	condensed	set condensed=1 to enable elimination of repeated lines
	deferred	set deferred=1 to disable logging; ToggleLogging keypress set in actions.keymap to enable/disable at runtime
	log-filter	Path to a json file with a list of class and functions tokens for which logging will be enabled. Use json files under layers directory as a starting point.

api-debug-layer

API Debug Layer

Usage : Use to enable validation layers, or similar functionality for DirectX and Vulkan

Arguments:
	gpubasedvalidation	Enables GPU based validation for D3D12. Effectively calls ID3D12Debug1::SetEnableGPUBasedValidation
	flushafterexecute	Naively flushes the queue after each ExecuteCommandLists call. D3D12 only. 5sec timeout.
	asyncdeviceremovalcheck	Creates thread that periodically checks for device removal status. Useful, if device removal happens on non-dispatch table call.

Validation layer messages will be logged to console

device-override

Device Override Layer

Usage : Used to specify which device should be used during execution of the injected application.

Arguments:
	deviceindex	The device to use during execution, specified in terms of the index in the array returned by the used API's device enumeration.
	vendorid	vendorId of the device to use during execution. Requires paired deviceid value.
	deviceid	deviceId of the device to use during execution. Requires paired vendorId value.
	luid	64 bit local adapter identifier

If user provide more than one way to identify the device, the layer will try to
use following identification methods in specified order:
1. LUID
2. Device and Vendor ID
3. Device index
If a device with requested parameters is not found, the layer will not force any device

DirectX Adapters:
	Device[0]
		name: NVIDIA GeForce RTX 3060
		vendorID: 0x10DE
		deviceID: 0x2504
		LUID: 0x21FFF

		Driver version: 32.0.15 Build 6094

		Max feature level for D3D12Device 12.1
		D3D12_TILED_RESOURCES_TIER: 3
		D3D12_RESOURCE_BINDING_TIER: 3
		D3D12_CONSERVATIVE_RASTERIZATION_TIER: 3
		D3D12_CROSS_NODE_SHARING_TIER: 0
		D3D12_RESOURCE_HEAP_TIER: 2
		D3D12_RENDER_PASS_TIER: 0
		D3D12_RAYTRACING_TIER: 1.1
		D3D12_VIARIABLE_SHADING_RATE_TIER: 2
		D3D12_MESH_SHADING_TIER: 1
		D3D12_SAMPLER_FEEDBACK_TIER: 0.9

		Max feature level for D3D11Device 12.1
		D3D11_CONSERVATIVE_RASTERIZATION_TIER: 3
		D3D11_TILED_RESOURCES_TIER: 3

	Device[1]
		name: Microsoft Basic Render Driver
		vendorID: 0x1414
		deviceID: 0x8C
		LUID: 0x22D48

		Driver version: 10.0.19041 Build 4355
		SOFTWARE ADAPTER

		Max feature level for D3D12Device 12.1
		D3D12_TILED_RESOURCES_TIER: 3
		D3D12_RESOURCE_BINDING_TIER: 3
		D3D12_CONSERVATIVE_RASTERIZATION_TIER: 3
		D3D12_CROSS_NODE_SHARING_TIER: 0
		D3D12_RESOURCE_HEAP_TIER: 2
		D3D12_RENDER_PASS_TIER: 1
		D3D12_RAYTRACING_TIER: 0
		D3D12_VIARIABLE_SHADING_RATE_TIER: 1
		D3D12_MESH_SHADING_TIER: 0
		D3D12_SAMPLER_FEEDBACK_TIER: 0

		Max feature level for D3D11Device 12.1
		D3D11_CONSERVATIVE_RASTERIZATION_TIER: 3
		D3D11_TILED_RESOURCES_TIER: 3

DirectX Software Adapters: 
	Device[1000]
		name: WARP (DX11, DX12)

	Device[1001]
		name: Reference Rasterizer (DX11)

	Device[1002]
		name: NULL Rasterizer (DX11)


Vulkan Devices:
	Device[0]
		name: NVIDIA GeForce RTX 3060
		vendorID: 0x10DE
		deviceID: 0x2504
		LUID: 0x21FFF

		Driver ID: VK_DRIVER_ID_NVIDIA_PROPRIETARY
		Driver name: NVIDIA
		Driver info: 560.94

dump-resources-layer

Dump Resources Layer

Usage : Use to inspect resources of a workload during capture or playback. Dumped file name syntax: f_<frame index>_cl_<command-list>_dc_<executed and/or draw call index>_<view type>_<slot index or buffer offset>_r_<resource>_i_<sub-resource index>_w_<depth index>.<extension>.

Arguments:
	frames	Override frame range (default: all frames). Dumps only in specified frames. Uses standard 'range' notation.

	draws	Override draw call range (default: all draws). Dumps only in specified draw calls. Uses standard 'range' notation.

	image-format	Override default image file format (default: png). Available formats are [jpg|png|bmp].

	timeout	Override default wait for dump (default: infinite).

	path	Override default output directory.

	dimensions	Override dimensions (default: all dimensions). Must be a hex mask. For D3D12, ith bit corresponds to D3D12_RESOURCE_DIMENSION value. For example, 0x2 is buffers only, 0x8 is 2D textures, 0x1C is any texture.

	dry-run	Override dump to disk (default: false). 

	command-list	Override command-lists for dump (default: all), must be a hex address. Only for playback.

	no-async	Override async saving for dump (default: false).

	clear	Clears per draw (default: false). Only for capture.

	views	Override views (default: all views). Must be a hex mask. For D3D12, ith bit corresponds to the enum value: DS:2, RT:3, UAV:6. For example, 0x8 is RT only, 0x40 is UAV only, 0xC is RT and DS.
	buffer-format	Override default buffer file format (default: hex). Available formats are [raw|hex].

	resource	Override resource for dump (default: all), must be a hex address. Only for playback.


Implemented for DirectX12

dump-state-layer

Dump State Layer

Usage : Inspect or dump draw/dispatch call state information such as pipeline states, views, root signatures and shaders. 

Arguments:
	frames	Dump state only for specified frame intervals (default: all frames).          Use range notation to specify an interval of frames 

	draws	Dump state only for specified draw calls (default: all draws).          Draw indexing is based on CommandList execution order (D3D12).          Use range notation to specify range of draw calls.

	dispatches	Dump state only for specified dispatch calls (default: all dispatches).          Dispatch indexing is based on CommandList execution order (D3D12).          Use range notation to specify range of dispatch calls.

	directory	Override default output directory, must be an absolute path.


Available only for D3D12 workloads.
         Most arguments use range notation. Ranges are specified using standard range notation - [start..end]:step. [] indicate closed and () indicate open. 
        Multiple ranges cab be specified using ; as delimiter.         Ranges can also be combined with single index value. 
         For e.g., [4..21]:2;35;50 dumps state data between frames 4 and 21 in steps of 2 and then frames 35, 50.