{ "file_format_version": "1.2.0", "layer": { "name": "VK_LAYER_LUNARG_gfxreconstruct", "type": "GLOBAL", "library_path": ".\\VkLayer_gfxreconstruct.dll", "api_version": "1.4.304", "implementation_version": "4194309", "description": "GFXReconstruct Capture Layer Version 1.0.5", "introduction": "The GFXReconstruct Capture Layer intercepts Vulkan API calls and logs them to a capture file. Other tools in the GFXReconstruct suite can inspect, modify, or replay capture files generated by this component.", "platforms": [ "WINDOWS", "LINUX", "ANDROID", "MACOS" ], "url": "https://vulkan.lunarg.com/doc/sdk/latest/windows/capture_tools.html", "status": "STABLE", "device_extensions": [ { "name": "VK_EXT_tooling_info", "spec_version": "1", "entrypoints": [ "vkGetPhysicalDeviceToolPropertiesEXT" ] } ], "features": { "presets": [ { "label": "Initialization", "description": "Capture the first two frames.", "platforms": [ "WINDOWS", "LINUX", "MACOS" ], "settings": [ { "key": "capture_trigger", "value": "" }, { "key": "capture_frames", "value": "1-2" } ] }, { "label": "Range", "description": "Capture a range of frames between presses of the F5 key.", "platforms": [ "WINDOWS", "LINUX", "MACOS" ], "settings": [ { "key": "capture_trigger", "value": "F5" }, { "key": "capture_frames", "value": "" } ] } ], "settings": [ { "key": "capture_trigger", "env": "GFXRECON_CAPTURE_TRIGGER", "label": "Hotkey Capture Trigger", "description": "Specify a hotkey (any one of F1-F12, TAB, CONTROL) that will be used to start/stop capture. Example: F3 will set the capture trigger to F3 hotkey. One capture file will be generated for each pair of start/stop hotkey presses. Default is: Empty string (hotkey capture trigger is disabled).", "platforms" : [ "WINDOWS", "LINUX", "MACOS" ], "type": "ENUM", "flags": [ { "key": "", "label": "None", "description": "" }, { "key": "F1", "label": "F1", "description": "F1 Key" }, { "key": "F2", "label": "F2", "description": "F2 Key" }, { "key": "F3", "label": "F3", "description": "F3 Key" }, { "key": "F4", "label": "F4", "description": "F4 Key" }, { "key": "F5", "label": "F5", "description": "F5 Key" }, { "key": "F6", "label": "F6", "description": "F6 Key" }, { "key": "F7", "label": "F7", "description": "F7 Key" }, { "key": "F8", "label": "F8", "description": "F8 Key" }, { "key": "F9", "label": "F9", "description": "F9 Key" }, { "key": "F10", "label": "F10", "description": "F10 Key" }, { "key": "F11", "label": "F11", "description": "F11 Key" }, { "key": "F12", "label": "F12", "description": "F12 Key" }, { "key": "TAB", "label": "TAB", "description": "TAB Key" }, { "key": "CONTROL", "label": "CONTROL", "description": "CONTROL Key" } ], "default": "" }, { "key": "capture_trigger_frames", "env": "GFXRECON_CAPTURE_TRIGGER_FRAMES", "label": "Hotkey Capture Frame Limit", "description": "Specify a limit on the number of frames to be captured via hotkey. Example: 1 will capture exactly one frame when the trigger key is pressed. Default is: Empty string (no limit)", "type": "STRING", "default": "" }, { "key": "capture_frames", "env": "GFXRECON_CAPTURE_FRAMES", "label": "Capture Specific Frames", "description": "Specify one or more comma-separated frame ranges to capture. Each range will be written to its own file. A frame range can be specified as a single value, to specify a single frame to capture, or as two hyphenated values, to specify the first and last frame to capture. Frame ranges should be specified in ascending order and cannot overlap. Note that frame numbering is 1-based (i.e. the first frame is frame 1). Example: 200,301-305 will create two capture files, one containing a single frame and one containing five frames. Default is: Empty string (all frames are captured).", "type": "STRING", "default": "" }, { "key": "capture_file", "env": "GFXRECON_CAPTURE_FILE", "label": "Capture File Name", "description": "Path to use when creating the capture file. Default is: gfxrecon_capture.gfxr", "type": "SAVE_FILE", "filter": "*.gfxr", "default": "gfxrecon_capture.gfxr", "settings": [ { "key": "capture_file_timestamp", "env": "GFXRECON_CAPTURE_FILE_TIMESTAMP", "label": "Capture File Name with Timestamp", "description": "Add a timestamp (yyyymmddThhmmss) postfix to the capture file name.", "type": "BOOL", "default": true }, { "key": "capture_file_flush", "env": "GFXRECON_CAPTURE_FILE_FLUSH", "label": "Capture File Flush After Write", "description": "Flush output stream after each packet is written to the capture file. Default is: false.", "type": "BOOL", "default": false } ] }, { "key": "capture_compression_type", "env": "GFXRECON_CAPTURE_COMPRESSION_TYPE", "label": "Compression Format", "description": "Compression format to use with the capture file. Valid values are: LZ4, ZLIB, ZSTD, and NONE. Default is: LZ4", "type": "ENUM", "flags": [ { "key": "LZ4", "label": "LZ4", "description": "Fastest compression algorithm that favors performance over compression ratio." }, { "key": "ZLIB", "label": "ZLIB", "description": "Widely used compression algorithm with better compression ratio than LZ4 but worse performance." }, { "key": "ZSTD", "label": "ZSTD", "description": "Newer compression algorithm with better compression ratio and performance than ZLIB, though not as fast as LZ4." }, { "key": "NONE", "label": "NONE", "description": "No compression" } ], "default": "LZ4" }, { "key": "memory_tracking_mode", "env": "GFXRECON_MEMORY_TRACKING_MODE", "label": "Memory Tracking Mode", "description": "Specifies the memory tracking mode to use for detecting modifications to mapped Vulkan memory objects. Available options are: page_guard, assisted, and unassisted.", "type": "ENUM", "flags": [ { "key": "page_guard", "label": "page_guard", "description": "Tracks modifications to individual memory pages, which are written to the capture file on calls to vkFlushMappedMemoryRanges, vkUnmapMemory, and vkQueueSubmit. Tracking modifications requires allocating shadow memory for all mapped memory." }, { "key": "assisted", "label": "assisted", "description": "Expects the application to call vkFlushMappedMemoryRanges after memory is modified; the memory ranges specified to the vkFlushMappedMemoryRanges call will be written to the capture file during the call." }, { "key": "unassisted", "label": "unassisted", "description": "Writes the full content of mapped memory to the capture file on calls to vkUnmapMemory and vkQueueSubmit. It is very inefficient and may be unusable with real-world applications that map large amounts of memory." } ], "default": "page_guard", "settings": [ { "key": "page_guard_copy_on_map", "env": "GFXRECON_PAGE_GUARD_COPY_ON_MAP", "label": "Page Guard Copy on Map", "description": "When the page_guard memory tracking mode is enabled, copies the content of the mapped memory to the shadow memory immediately after the memory is mapped.", "type": "BOOL", "default": true, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" } ] } }, { "key": "page_guard_separate_read", "env": "GFXRECON_PAGE_GUARD_SEPARATE_READ", "label": "Page Guard Separate Read Tracking", "description": "When the page_guard memory tracking mode is enabled, copies the content of pages accessed for read from mapped memory to shadow memory on each read. Can overwrite unprocessed shadow memory content when an application is reading from and writing to the same page.", "type": "BOOL", "default": true, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" } ] } }, { "key": "page_guard_external_memory", "env": "GFXRECON_PAGE_GUARD_EXTERNAL_MEMORY", "label": "Page Guard External Memory", "description": "When the page_guard memory tracking mode is enabled, use the VK_EXT_external_memory_host extension to eliminate the need for shadow memory allocations. For each memory allocation from a host visible memory type, the capture layer will create an allocation from system memory, which it can monitor for write access, and provide that allocation to vkAllocateMemory as external memory. Only available on Windows.", "platforms": [ "WINDOWS" ], "type": "BOOL", "default": false, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" } ] } }, { "key": "page_guard_persistent_memory", "env": "GFXRECON_PAGE_GUARD_PERSISTENT_MEMORY", "label": "Page Guard Persistent Memory", "description": "When the page_guard memory tracking mode is enabled, this option changes the way that the shadow memory used to detect modifications to mapped memory is allocated. The default behavior is to allocate and copy the mapped memory range on map and free the allocation on unmap. When this option is enabled, an allocation with a size equal to that of the object being mapped is made once on the first map and is not freed until the object is destroyed. This option is intended to be used with applications that frequently map and unmap large memory ranges, to avoid frequent allocation and copy operations that can have a negative impact on performance. This option is ignored when GFXRECON_PAGE_GUARD_EXTERNAL_MEMORY is enabled.", "type": "BOOL", "default": false, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" }, { "key": "page_guard_external_memory", "value": false } ] } }, { "key": "page_guard_align_buffer_sizes", "env": "GFXRECON_PAGE_GUARD_ALIGN_BUFFER_SIZES", "label": "Page Guard Align Buffer Sizes", "description": "When the page_guard memory tracking mode is enabled, this option overrides the Vulkan API calls that report buffer memory properties to report that buffer sizes and alignments must be a multiple of the system page size. This option is intended to be used with applications that perform CPU writes and GPU writes/copies to different buffers that are bound to the same page of mapped memory, which may result in data being lost when copying pages from the page_guard shadow allocation to the real allocation. This data loss can result in visible corruption during capture. Forcing buffer sizes and alignments to a multiple of the system page size prevents multiple buffers from being bound to the same page, avoiding data loss from simultaneous CPU writes to the shadow allocation and GPU writes to the real allocation for different buffers bound to the same page. This option is only available for the Vulkan API.", "type": "BOOL", "default": true, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" }, { "key": "page_guard_external_memory", "value": false } ] } }, { "key": "page_guard_unblock_sigsegv", "env": "GFXRECON_PAGE_GUARD_UNBLOCK_SIGSEGV", "label": "Page Guard unblock SIGSEGV from thread's signal mask", "description": "When the page_guard memory tracking mode is enabled, this option overrides enables SIGSEGV in thread's signal mask in the case that it has been disabled.", "type": "BOOL", "default": false, "dependence": { "mode": "ALL", "settings": [ { "key": "memory_tracking_mode", "value": "page_guard" }, { "key": "page_guard_external_memory", "value": false } ] } } ] }, { "key": "log", "label": "Log", "description": "Control log messages.", "type": "GROUP", "settings": [ { "key": "log_level", "env": "GFXRECON_LOG_LEVEL", "label": "Level", "description": "Specify the minimum severity level of messages to log. Options are: debug, info, warning, error, and fatal. The specified level and all higher levels will be enabled for logging. For example, choosing the warning level will also enable the error and fatal levels.", "type": "ENUM", "flags": [ { "key": "debug", "label": "debug, info, warning, error, fatal", "description": "" }, { "key": "info", "label": "info, warning, error, fatal", "description": "" }, { "key": "warning", "label": "warning, error, fatal", "description": "" }, { "key": "error", "label": "error, fatal", "description": "" }, { "key": "fatal", "label": "fatal", "description": "" } ], "default": "info" }, { "key": "log_detailed", "env": "GFXRECON_LOG_DETAILED", "label": "Log Name and Line Number", "description": "Include name and line number from the file responsible.", "type": "BOOL", "default": false }, { "key": "log_allow_indents", "env": "GFXRECON_LOG_ALLOW_INDENTS", "label": "Apply additional indentation", "description": "Apply additional indentation formatting to log messages.", "type": "BOOL", "default": false }, { "key": "log_output_to_console", "env": "GFXRECON_LOG_OUTPUT_TO_CONSOLE", "label": "Log Output to Console / stdout", "description": "Log messages will be written to stdout.", "type": "BOOL", "default": true }, { "key": "log_break_on_error", "env": "GFXRECON_LOG_BREAK_ON_ERROR", "label": "Trigger Debug Break on Error", "description": "Trigger a debug break when logging an error.", "type": "BOOL", "default": false }, { "key": "log_output_to_os_debug_string", "env": "GFXRECON_LOG_OUTPUT_TO_OS_DEBUG_STRING", "label": "Log Output to Debug Console", "description": "Windows only option. Log messages will be written to the Debug Console with OutputDebugStringA", "platforms": [ "WINDOWS" ], "type": "BOOL", "default": false }, { "key": "log_file", "env": "GFXRECON_LOG_FILE", "label": "Log File", "description": "When set, log messages will be written to a file at the specified path. Default is: Empty string (file logging disabled).", "type": "SAVE_FILE", "filter": "*.txt", "default": "", "settings": [ { "key": "log_file_flush_after_write", "env": "GFXRECON_LOG_FILE_FLUSH_AFTER_WRITE", "label": "Log File Flush After Write", "description": "Flush the log file to disk after each write when true.", "type": "BOOL", "default": false }, { "key": "log_file_keep_open", "env": "GFXRECON_LOG_FILE_KEEP_OPEN", "label": "Log File Keep Open", "description": "Keep the log file open between log messages when true, or close and reopen the log file for each message when false.", "type": "BOOL", "default": true }, { "key": "log_file_create_new", "env": "GFXRECON_LOG_FILE_CREATE_NEW", "label": "Log File Overwrite", "description": "Specifies that log file initialization should overwrite an existing file when true, or append to an existing file when false.", "type": "BOOL", "default": true } ] } ] } ] } } }