Update documentation for event browser changes

docs/getting_started/quick_start.rst

@@ -89,7 +89,9 @@ More details can be found on the :doc:`../window/event_browser` page.
 
 .. |timeline_marker| image:: ../imgs/icons/timeline_marker.png
 
-The Event Browser is the primary method of stepping through the frame and browsing the events that occurred within. The first column EID (Event ID) indicates which event or API call this was in the frame, chronologically. Events which are listed here are known as actions. Actions are draws and dispatches but also events that modify resources like clears and copies. State setting and other CPU-update calls like Maps are not included and are available in the API Calls view (see below).
+The Event Browser is the primary method of stepping through the frame and browsing the events that occurred within. The first column EID (Event ID) indicates which event or API call this was in the frame, chronologically. 
+
+By default the events which are listed here are those known as actions. Draws and dispatches are examples of actions, but also events that modify resources like clears and copies. State setting and other CPU-update calls like Maps are not included and are available in the API Calls view (see below). You can use the filter field to include or exclude events as you wish, for more information see :doc:`../how/how_filter_events`.
 
 The columns can be customised and reordered, the |timeline_marker| select columns button (or right-click) will allow you to choose which columns are displayed.
 
@@ -101,7 +103,7 @@ Standard performance markers are available and create the hierarchy/labels as yo
 
 The 'current' event - i.e. the event at which we are inspecting the graphics state - is highlighted with a green Flag |flag_green| and the row is highlighted. As any row is selected it immediately becomes the new current event.
 
-While the Event Browser is selected, you can press the shortcut keys :kbd:`CTRL-F` or :kbd:`CTRL-G` to find |find| or jump to a given EID |flag_green| respectively.
+While the Event Browser is selected, you can press the shortcut keys :kbd:`CTRL-F` to find |find| a given event or action. You can enter a number to jump to that given EID.
 
 
 The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`CTRL-B`.
@@ -119,7 +121,7 @@ API Inspector
 
 More details can be found on the :doc:`../window/api_inspector` page.
 
-The API Calls window updates as a new event is selected. It shows the individual API calls and their parameters between the previous and current event. The bottom entry in this list always corresponds to the event that is currently selected, and each row can be expanded to show the parameters that were passed to that API call.
+The API Calls window updates as a new event is selected. It shows the individual API calls and their parameters. If an action is selected, the list shows all API calls between the previous action and this action and the last entry in this list always corresponds to the action itself. Each row can be expanded to show the parameters that were passed to that API call.
 
 At the bottom of the window is an optional expandable section which shows the callstack (if available and recorded) from the application code into the API function.
 

docs/how/how_filter_events.rst

@@ -0,0 +1,132 @@
+How do I filter visible events?
+===============================
+
+The :doc:`Event Browser window <../window/event_browser>` allows you to browse through the frame by changing the current event, and seeing a list of events in the capture organised into a user-defined hierarchy of markers (for more information on how to provide these markers, see :doc:`how_annotate_capture`).
+
+By default the events which are listed are those known as actions. Draws and dispatches are examples of actions, but also events that modify resources like clears and copies. State setting and other CPU-update calls like Maps are not included and are listed in the :doc:`API Inspector <../window/api_inspector>`.
+
+With event filters you can control which events are displayed, to include or exclude them based on substrings or more complex filters.
+
+Filter Expressions
+------------------
+
+At the most basic level filters act like a search query across all the events in a capture. If several terms are given together:
+
+.. code:: text
+    
+    Draw Clear Copy
+
+This will include any event that matches any one of these terms. For example ``DrawIndexed()`` and ``Draw()`` would both match ``Draw`` and so would be displayed even if they don't match ``Clear`` or ``Copy``. ``Dispatch()`` would be filtered out because it doesn't match any of these terms.
+
+You can also exclude specific terms by prefixing them with a ``-``:
+
+.. code:: text
+    
+    Draw Clear Copy -Depth 
+
+Which will still display ``DrawIndexed()`` and ``Draw()`` as before, as well as for example ``ClearColor()``. However ``ClearDepth()`` would be filtered out because it matches the ``-Depth`` term.
+
+If you don't want to have all terms be optional, you can instead require specific terms:
+
+.. code:: text
+    
+    +Draw +Indexed -Instanced
+
+This requires that events **must** match ``Draw`` and ``Indexed`` and **must not** match ``Instanced``. This means ``DrawIndexed()`` would be displayed because it satisfies all terms, but ``Draw()`` would now be filtered out because although it matches ``Draw`` it does not match ``Indexed``. Similarly ``DrawIndexedInstanced()`` would be filtered out because while it matches both required terms, it also matches the excluded term.
+
+.. warning::
+    If you have some required terms like this then any optional terms are completely ignored. ``+Draw -Instanced`` would match the same events as ``+Draw Dispatch -Instanced``. This is because an event will be included only if it matches the required term and excluded if it doesn't, there's no room for an optional match.
+    
+    This is unlike a more flexible search which can use optional terms to weight some results higher than others, since events are always listed in their explicit order.
+
+Filters can also be nested with parentheses, for example if you wanted to require at least one of several matches:
+
+.. code:: text
+    
+    +Draw +(Indexed Instanced) -Indirect
+
+Which requires that events **must** match ``Draw``, and **must** match at least one of ``Indexed`` or ``Instanced``.
+
+Filter functions
+----------------
+
+The examples above all used simple string matching, which can be enough for many cases but sometimes a more complex query is desired. For this reason there are filter functions, which can query properties with more flexibility.
+
+The default filter is an example of this, the ``$action()`` filter function will match any action - draws, dispatches, copies, clears, etc.
+
+.. figure:: ../imgs/Screenshots/EventsDefaultDisplay.png
+
+	Default Display: The Event browser with the default event filter applied.
+
+The ``$action()`` filter function can also take parameters, for example here we will filter for only actions which are draws with over 1000 indices or vertices:
+
+.. figure:: ../imgs/Screenshots/EventsFiltered1000Indices.png
+
+	Filtered Display: The Event browser with only draws containing more than 1000 indices.
+
+Other filter functions are available, for example ``$parent(...)`` will match events that have a given marker as a parent, so we could filter to only the draws in the scene and not in the off-screen pass:
+
+.. figure:: ../imgs/Screenshots/EventsFilteredParent.png
+
+	Filtered Display: The Event browser with only draws containing more than 1000 indices underneath the 'Render Scene' marker.
+
+Notice how we changed the filter to require both ``$action(numIndices > 1000)`` as well as ``$parent(render scene)``. If we didn't, we would include all draws with 1000 vertices as well as all events under Render Scene - which isn't what we wanted in this case.
+
+.. note::
+
+    As seen above, any marker regions which don't have any included child events (recursively) will be hidden entirely.
+
+There are many other filter functions and it is also possible to register custom filter functions as a python extension, you can explore the available functions and their documentation in the filter settings menu.
+
+Example
+-------
+
+We'll give another real world example of how to selectively include or exclude events. Starting with the same case as above:
+
+.. figure:: ../imgs/Screenshots/EventsDefaultDisplay.png
+
+	Default Display: The Event browser with the default event filter applied.
+
+We want to see when bindings are changed in addition to the draws. To do this we'll add ``Bind`` as an optional term:
+
+.. figure:: ../imgs/Screenshots/EventsFilteredBind.png
+
+	Actions and binds: The filter including binding calls as well as actions.
+
+Now we can see the pipeline and vertex/index buffer binds that happened before the first drawcall. In this case there aren't other binding changes between the later drawcalls visible.
+
+Let's say that we only care about buffer bindings and want to exclude the pipeline bind. We could do this by adding a ``-Pipeline`` term, but we might then have to exclude other types of bindings and that could get tedious. Instead we'll change the bind term to ``(+Bind +Buffer)`` which will only match events that contain ``Bind`` and ``Buffer``. Since the term itself is optional, this still means actions are included.
+
+.. note::
+    This could be accomplished another way such as usuing a regular expression, but for the sake of example we'll do it like this.
+
+.. figure:: ../imgs/Screenshots/EventsFilteredBindBuffer.png
+
+	Actions and binds: The filter narrows to include only buffer binding calls.
+
+Now we can see the buffer binding calls as well as the actions that we wanted. At this point we might find that the markers setting object names are a little too noisy, so we want to exclude them. Since there isn't necessarily a common substring with these object names we can instead exclude all markers by type. Markers are a type of action, so we can match against the action flags containing the flag indicating a set marker.
+
+.. figure:: ../imgs/Screenshots/EventsFilteredBindBufferNoAction.png
+
+	Actions and binds: The final filter, excluding set markers from the previous filters.
+
+Finally we have the filter expression matching only the events we want. We can further include/exclude events as we wish in a similar way, or we could save this filter for later in the settings window if this is a filter we will want to have available regularly.
+
+Filter settings
+---------------
+
+The filter settings window contains an explanation of the current filter and what it matches against, as well as ways to save/load filters, and documentation for the available filter functions.
+
+.. figure:: ../imgs/Screenshots/EventFilterSettingsHelp.png
+
+	Filter settings: The filter settings window, showing the example query above explained.
+
+At the top the filter is editable in the same way as in the main Event Browser, and once parsed it will be highlighted showing each term corresponding to the explanation in the panel below.
+
+.. |save| image:: ../imgs/icons/save.png
+
+The filter can be saved by pressing the |save| Save button. By giving the filter a name you can then re-select this filter in future. Changes to filters are only applied when explicitly saving them here, if you select a filter and edit it then those changes will not be saved.
+
+You can also export or import the whole set of filters here with the save drop-down menu. This will overwrite your current set of filters.
+
+At the bottom there is documentation similar to here about how the filter syntax works and in particular for each of the available filter functions how they work and what parameters they support.

docs/how/index.rst

@@ -5,6 +5,7 @@ How do I ...?
 
 	how_capture_frame
 	how_android_capture
+	how_filter_events
 	how_debug_shader
 	how_inspect_pixel
 	how_view_texture

docs/window/api_inspector.rst

@@ -6,7 +6,9 @@ Although not the most complex part of the RenderDoc's UI, this page details the
 UI Elements
 -----------
 
-The API Inspector is divided into two sections - the top section is the most common, detailing all of the API calls leading up to and including the current action. The special case for this is the end of the frame where there may not be a final action but the API Inspector lists the API calls that preceded the final flip of the backbuffer that marks the end of RenderDoc's captured frame.
+The API Inspector is divided into two sections - the top section is the most common, detailing the API calls and all of their parameters.
+
+If an action is currently selected in the :doc:`event_browser`, all the API calls between the previous action and this action will be shown - in other words if you select a draw, this may show several state-setting API calls binding shaders or resources before the draw. If an individual event is currently selected then that event's API call will be shown.
 
 The bottom section is less commonly used but shows the callstack from user code into the API entry point, if such a callstack is available and the symbols are resolved. For more information check out the page on :doc:`../how/how_capture_callstack`.
 

docs/window/event_browser.rst

@@ -12,6 +12,61 @@ Doing this is API and platform specific. More information on how to do it can be
 
 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.
 
+Filtering displayed events
+--------------------------
+
+By default the Event Browser only lists actions. Actions are events like draws, dispatches, copies, clears, resolves, and other calls that cause the GPU to do work or can affect memory and resources like textures and buffers. This is sometimes referred to as a drawcall, but the term action is used to be less ambiguous compared to actual rasterization drawing.
+
+Often these are the only events you need to see to browse the frame, but there are cases where you may want to see some state setting calls to see where state is changed. To do this you can change the filter on the event browser from the default to include them.
+
+Filter expressions can be quite complex and are explained in :doc:`../how/how_filter_events`.
+
+The filter expression has a drop-down which allows you to select any of the pre-saved filters, and you can save new filters in the settings window.
+
+Event display
+-------------
+
+Events displayed in the Event Browser are typically derived from the parameters to the API call itself. A small number of events will have custom generated names - these are typically for example indirect draws where it is more useful to see the used GPU draw parameters instead of the raw CPU side buffer, or for renderpasses where the load and store ops can be displayed.
+
+There are controls to tweak these names available under the :menu:`Settings & Help` window when configuring the filter.
+
+To show these options by way of example, take this default display of a section of a captured frame:
+
+.. figure:: ../imgs/Screenshots/EventsDefaultDisplay.png
+
+	Default Display: The Event browser with the default event naming.
+
+| :guilabel:`Show custom action names` Default: ``Enabled``
+
+This option controls whether the custom names are used as detailed above for e.g. indirect draws and renderpasses. Note the effect that disabling it has on the renderpass beginning and command buffer boundary.
+
+.. figure:: ../imgs/Screenshots/EventsNoCustom.png
+
+	Disabled Custom Action Names: The Event browser with custom names disabled.
+
+| :guilabel:`Show parameter names and values` Default: ``Disabled``
+
+This option controls whether the names of parameters are included as well as their values. By default no parameter names are given and only the values are visible.
+
+.. note::
+	This will have no effect on actions with custom names, as controlled above in :guilabel:`Show custom action names`.
+
+.. figure:: ../imgs/Screenshots/EventsParameterNames.png
+
+	Parameter names: The Event browser with parameter names displayed as well as parameter values.
+
+| :guilabel:`Show all parameters` Default: ``Disabled``
+
+This option controls whether all parameters are displayed, or whether only the most significant ones are included. Note that with all parameters displayed it can be hard to make anything out as some functions have uninteresting implicit parameters like the command buffer.
+
+.. note::
+	This does not affect parameter values, which in the case of structures will still only show an elided struct in many cases. Also as above with :guilabel:`Show parameter names and values` this will have no effect on actions with custom names, as controlled above in :guilabel:`Show custom action names`.
+
+.. figure:: ../imgs/Screenshots/EventsAllParameters.png
+
+	All Parameters: A snippet of the Event browser showing all function parameters.
+
+
 Selecting available columns
 ---------------------------
 
@@ -51,9 +106,9 @@ The currently selected event is highlighted and indicated with a green flag |fla
 
 	Current Event: The Event browser showing several sections and the current event.
 
-The EID column indicates the event ID of the action listed. Event IDs are assigned starting from 1 and increase every time an API call is made - for this reason action EIDs are not necessarily contiguous.
+The EID (Event ID) column indicates the ID of the event. Event IDs are assigned starting from 1 and increase every time an API call is made. For this reason action EIDs are usually not contiguous because there are state setting events in between which also have EIDs.
 
-Simply clicking on a different event will select it as current, and selecting a parent node with some child events will act as if the final child is selected - in other words selecting a node with several children will show the results of all children having happened.
+Simply clicking on a different event will select it as current, and selecting an entry with some child events will act as if the final child is selected - in other words selecting a node with several children will show the results of all children having happened.
 
 You can also use keyboard shortcuts to browse through the frame. Pressing up or down arrow key will move up and down through the visible elements, skipping over any sections which are collapsed. These keys will move into and out of a sub-section into the next sibling afterwards - essentially going straight up and down as if there is not a tree and it is a straight list.
 
@@ -87,32 +142,25 @@ There are two other controls available in the Event Browser to aid in navigating
 
 Pressing :kbd:`Ctrl-F` will open the find-event toolbar |find|. This toolbar allows you to type in a partial text filter that will be matched against both labels and action events. The find will be executed when you press enter, although you can then adjust the text and re-search if you wish.
 
+.. tip::
+
+	If you want to go to a particular event you can search for its EID. The find results will only show the matching event, and not any other events which might match that number by substring.
+
 If the event found lies inside an unexpanded section, the sections will be expanded until the matching event is visible.
 
 Matching events will be highlighted with a find icon |find|, and pressing enter repeatedly will jump between matching events.
 
-.. |cross| image:: ../imgs/icons/cross.png
-
-The find toolbar isn't dismissed until you press escape in the text box, or click the close button |cross|.
+The find toolbar isn't dismissed until you press escape in the text box, or click on the find-event tool button |find| again.
 
 .. |arrow_left| image:: ../imgs/icons/arrow_left.png
 .. |arrow_right| image:: ../imgs/icons/arrow_right.png
 
-
 You can also jump up and down between find results with the previous |arrow_left| and next |arrow_right| buttons.
 
 .. figure:: ../imgs/Screenshots/FindResults.png
 
 	Highlighted Results: The results of a find are highlighted with an icon.
 
-Pressing :kbd:`Ctrl-G` will open the jump to EID toolbar. This allows you to type in an EID and jump straight there, expanding nodes as necessary. If the EID typed doesn't exist in the list of actions, the closest matching EID will be jumped to.
-
-When you hit enter to jump to an EID, the toolbar closes and if you wish to jump again you must press :kbd:`Ctrl-G` again
-
-.. figure:: ../imgs/Screenshots/JumpEID.png
-
-	Jumping around: The jump-to-EID toolbar prompting for an event.
-
 See Also
 --------