mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 01:20:42 +00:00
Add better documentation for how to specify separate shader debug info
This commit is contained in:
baldurk
@@ -201,22 +201,18 @@ Querying an ``ID3D11Device`` or ``ID3D12Device`` for UUID ``{A7AA6116-9C8D-4BBA-
|
||||
|
||||
On Vulkan `VK_EXT_tooling_info` will return an entry for RenderDoc. This extension will always be available when running under RenderDoc.
|
||||
|
||||
.. _unstripped-shader-info:
|
||||
|
||||
My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?
|
||||
---------------------------------------------------------------------------------
|
||||
|
||||
If you get textures that are just named ``texture0`` and ``texture1`` or constant/uniform buffers named ``cbuffer2`` then this indicates that you have stripped optional reflection/debug information out of your shaders.
|
||||
|
||||
This optional information is generated by the compiler, but is not required for API correctness so some codebases will strip the information out after processing it offline, and so it will not be available for RenderDoc to fetch.
|
||||
This optional information is generated by the compiler, but is not required for API correctness so some codebases will strip the information out after processing it offline, and so it will not be available for RenderDoc to fetch. This also includes shader source for source-level shader debugging on APIs that support it.
|
||||
|
||||
The simplest solution is just to avoid stripping the data when using RenderDoc, but that isn't always possible. Instead RenderDoc allows you to use API-specific methods to specify where the unstripped data can be found. This means you can save the unstripped shader to a debug location and then either store this location with the shader, or specify it at runtime. On replay RenderDoc will expect the data to be available at that location and it will load it up instead.
|
||||
The simplest solution is just to avoid stripping the data when using RenderDoc. If you can enable debugging information to be embedded when building your shaders that's all that is necessary. All APIs will allow this data in the shader blob, but the way it is generated varies by API and shader compiler.
|
||||
|
||||
The path you specify (with the stripped shader, or at runtime) can be either absolute or relative. If it's relative, you must configure a shader search path in the :doc:`../window/settings_window`.
|
||||
It's not always simple to avoid that stripping, and in some cases it may not be desirable as debug information can be quite a storage and memory overhead, it may instead be better to separate out the debug information and store it in a disk cache, with only a path or identifier remaining in the stripped blob so that RenderDoc can identify the matching debug information later.
|
||||
|
||||
The stripped shader file stored on disk can also be compressed with LZ4 to save space as often most of the size is made up for shader source text which compresses well. To do this, simply compress the contents of the file and prepend the pathname (either absolute or relative, specified in the shader blob or at runtime) with ``lz4#``.
|
||||
|
||||
For example code using this method, check out :doc:`tips_tricks`.
|
||||
For more information on how to do this, see :doc:`../how/how_shader_debug_info`.
|
||||
|
||||
I want to debug a child process that my program launches, how can I inject RenderDoc?
|
||||
-------------------------------------------------------------------------------------
|
||||
|
||||
@@ -44,34 +44,7 @@ This page is a random hodge-podge of different tips and tricks that might not be
|
||||
// For Vulkan
|
||||
// VK_EXT_tooling_info will be available, see the Vulkan specification
|
||||
|
||||
#. RenderDoc can be informed about separated debug shader blobs through API specific ways - see :ref:`unstripped-shader-info` for more details:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// For D3D11:
|
||||
GUID RENDERDOC_ShaderDebugMagicValue = RENDERDOC_ShaderDebugMagicValue_value; // GUID value in renderdoc_app.h
|
||||
|
||||
ID3D11VertexShader *shader = ...;
|
||||
std::string pathName = "/path/to/saved/blob"; // path name is in UTF-8
|
||||
// path name can also be prefixed with lz4# to indicate the blob is compressed
|
||||
pathName = "lz4#/path/to/saved/blob";
|
||||
|
||||
// string parameter must be NULL-terminated, and in UTF-8
|
||||
shader->SetPrivateData(RENDERDOC_ShaderDebugMagicValue, (UINT)pathName.length(), pathName.c_str());
|
||||
|
||||
// Alternatively at build time:
|
||||
struct { GUID guid; char name[MAX_PATH]; } path;
|
||||
|
||||
path.guid = RENDERDOC_ShaderDebugMagicValue;
|
||||
// must include NULL-terminator, and be in UTF-8
|
||||
memcpy(path.name, debugPath.c_str(), debugPath.length() + 1);
|
||||
|
||||
size_t pathSize = sizeof(GUID) + debugPath.length() + 1;
|
||||
|
||||
D3DSetBlobPart(strippedBlob->GetBufferPointer(), strippedBlob->GetBufferSize(), D3D_BLOB_PRIVATE_DATA, 0, &path, pathSize, &annotatedBlob);
|
||||
// use annotatedBlob instead of strippedBlob from here on
|
||||
|
||||
#. RenderDoc can be informed about separated debug shader blobs through API specific ways - see :doc:`../how/how_shader_debug_info` for more details.
|
||||
#. More coming soon hopefully :).
|
||||
|
||||
Keyboard Shortcuts
|
||||
|
||||
@@ -14,7 +14,7 @@ For the most part at least some debug information is included with shaders unles
|
||||
|
||||
For shader debugging it's recommended that you build with ``/Od`` or ``D3DCOMPILE_SKIP_OPTIMIZATION``, as this will enable HLSL debugging by default.
|
||||
|
||||
For more information on how to get this unstripped debug information to renderdoc, see :ref:`unstripped-shader-info`.
|
||||
For more information on how to get this unstripped debug information to renderdoc, see :doc:`how_shader_debug_info`.
|
||||
|
||||
Debugging a vertex
|
||||
------------------
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
How do I use shader debug information?
|
||||
======================================
|
||||
|
||||
RenderDoc makes extensive use of shader debug information to provide a smoother debugging experience. This kind of information gives names to anything in the shader interface such as constants, resource bindings, interpolated inputs and outputs. It includes better type information that in many cases is not available, and it can also even include embedded copies of the shader source which is used for source-level debugging.
|
||||
|
||||
On most APIs this debug information adds up to a large amount of information which is not necessary for functionality, and so it can be optionally stripped out. Many shader compilation pipelines will do this automatically, so the information is lost by the time RenderDoc can intercept it at the API level. For this reason there are several ways to save either the unstripped shader blob or just the debug information separately at compile time and provide ways for RenderDoc to correlate the stripped blob it sees passed to the API with the debug information on disk.
|
||||
|
||||
.. note::
|
||||
|
||||
OpenGL is effectively excluded from this consideration because it has no separate debug information, everything is generated from the source uploaded to the API. If the source has been stripped of information or obfuscated, this will have to be handled by your application.
|
||||
|
||||
.. warning::
|
||||
|
||||
Since this debug information is stored separately, it is *not* part of the capture and so if the debug information is moved or deleted RenderDoc will not be able to find it and the capture will show only what is possible with no debug information.
|
||||
|
||||
Specifying debug shader blobs
|
||||
-----------------------------
|
||||
|
||||
Separated debug shader blobs can be specified using a path and an API-specific mechanism. The path itself can either be an absolute path, which will be used directly every time, or it can be a relative path which allows the blob identifier to be specified relative to customisable search folders. If using a relative path, it can be as simple as a filename.
|
||||
|
||||
The search folders for shader debug info are specified in the settings window, under the ``Core`` category. You can configure as many search directories as you wish, and they will be searched in the listed order.
|
||||
|
||||
If no match is found after all of the directories have been tried, the first subdirectory in the path specified will be removed and the directories will be tried again in order. This way an absolute path can match if there is a trailing subset that exists in one of the configured search paths. Similarly for a relative path which has a non-matching prefix to the path but a trailing subpath that does exist.
|
||||
|
||||
Using the D3D11 API you can specify the path at runtime:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
std::string pathName = "path/to/saved/blob.dxbc"; // path name is in UTF-8
|
||||
|
||||
ID3D11VertexShader *shader = ...;
|
||||
|
||||
// GUID value in renderdoc_app.h
|
||||
GUID RENDERDOC_ShaderDebugMagicValue = RENDERDOC_ShaderDebugMagicValue_struct;
|
||||
|
||||
// string parameter must be NULL-terminated, and in UTF-8
|
||||
shader->SetPrivateData(RENDERDOC_ShaderDebugMagicValue,
|
||||
(UINT)pathName.length(), pathName.c_str());
|
||||
|
||||
You can also specify it using the Vulkan API:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
std::string pathName = "path/to/saved/blob.dxbc"; // path name is in UTF-8
|
||||
|
||||
VkShaderModule shaderModule = ...;
|
||||
|
||||
// Both EXT_debug_marker and EXT_debug_utils can be used, this example uses
|
||||
// EXT_debug_utils as EXT_debug_marker is deprecated
|
||||
VkDebugUtilsObjectTagInfoEXT tagInfo = {VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT};
|
||||
tagInfo.objectType = VK_OBJECT_TYPE_SHADER_MODULE;
|
||||
tagInfo.objectHandle = (uint64_t)shaderModule;
|
||||
// tag value in renderdoc_app.h
|
||||
tagInfo.tagName = RENDERDOC_ShaderDebugMagicValue_truncated;
|
||||
tagInfo.pTag = pathName.c_str();
|
||||
tagInfo.tagSize = pathName.length();
|
||||
|
||||
vkSetDebugUtilsObjectTagEXT(device, &tagInfo);
|
||||
|
||||
D3D12 requires using a shader-compile-time specifier. This is done by passing ``/Fd`` to fxc or dxc. This switch requires a parameter which can either be a path to a file or a directory. If you specify a file, that path is then stored in the stripped blob as an absolute path. If you specify a directory the debug blob will be stored in that directory with a hash-based filename. The path stored in the stripped blob is then a *relative* path with just the filename.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
* :doc:`how_debug_shader`
|
||||
@@ -7,6 +7,7 @@ How do I ...?
|
||||
how_android_capture
|
||||
how_filter_events
|
||||
how_debug_shader
|
||||
how_shader_debug_info
|
||||
how_inspect_pixel
|
||||
how_view_texture
|
||||
how_object_details
|
||||
|
||||
@@ -171,7 +171,7 @@ Core options
|
||||
|
||||
Here you can choose which locations to search in, and in which order, when looking up a relative path for unstripped debug info.
|
||||
|
||||
For more information you can consult :ref:`the FAQ entry about providing unstripped shader debug information <unstripped-shader-info>`.
|
||||
For more information you can consult :doc:`../how/how_shader_debug_info`.
|
||||
|
||||
| :guilabel:`Enable Radeon GPU Profiler integration` Default: ``Off``
|
||||
|
||||
|
||||
Reference in New Issue
Block a user