mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-04 09:00:44 +00:00
Put all annotation docs into the same 'how do I' page. Refs #2285
* This page now documents both how to annotate things from code in the application, as well as at runtime in the UI.
This commit is contained in:
baldurk
@@ -1,9 +1,172 @@
|
||||
How do I annotate a capture?
|
||||
============================
|
||||
|
||||
RenderDoc allows some annotation of capture files, meaning that you can make notes and bookmark important events, then save your changes within the capture itself for sharing with other people. This can be useful for example when investigating a bug or repro case and passing on your findings natively to someone else, instead of having to include additional text like 'texture 148 is the buggy texture'.
|
||||
RenderDoc allows annotation of captures in two ways - annotations that you provide from your application along with the other graphics API calls that you make, and annotations that are made in the UI while analysing a capture and can be saved with it.
|
||||
|
||||
All of these modifications can be saved with a capture. Pressing :kbd:`Ctrl-S` or :guilabel:`File` → :guilabel:`Save` will save the capture with any changes that have been made to it in the UI. If you haven't already saved a temporary capture, or the capture is on a remote context, this will need to you save it to a local path.
|
||||
The annotations provided with the graphics API calls from your application vary by the particular API and are documented below.
|
||||
|
||||
Annotations made in the UI are also described below. These can be useful for example when investigating a bug or repro case and passing on your findings natively to someone else, instead of having to include additional text like 'texture 148 is the buggy texture' you can directly mark up the capture.
|
||||
|
||||
All of the UI modifications can be saved with a capture. Pressing :kbd:`Ctrl-S` or :guilabel:`File` → :guilabel:`Save` will save the capture with any changes that have been made to it in the UI. If you haven't already saved a temporary capture, or the capture is on a remote context, this will need to you save it to a local path.
|
||||
|
||||
Application provided marker regions
|
||||
-----------------------------------
|
||||
|
||||
When calling graphics API functions from your code you can provide annotations to group regions of the frame under names, with a nested hierarchy.
|
||||
|
||||
These markers are provided in an API specific way: D3D11 uses the ``D3DPERF`` or ``ID3DUserDefinedAnnotation`` APIs, D3D12 uses ``SetMarker``/``BeginEvent``/``EndEvent`` on lists or queues, OpenGL has many extensions but ``KHR_debug`` is guaranteed to always be available, and Vulkan uses ``VK_EXT_debug_utils``.
|
||||
|
||||
In APIs such as D3D12 and Vulkan with queues and command buffers, the markers are processed in submission order and are allowed to cross primary command buffers, so a single region can cross several command buffers. Secondary command buffers or bundles can contain markers but they must be self-contained and not imbalanced.
|
||||
|
||||
Some of the APIs add the ability to provide a colour for a marker region, these colours are displayed in the :doc:`../window/event_browser` window.
|
||||
|
||||
.. figure:: ../imgs/Screenshots/EventBrowserRegions.png
|
||||
|
||||
Marker Regions: The Event browser showing several coloured marker regions.
|
||||
|
||||
Example code for D3D11:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// The ``D3DPERF`` APIs are exported by ``d3d9.dll``, but can still be used in D3D11
|
||||
// for compatibility reasons
|
||||
|
||||
D3DPERF_BeginEvent(0xffffffff, L"Start of example");
|
||||
|
||||
D3DPERF_BeginEvent(0xff00ff00, L"Sub section");
|
||||
// events inside the subsection
|
||||
D3DPERF_EndEvent();
|
||||
|
||||
// events outside the subsection
|
||||
D3DPERF_EndEvent();
|
||||
|
||||
// the newer ID3DUserDefinedAnnotation API is also supported
|
||||
ID3DUserDefinedAnnotation *annot;
|
||||
immediateContext->QueryInterface(__uuidof(ID3DUserDefinedAnnotation), (void **)&annot);
|
||||
|
||||
annot->BeginEvent(L"Sub section 2")
|
||||
|
||||
annot->EndEvent();
|
||||
|
||||
Example code for D3D12:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// 1 for the first parameter means the data is an ANSI string. Pass 0 for a wchar string.
|
||||
// the length should include the NULL terminator
|
||||
list->BeginEvent(1, "Begin Section", sizeof("Begin Section"));
|
||||
|
||||
list->EndEvent();
|
||||
|
||||
// queue-level markers can be provided similarly.
|
||||
|
||||
Example code for OpenGL using the ``KHR_debug`` extension. Many other extensions exist in GL to provide markers and will be made available by RenderDoc too.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// omitted code to initialise the extension function pointers
|
||||
|
||||
glPushDebugGroupKHR(GL_DEBUG_SOURCE_APPLICATION, 0, -1, "Begin Section");
|
||||
|
||||
// contents of section here
|
||||
|
||||
glPopDebugGroupKHR();
|
||||
|
||||
Example code for Vulkan using the ``VK_EXT_debug_utils`` extension:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// omitted code to initialise the extension
|
||||
|
||||
VkCommandBuffer cmd = ...;
|
||||
|
||||
VkDebugUtilsLabelEXT markerInfo = {};
|
||||
markerInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT;
|
||||
markerInfo.pLabelName = "Begin Section";
|
||||
vkCmdBeginDebugUtilsLabelEXT(cmd, &markerInfo);
|
||||
|
||||
// contents of section here
|
||||
|
||||
vkCmdEndDebugUtilsLabelEXT(cmd);
|
||||
|
||||
// queue-level markers can be provided similarly.
|
||||
|
||||
Application provided object names
|
||||
---------------------------------
|
||||
|
||||
Similar to the marker regions above, it is possible to give objects names via the graphics APIs and they will be displayed with those human-readable names instead of auto-generated names.
|
||||
|
||||
When a resource with a custom name is bound to the pipeline it will be listed like so:
|
||||
|
||||
.. figure:: ../imgs/Screenshots/NamedTex.png
|
||||
|
||||
Named Texture: The example texture bound with name displayed.
|
||||
|
||||
In a similar way any other resource can be named and this will be useful throughout the rest of the analysis. If a custom name is not provided, a default name will be generated - as seen above with the Render Pass and Framebuffer objects.
|
||||
|
||||
Again the exact method varies by API, as given in the examples below.
|
||||
|
||||
.. note::
|
||||
|
||||
RenderDoc does not support names that change within a capture. A resource only has one name, which is the most recent one set.
|
||||
|
||||
Example code for D3D11 using the ``SetPrivateData`` function:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
ID3D11Texture2D *tex2d = NULL;
|
||||
d3dDevice->CreateTexture2D(&descriptor, NULL, &tex2d);
|
||||
|
||||
// Give the texture a useful name
|
||||
tex2d->SetPrivateData(WKPDID_D3DDebugObjectName, sizeof("Example Texture"), "Example Texture");
|
||||
|
||||
With D3D12 you can use the ``SetName`` function:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
ID3D12Resource *tex2d = NULL;
|
||||
d3dDevice->CreateCommittedResource(&heapProps, heapFlags, &descriptor, initState, &clearValue, __uuidof(ID3D12Resource), (void **)&tex2d);
|
||||
|
||||
// Give the texture a useful name
|
||||
tex2d->SetName(L"Example Texture");
|
||||
|
||||
In OpenGL this can be done with ``GL_KHR_debug`` with the function ``glObjectLabel``.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
GLuint tex2d = 0;
|
||||
glGenTextures(1, &tex2d);
|
||||
glBindTexture(GL_TEXTURE_2D, tex2d);
|
||||
|
||||
// apply the name, -1 means NULL terminated
|
||||
glObjectLabel(GL_TEXTURE, tex2d, -1, "Example Texture");
|
||||
|
||||
In Vulkan you can enable the ``VK_EXT_debug_utils`` extension, which is provided by RenderDoc, and use the ``vkSetDebugUtilsObjectNameEXT`` function.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// create the image
|
||||
VkImage tex2d;
|
||||
vkCreateImage(device, &createInfo, NULL, &tex2d);
|
||||
|
||||
// set the name
|
||||
VkDebugUtilsObjectNameInfoEXT nameInfo = {};
|
||||
nameInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT;
|
||||
nameInfo.objectType = VK_OBJECT_TYPE_IMAGE;
|
||||
nameInfo.objectHandle = (uint64_t)tex2d; // this cast may vary by platform/compiler
|
||||
nameInfo.pObjectName = "Off-screen color framebuffer";
|
||||
vkSetDebugUtilsObjectNameEXT(device, &nameInfo);
|
||||
|
||||
Bookmarks
|
||||
---------
|
||||
|
||||
@@ -1,77 +1,7 @@
|
||||
How do I view a specific texture?
|
||||
=================================
|
||||
|
||||
This page documents how to annotate your resources with user-friendly names to make it easier to follow use of them throughout the frame, as well as the functions for finding and following textures by name rather than by usage.
|
||||
|
||||
Annotating resources with names
|
||||
-------------------------------
|
||||
|
||||
It is much easier to browse and debug frames when the resources are given meaningful names - along with including :doc:`debugging information in shaders <how_debug_shader>` and marking up the frame with :doc:`hierarchical user-defined regions <../window/event_browser>`.
|
||||
|
||||
The way this is done varies by API. In D3D11 the resource is named using the ``SetPrivateData`` function:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
ID3D11Texture2D *tex2d = NULL;
|
||||
d3dDevice->CreateTexture2D(&descriptor, NULL, &tex2d);
|
||||
|
||||
// Give the buffer a useful name
|
||||
tex2d->SetPrivateData(WKPDID_D3DDebugObjectName, sizeof("Example Texture"), "Example Texture");
|
||||
|
||||
With D3D12 you can use the ``SetName`` function:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
ID3D12Resource *tex2d = NULL;
|
||||
d3dDevice->CreateCommittedResource(&heapProps, heapFlags, &descriptor, initState, &clearValue, __uuidof(ID3D12Resource), (void **)&tex2d);
|
||||
|
||||
// Give the buffer a useful name
|
||||
tex2d->SetName(L"Example Texture");
|
||||
|
||||
In OpenGL this can be done with ``GL_KHR_debug`` - ``glObjectLabel``.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
GLuint tex2d = 0;
|
||||
glGenTextures(1, &tex2d);
|
||||
glBindTexture(GL_TEXTURE_2D, tex2d);
|
||||
|
||||
// apply the name, -1 means NULL terminated
|
||||
glObjectLabel(GL_TEXTURE, tex2d, -1, "Example Texture");
|
||||
|
||||
In Vulkan you can enable the ``VK_EXT_debug_utils`` extension, which is provided by RenderDoc, and use the ``vkSetDebugUtilsObjectNameEXT`` function.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// At instance creation time, request the VK_EXT_debug_utils extension and
|
||||
// use vkGetInstanceProcAddr to obtain vkSetDebugUtilsObjectNameEXT
|
||||
|
||||
// create the image
|
||||
VkImage tex2d;
|
||||
vkCreateImage(device, &createInfo, NULL, &tex2d);
|
||||
|
||||
// set the name
|
||||
VkDebugUtilsObjectNameInfoEXT nameInfo = {};
|
||||
nameInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT;
|
||||
nameInfo.objectType = VK_OBJECT_TYPE_IMAGE;
|
||||
nameInfo.objectHandle = (uint64_t)tex2d; // this cast may vary by platform/compiler
|
||||
nameInfo.pObjectName = "Off-screen color framebuffer";
|
||||
vkSetDebugUtilsObjectNameEXT(device, &nameInfo);
|
||||
|
||||
When this texture is bound to the pipeline it will be listed like so:
|
||||
|
||||
.. figure:: ../imgs/Screenshots/NamedTex.png
|
||||
|
||||
Named Texture: The example texture bound with name displayed.
|
||||
|
||||
In a similar way any other resource can be named and this will be useful throughout the rest of the analysis. If a custom name is not provided, a default name will be generated - as seen above with the Render Pass and Framebuffer objects.
|
||||
This page documents how to open a specific texture by name, without needing to find it via a current resource binding.
|
||||
|
||||
Texture list in Texture Viewer
|
||||
------------------------------
|
||||
@@ -111,4 +41,5 @@ Opening a texture from the pipeline state viewer (:doc:`how_object_details`) wil
|
||||
See Also
|
||||
--------
|
||||
|
||||
* :doc:`../how/how_annotate_capture`
|
||||
* :doc:`../window/texture_viewer`
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
+4
-4
@@ -41,12 +41,12 @@
|
||||
</OBJECT>
|
||||
<UL>
|
||||
<LI> <OBJECT type="text/sitemap">
|
||||
<param name="Keyword" value="Annotating textures">
|
||||
<param name="Local" value="how/how_view_texture.html#annotating-resources-with-names">
|
||||
<param name="Keyword" value="Naming resources">
|
||||
<param name="Local" value="how/how_annotate_capture.html#application-provided-object-names">
|
||||
</OBJECT>
|
||||
<LI> <OBJECT type="text/sitemap">
|
||||
<param name="Keyword" value="Creating Event Hierarchy">
|
||||
<param name="Local" value="window/event_browser.html#annotating-your-frame">
|
||||
<param name="Keyword" value="Event marker annotations">
|
||||
<param name="Local" value="how/how_annotate_capture.html#application-provided-marker-regions">
|
||||
</OBJECT>
|
||||
<LI> <OBJECT type="text/sitemap">
|
||||
<param name="Keyword" value="Integrating RenderDoc functionality">
|
||||
|
||||
@@ -8,60 +8,9 @@ Annotating your frame
|
||||
|
||||
The Event Browser becomes most useful when the application has user-defined annotations of sections and subsections of the frames, to allow for a more logical and ordered browsing of the frame.
|
||||
|
||||
Doing this is API and platform specific. Example code for D3D11 is included below, using the ``D3DPERF`` library that is exported by ``d3d9.dll``, which can still be used in D3D11:
|
||||
Doing this is API and platform specific. More information on how to do it can be found in :doc:`../how/how_annotate_capture`.
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
D3DPERF_BeginEvent(0xffffffff, L"Start of example");
|
||||
|
||||
D3DPERF_BeginEvent(0xff00ff00, L"Sub section");
|
||||
// events inside the subsection
|
||||
D3DPERF_EndEvent();
|
||||
|
||||
// events outside the subsection
|
||||
D3DPERF_EndEvent();
|
||||
|
||||
// the newer ID3DUserDefinedAnnotation API is also supported
|
||||
ID3DUserDefinedAnnotation *annot;
|
||||
immediateContext->QueryInterface(__uuidof(ID3DUserDefinedAnnotation), (void **)&annot);
|
||||
|
||||
annot->BeginEvent(L"Sub section 2")
|
||||
|
||||
annot->EndEvent();
|
||||
|
||||
This will generate a section of the frame with a subsection that includes some events, and then some further events that are siblings of the subsection.
|
||||
|
||||
OpenGL can make use of the ``KHR_debug`` extension:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// omitted code to initialise the extension
|
||||
|
||||
glPushDebugGroupKHR(GL_DEBUG_SOURCE_APPLICATION, 0, -1, "Begin Section");
|
||||
|
||||
// contents of section here
|
||||
|
||||
glPopDebugGroupKHR();
|
||||
|
||||
Vulkan can use the ``VK_EXT_debug_utils`` extension:
|
||||
|
||||
.. highlight:: c++
|
||||
.. code:: c++
|
||||
|
||||
// omitted code to initialise the extension
|
||||
|
||||
VkCommandBuffer cmd = ...;
|
||||
|
||||
VkDebugUtilsLabelEXT markerInfo = {};
|
||||
markerInfo.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT;
|
||||
markerInfo.pLabelName = "Begin Section";
|
||||
vkCmdBeginDebugUtilsLabelEXT(cmd, &markerInfo);
|
||||
|
||||
// contents of section here
|
||||
|
||||
vkCmdEndDebugUtilsLabelEXT(cmd);
|
||||
The colours of any marker regions provided by these API functions will be used to markup the row for the region as well as showing a bar along the left side of the tree showing which regions an event is in.
|
||||
|
||||
Selecting available columns
|
||||
---------------------------
|
||||
@@ -98,7 +47,7 @@ The event browser is the primary way to browse through the frame. Events are lis
|
||||
|
||||
The currently selected event is highlighted and indicated with a green flag |flag_green|. This is the event that RenderDoc is inspecting and is reflected in all the other windows of the UI.
|
||||
|
||||
.. figure:: ../imgs/QuickStart/QuickStart4.png
|
||||
.. figure:: ../imgs/Screenshots/EventBrowserRegions.png
|
||||
|
||||
Current Event: The Event browser showing several sections and the current event.
|
||||
|
||||
@@ -163,3 +112,8 @@ When you hit enter to jump to an EID, the toolbar closes and if you wish to jump
|
||||
.. figure:: ../imgs/Screenshots/JumpEID.png
|
||||
|
||||
Jumping around: The jump-to-EID toolbar prompting for an event.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
* :doc:`../how/how_annotate_capture`
|
||||
|
||||
Reference in New Issue
Block a user