diff --git a/docs/how/how_annotate_capture.rst b/docs/how/how_annotate_capture.rst index 4e8680ee4..f1f2187a0 100644 --- a/docs/how/how_annotate_capture.rst +++ b/docs/how/how_annotate_capture.rst @@ -1,16 +1,28 @@ How do I annotate a capture? ============================ -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. - -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. +RenderDoc allows annotation of captures in multiple ways. Your application can call built-in debug functions in graphics APIs as well as custom RenderDoc APIs. You can also add extra annotations after opening 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 data +------------------------- + +Rich custom annotations +^^^^^^^^^^^^^^^^^^^^^^^ + +RenderDoc's :doc:`../in_application_api` provides mechanisms for annotating both objects and commands with rich structured annotations, which can be used by the application for including complex custom data for additional context and debug information beyond what is provided via baseline graphics APIs. + +The specific implementation details of how to pass this information along can be found in the documentation for the :doc:`../in_application_api`, via the :cpp:func:`SetObjectAnnotation` and :cpp:func:`SetCommandAnnotation` functions. The exact details may vary slightly by graphics API. + +For a high-level explanation of how the feature works and how to inspect and use it in the UI, see the :doc:`../window/annotation_viewer` documentation. + +.. figure:: ../imgs/Screenshots/CommandAnnotations.png + + Annotation Viewer: Showing the custom annotations on a selected event. + 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. @@ -96,7 +108,7 @@ Example code for Vulkan using the ``VK_EXT_debug_utils`` extension: // 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. @@ -183,9 +195,11 @@ On D3D12 there is a RenderDoc extension provided with this interface, queried fr This interface allows you to set a custom name for descriptors, if using SM6.6 style ``ResourceDescriptorHeap[]`` access for better debugging. +UI-side markup +-------------- Bookmarks ---------- +^^^^^^^^^ .. |asterisk_orange| image:: ../imgs/icons/asterisk_orange.png @@ -200,7 +214,7 @@ The |asterisk_orange| bookmark button will allow you to bookmark an event, the s When loading any capture with saved bookmarks they will be automatically populated into the UI. This will allow you to highlight particular problematic events and anyone opening the capture will be able to use the shortcuts above to jump immediately to where the problem is. Resource Renaming ------------------ +^^^^^^^^^^^^^^^^^ From within the :doc:`../window/resource_inspector` window, you can rename any resource in the capture. Whether the resource already had a custom-specified name, or if it had a default-generated name, you can provide overrides at any time. @@ -213,7 +227,7 @@ To do so, simply select the resource in question in the resource inspector - eit As with bookmarks, these renames can be saved with a capture and are automatically used when loading the capture subsequently. This can be useful to point the way to which resources are causing problems, or specifically how a given resource with a more general name is being used in this particular capture. Capture Comments ----------------- +^^^^^^^^^^^^^^^^ In the :doc:`../window/capture_comments` window there is a simple text field allowing you to store any arbitrary text you want within the capture. This could be notes on the environment or build version that was stored. diff --git a/docs/imgs/Screenshots/CommandAnnotations.png b/docs/imgs/Screenshots/CommandAnnotations.png new file mode 100644 index 000000000..2d2388ef2 Binary files /dev/null and b/docs/imgs/Screenshots/CommandAnnotations.png differ diff --git a/docs/imgs/Screenshots/EventAnnotFilter.png b/docs/imgs/Screenshots/EventAnnotFilter.png new file mode 100644 index 000000000..91afb249a Binary files /dev/null and b/docs/imgs/Screenshots/EventAnnotFilter.png differ diff --git a/docs/imgs/Screenshots/EventAnnotHighlight.png b/docs/imgs/Screenshots/EventAnnotHighlight.png new file mode 100644 index 000000000..11ef7f8ad Binary files /dev/null and b/docs/imgs/Screenshots/EventAnnotHighlight.png differ diff --git a/docs/imgs/Screenshots/ResourceAnnotations.png b/docs/imgs/Screenshots/ResourceAnnotations.png new file mode 100644 index 000000000..629473a09 Binary files /dev/null and b/docs/imgs/Screenshots/ResourceAnnotations.png differ diff --git a/docs/in_application_api.rst b/docs/in_application_api.rst index 298b1c389..f69fdeace 100644 --- a/docs/in_application_api.rst +++ b/docs/in_application_api.rst @@ -138,7 +138,7 @@ To do this you'll use your platforms dynamic library functions to see if the lib .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugOutputMute - specifies whether to mute any API debug output messages when `APIValidation` is enabled, and not pass them along to the application. Default is on. + specifies whether to mute any API debug output messages when ``APIValidation`` is enabled, and not pass them along to the application. Default is on. .. cpp:function:: uint32_t GetCaptureOptionU32(RENDERDOC_CaptureOption opt) @@ -331,8 +331,8 @@ To do this you'll use your platforms dynamic library functions to see if the lib :param uint32_t idx: specifies which capture to return the details of. Must be less than the return value of :cpp:func:`GetNumCaptures`. :param char* filename: is an optional parameter filled with the UTF-8 null-terminated path to the file. There must be enough space in the array to contain all characters including the null terminator. If set to NULL, nothing is written. - :param uint32_t* pathlength: is an optional parameter filled with the byte length of the above `filename` including the null terminator. If set to NULL, nothing is written. - :param uint64_t* timestamp: is an optional parameter filled with the 64-bit timestamp of the file - equivalent to the `time()` system call. If set to NULL, nothing is written. + :param uint32_t* pathlength: is an optional parameter filled with the byte length of the above ``filename`` including the null terminator. If set to NULL, nothing is written. + :param uint64_t* timestamp: is an optional parameter filled with the 64-bit timestamp of the file - equivalent to the ``time()`` system call. If set to NULL, nothing is written. :return: Returns ``1`` if the capture index was valid, or ``0`` if it was out of range. .. note:: @@ -391,7 +391,7 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i * For D3D12 it must be the ``ID3D12Device`` device object. * For OpenGL it must be the ``HGLRC``, ``GLXContext``, or ``EGLContext`` context object. * For OpenGLES it must be the ``EGLContext`` context object. - * For Vulkan it must be the dispatch table pointer within the ``VkInstance``. This is a pointer-sized value at the location pointed to by the ``VkInstance``. NOTE - this is not the actual ``VkInstance`` pointer itself. You can use the RENDERDOC_DEVICEPOINTER_FROM_VKINSTANCE helper macro defined in the renderdoc header to obtain this pointer from any VkInstance. + * For Vulkan it must be the dispatch table pointer within the ``VkInstance``. This is a pointer-sized value at the location pointed to by the ``VkInstance``. NOTE - this is not the actual ``VkInstance`` pointer itself. You can use the ``RENDERDOC_DEVICEPOINTER_FROM_VKINSTANCE()`` helper macro defined in the renderdoc header to obtain this pointer from any VkInstance. ``RENDERDOC_WindowHandle`` is a typedef to ``void *``. It is the platform specific Windows ``HWND``, Xcb ``xcb_window_t``, Xlib ``Window`` / ``Drawable``, Wayland ``wl_surface*``, or Android ``ANativeWindow*``. @@ -433,7 +433,7 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i ``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`. ``device`` and ``wndHandle`` can either or both be set to ``NULL`` to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. - Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`StartFrameCapture`. + Wildcard matching of ``device`` and ``wndHandle`` is described above in :cpp:func:`StartFrameCapture`. There will be undefined results if there is not an active frame capture for the device/window combination. @@ -451,7 +451,7 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i ``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`. ``device`` and ``wndHandle`` can either or both be set to ``NULL`` to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. - Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`StartFrameCapture`. + Wildcard matching of ``device`` and ``wndHandle`` is described above in :cpp:func:`StartFrameCapture`. There will be undefined results if there is not an active frame capture for the device/window combination. @@ -495,3 +495,142 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i Added in API version 1.2.0 +.. cpp:function:: void SetObjectAnnotation(RENDERDOC_DevicePointer device, void* object, const char *key, RENDERDOC_AnnotationType valueType, uint32_t valueVectorWidth, const RENDERDOC_AnnotationValue* value) + + This function allows associating custom rich annotations with API objects. These annotations can be examined in the :doc:`window/resource_inspector`. + + See the :doc:`window/annotation_viewer` documentation for more detailed information on the annotation system. + + :param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be ``NULL`` to wildcard match. + :param void* object: is a handle to the API object that will be annotated. Must not be ``NULL``. + :param const char* key: is a dot separated path for the annotation to update. Must not be ``NULL`` or empty. + :param RENDERDOC_AnnotationType valueType: is the type of value to set, including basic scalar types as well as strings and API objects. + :param uint32_t valueVectorWidth: is the vector width of the value to set, or 0 for scalars. Must be no greater than 4. + :param const RENDERDOC_AnnotationValue* value: is a pointer to the value itself. + + :return: Returns ``0`` if the annotation was successfully set. + + Returns ``1`` if the device is unknown or invalid. + + Returns ``2`` if the device is valid but the annotation is not recognised or not supported for API-specific reasons, such as an unrecognised or invalid object or queue/commandbuffer. + + Returns ``3`` if the call is ill-formed or invalid e.g. empty is specified with a value pointer, or non-empty is specified with a NULL value pointer. + + Deleting an annotation can be done by setting a value with ``valueType`` equal to ``eRENDERDOC_Empty`` and ``value`` equal to ``NULL``. This deletes the annotation at the specific key, as well as any children of that key. + + You can set ``valueVectorWidth`` to 0 for single values, which is equivalent to setting 1. This is required for strings and API objects, which can't be vectors. + + There are C++ helper structs ``RDGLObjectHelper`` and ``RDAnnotationHelper`` that can simplify code for specifying single scalar values. + +.. note:: + + For Vulkan, annotating ``VkInstance``, ``VkPhysicalDevice``, or ``VkDevice`` objects may encounter problems due to loader wrapping. To address this, you can use ``vkSetDebugUtilsObjectTagEXT`` to set a tag with the ``tagName`` set to ``RENDERDOC_APIObjectAnnotationHelper`` and the ``pTag`` set to the handle of the object itself. After doing that once RenderDoc will be able to recognise those handles. + + For OpenGL as it lacks proper object handles, the ``object`` parameter and any ``apiObject`` value must be a pointer to an instance of ``RENDERDOC_GLResourceReference`` which contains both a ``GLenum`` identifier with the same meaning as the parameter in ``glObjectLabel`` as well as the integer handle itself. + +.. note:: + + ``RENDERDOC_DevicePointer`` is described above in :cpp:func:`SetActiveWindow`. + ``device`` can be set to ``NULL`` to wildcard match against active devices. This wildcard matching can be used if the handle is difficult to obtain where annotations are set. + + Wildcard matching of ``device`` is described above in :cpp:func:`StartFrameCapture`. + +.. note:: + + Added in API version 1.7.0 + +.. cpp:enum:: RENDERDOC_AnnotationType + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Empty + + ``eRENDERDOC_Empty`` is used to delete an annotation. All children are also deleted. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Bool + + ``eRENDERDOC_Bool`` indicates that the ``boolean`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Int32 + + ``eRENDERDOC_Int32`` indicates that the ``int32`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_UInt32 + + ``eRENDERDOC_UInt32`` indicates that the ``uint32`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Int64 + + ``eRENDERDOC_Int64`` indicates that the ``int64`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_UInt64 + + ``eRENDERDOC_UInt64`` indicates that the ``uint64`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Float + + ``eRENDERDOC_Float`` indicates that the ``float32`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_Double + + ``eRENDERDOC_Double`` indicates that the ``float64`` member of ``RENDERDOC_AnnotationValue`` (or ``RENDERDOC_AnnotationVectorValue``) is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_String + + ``eRENDERDOC_String`` indicates that the ``string`` member of ``RENDERDOC_AnnotationValue`` is valid. + +.. cpp:enumerator:: RENDERDOC_AnnotationType::eRENDERDOC_APIObject + + ``eRENDERDOC_APIObject`` indicates that the ``apiObject`` member of ``RENDERDOC_AnnotationValue`` is valid. + +.. cpp:function:: void SetCommandAnnotation(RENDERDOC_DevicePointer device, void* queueOrCommandBuffer, const char* key, RENDERDOC_AnnotationType valueType, uint32_t valueVectorWidth, const RENDERDOC_AnnotationValue* value) + + This function allows adding custom rich annotations to command streams. These annotations can be examined in the :doc:`window/annotation_viewer` which has more information on the annotation system. + + For more information see the page on the :doc:`../window/annotation_viewer`. + + :param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be ``NULL`` to wildcard match. + :param void* queueOrCommandBuffer: is a handle to the API-specific command buffer or queue. + :param const char* key: is a dot separated path for the annotation to update. Must not be ``NULL`` or empty. + :param RENDERDOC_AnnotationType valueType: is the type of value to set, including basic scalar types as well as strings and API objects. + :param uint32_t valueVectorWidth: is the vector width of the value to set, or 0 for scalars. Must be no greater than 4. + :param const RENDERDOC_AnnotationValue* value: is a pointer to the value itself. + + :return: Returns ``0`` if the annotation was successfully set. + + Returns ``1`` if the device is unknown or invalid. + + Returns ``2`` if the device is valid but the annotation is not recognised or not supported for API-specific reasons, such as an unrecognised or invalid object or queue/commandbuffer. + + Returns ``3`` if the call is ill-formed or invalid e.g. empty is specified with a value pointer, or non-empty is specified with a NULL value pointer. + + Deleting an annotation can be done by setting a value with ``valueType`` equal to ``eRENDERDOC_Empty`` and ``value`` equal to ``NULL``. This deletes the annotation at the specific key, as well as any children of that key. + + You can set ``valueVectorWidth`` to 0 for single values, which is equivalent to setting 1. This is required for strings and API objects, which can't be vectors. + + There are C++ helper structs ``RDGLObjectHelper`` and ``RDAnnotationHelper`` that can simplify code for specifying single scalar values. + + The ``queueOrCommandBuffer`` parameter refers to a different object depending on the API: + + * On Vulkan, it can either be a ``VkCommandBuffer`` in the recording state, or a ``VkQueue``. + * On OpenGL, it must be ``NULL``. + * On D3D11 it must either be ``NULL`` or the immediate context ``ID3D11DeviceContext*``. + * On D3D12 it must either be an ``ID3D12GraphicsCommandList*`` or a ``ID3D12CommandQueue*``. + +.. note:: + + For Vulkan, annotating ``VkInstance``, ``VkPhysicalDevice``, or ``VkDevice`` objects may encounter problems due to loader wrapping. To address this, you can use ``vkSetDebugUtilsObjectTagEXT`` to set a tag with the ``tagName`` set to ``RENDERDOC_APIObjectAnnotationHelper`` and the ``pTag`` set to the handle of the object itself. After doing that once RenderDoc will be able to recognise those handles. + + For OpenGL as it lacks proper object handles, any ``apiObject`` values must be a pointer to an instance of ``RENDERDOC_GLResourceReference`` which contains both a ``GLenum`` identifier with the same meaning as the parameter in ``glObjectLabel`` as well as the integer handle itself. + The ``queueOrCommandBuffer`` parameter must be ``NULL``. + + For D3D11 the ``queueOrCommandBuffer`` parameter must be either the immediate context or ``NULL``. + +.. note:: + + ``RENDERDOC_DevicePointer`` is described above in :cpp:func:`SetActiveWindow`. + ``device`` can be set to ``NULL`` to wildcard match against active devices. This wildcard matching can be used if the handle is difficult to obtain where annotations are set. + + Wildcard matching of ``device`` is described above in :cpp:func:`StartFrameCapture`. + +.. note:: + + Added in API version 1.7.0 diff --git a/docs/python_api/qrenderdoc/windows.rst b/docs/python_api/qrenderdoc/windows.rst index a47757e90..b0ff66cc5 100644 --- a/docs/python_api/qrenderdoc/windows.rst +++ b/docs/python_api/qrenderdoc/windows.rst @@ -42,6 +42,12 @@ Descriptor Viewer .. autoclass:: qrenderdoc.DescriptorViewer :members: +Annotation Viewer +----------------- + +.. autoclass:: qrenderdoc.AnnotationViewer + :members: + Texture Viewer -------------- diff --git a/docs/window/annotation_viewer.rst b/docs/window/annotation_viewer.rst new file mode 100644 index 000000000..65044b9dc --- /dev/null +++ b/docs/window/annotation_viewer.rst @@ -0,0 +1,123 @@ +Annotation Viewer +================= + +The annotation viewer window provides information on the per-command annotations provided by the application. By default it is hidden, if loading a capture with annotations included the viewer will be shown if it has never previously been used. + +This page describes both the general annotation system as well as the specific viewer for per-command annotations. + +.. figure:: ../imgs/Screenshots/CommandAnnotations.png + + Annotation Viewer: Showing the custom annotations on a selected event. + +Individual annotations can be strings, scalar values (integers, floats, bools), up to 4-wide vectors of those same types, as well as other API objects. + +Annotations are set in an arbitrary user-specified hierarchy as determined by a dot-separated path. When displayed, paths are sorted with a natural sort so arrays can be created by using paths such as ``custom.list.0``, ``custom.list.1``, and so on. + +.. note:: + + It is also possible to associate the same annotations with an object itself which can be viewed in a section in the :doc:`resource_inspector`. + +Viewing command annotations +--------------------------- + +When opening a capture with annotations, if it hasn't been displayed before the Annotation Viewer will open and by default be docked onto the :doc:`api_inspector`. If you have closed the Annotation Viewer you will have to open it from the :guilabel:`Window` menu. + +The Annotation Viewer will then show the set of annotations for the current event. These can be expanded and examined at will, and as different events are selected the annotations for each of those events will be shown. + +When right clicking on an annotation, it can be selected for previewing in a column in the event browser. This is only possible for scalar values, but if a particular path is selected then a new column will be shown on the event browser that shows the value of that annotation (or nothing, if it is absent) at each event. + +.. figure:: ../imgs/Screenshots/EventAnnotHighlight.png + + Event Browser: Showing a given annotation as a column on each event. + +Viewing object annotations +-------------------------- + +Annotations set on objects rather than commands are visible via the :doc:`resource_inspector`, when a capture contains annotations a panel will be shown with any annotations for the selected resource. + +As different resources are selected, the same set of annotations will be displayed if there is overlap, so for example viewing a nested entry ``custom.nested.value`` it will stay expanded if a different resource is selected which also has that annotation. + +The display is the same as for command annotations above in the Annotation Viewer. + +.. figure:: ../imgs/Screenshots/ResourceAnnotations.png + + Resource Inspector: Viewing the annotations applied to an image in the resource inspector. + +API usage +------------------- + +The annotations are provided via the :doc:`../in_application_api` as the :cpp:func:`SetObjectAnnotation` and :cpp:func:`SetCommandAnnotation` functions, the documentation page for which provides the specific API reference. + +These can be wrapped in helper functions as desired to make it easier to integrate with an application's codebase. + +.. tip:: + To explicitly remove annotations, you can set a value with ``valueType`` equal to ``eRENDERDOC_Empty`` and ``value`` equal to ``NULL``. This will delete the annotation at that path and all children. + +Annotations can be set on objects at any time. The latest contents of these annotations are saved when the capture ends and do not vary depending on the current event. This means that any modifications to object annotations during a capture will be shown, but selecting different events will not change the annotations on an object. If you need annotations that vary by event, you can use command annotations. + +Annotations on commands begin empty at the start of a capture, and are stored per-event with each event able to have a unique set of annotations. + +Vulkan and D3D12 have both queue-level and command buffer-level annotations, OpenGL and D3D11 only having one immediate level of annotations. When dealing with both queue and command buffer annotations, the queue annotations persist globally on each queue, and command buffer annotations are layered on top for the duration of that command buffer. + +Examples +^^^^^^^^ + +As a simple example of adding an annotation to an object on D3D11, assuming an ``rdoc`` pointer to the 1.7 API function structure: + +.. highlight:: c++ +.. code:: c++ + + void AnnotateImage(ID3D11Device *dev, ID3D11Texture2D *tex, ID3D11Buffer *buf) + { + // using the RDAnnotationHelper to minimise typing for simple scalar values + rdoc->SetObjectAnnotation(dev, tex, "custom.texture_flags", eRENDERDOC_Int32, 0, RDAnnotationHelper(16)); + + // referring to an object, using the temporary value structure + RENDERDOC_AnnotationValue val; + val.apiObject = (void *)buf; + rdoc->SetObjectAnnotation(dev, tex, "custom.associated_buffer", eRENDERDOC_APIObject, 0, &val); + } + +And similarly an example of adding a command annotation on Vulkan: + +.. highlight:: c++ +.. code:: c++ + + void AnnotateCommand(VkInstance inst, VkCommandBuffer cmd) + { + void *dev = RENDERDOC_DEVICEPOINTER_FROM_VKINSTANCE(inst); + rdoc->SetCommandAnnotation(dev, cmd, "draw_mesh.my_property", eRENDERDOC_Int32, 0, + RDAnnotationHelper(200)); + + rdoc->SetCommandAnnotation(dev, cmd, "draw_mesh.source_name", eRENDERDOC_String, 0, + RDAnnotationHelper("Default_Model.file")); + } + +Special object properties +------------------------- + +When specifying an object, certain properties can be provided for convenience of display. With a buffer resource you can specify both ``resource`` as the API object, as well as ``resource.__offset`` and ``resource.__size`` to specify a particular sub-range of that buffer. When opening the resource from the annotation viewer or resource inspector the buffer viewer will pre-fill this particular range. + +You can also specify ``resource.__rd__format`` as a string to provide a text-based buffer format to pre-fill in the buffer viewer, for more information see :doc:`../how/how_buffer_format`. You can also specify a ``__rd_format`` annotation on an object itself as well to provide a 'default' format. + +.. note:: + + These properties and any other properties prefixed with ``__`` will not be visible normally, and will only come into effect when applied in these ways. + +Event filtering +--------------- + +The event browser filtering system also has a function for filtering based on annotations ``$annot()``. + +This function can be used to filter the visible events, based on their annotation values. For example an expression like ``$annot(foo.bar > 5)`` will only display events where the annotation ``foo.bar`` is present, and stores a number greater than 5. Expressions can also filter based on strings using ``$annot(foo.bar contains "qux")`` or regular expression matching such as ``$annot(foo.bar =~ /qu[xz])``. + +.. figure:: ../imgs/Screenshots/EventAnnotFilter.png + + Event Browser: Filtering the visible events based on an annotation. + +Python access +------------- + +Annotations on commands can be accessed via :py:attr:`renderdoc.APIEvent.annotations`, which is an optional :py:class:`~renderdoc.SDObject` object that can be accessed recursively. Helper functions like :py:meth:`~renderdoc.SDObject.FindChildByKeyPath` can be used to speed up accessing a specific annotation. + +Annotations on objects are available in a similar way through :py:attr:`renderdoc.ResourceDescription.annotations`. \ No newline at end of file diff --git a/docs/window/index.rst b/docs/window/index.rst index 8b6f1ac37..b9d85c3ce 100644 --- a/docs/window/index.rst +++ b/docs/window/index.rst @@ -2,20 +2,21 @@ Window reference ================ .. toctree:: - texture_viewer + annotation_viewer api_inspector - mesh_viewer buffer_viewer capture_attach - event_browser - settings_window - pipeline_state - shader_viewer - shader_messages - timeline_bar + capture_comments capture_connection debug_messages + event_browser + mesh_viewer + performance_counter_viewer + pipeline_state python_shell resource_inspector - performance_counter_viewer - capture_comments + settings_window + shader_messages + shader_viewer + texture_viewer + timeline_bar \ No newline at end of file diff --git a/docs/window/resource_inspector.rst b/docs/window/resource_inspector.rst index 7b68f3bd9..0629c67c4 100644 --- a/docs/window/resource_inspector.rst +++ b/docs/window/resource_inspector.rst @@ -25,6 +25,15 @@ Some resources such as textures and buffers have information available about whe In this list, each entry lists an EID range and a type of usage. +Annotations +----------- + +Resources can optionally have deep structured annotations provided by the application via the :doc:`../in_application_api`. For annotations applied to objects, they are displayed here under the key paths provided. + +For more information on the annotation system in general see the :doc:`annotation_viewer`. + +This view is hidden if there are no annotations in the capture. + Resource Initialisation Parameters ----------------------------------