$regex(/my regex.*match/i) | - passes if the specified regex matches the event name.
This filter can be used to do regex matching against events. The regex itself must be surrounded with //s. The syntax is perl-like and supports perl compatible options after the trailing /: - /i - Case insensitive match - /x - Extended syntax. See regex documentation for more information - /u - Use unicode properties. Character classes like \w and \d match more than ASCII +
+ +| /i | - Case insensitive match | +
| /x | - Extended syntax. See regex documentation for more information | +
| /u | - Use unicode properties. Character classes like \w and \d match more than ASCII | +
$param(name: value)+ $param(name = value) | - passes if a given parameter matches a value. |
This filter searches through the parameters to each API call to find a matching name. The name is specified case-sensitive and can be at any nesting level. The value is searched for as a case-insensitive substring. +
)EOD", "EventFilterModel"); } @@ -1723,14 +1740,25 @@ searched for as a case-insensitive substring. QString filterDescription_event() const { return tr(R"EOD( -$event(condition) - passes if an event property matches a condition. +$event(condition) | - passes if an event property matches a condition.
This filter queries given properties of an event to match simple conditions. A
-condition must be specified, and only one condition can be queried in each $event().
+condition must be specified, and only one condition can be queried in each $event().
+
+Available numeric properties. Compare with $event(prop > 100) or $event(prop <= 200).
+
| EID: | The event's EID. |
| $draw() | - passes if an event is a drawcall. |
| $draw(condition) | - passes if an event is a drawcall and matches a condition. |
+If no condition is specified then the event is just included if it's a draw-type event - meaning any
+event such as drawcalls, dispatches, copies, clears and others that do work and modify resources.
Otherwise the event is included if it's a draw AND if the condition is true.
+
Available numeric properties. Compare with $draw(prop > 100) or $draw(prop <= 200)
| EID: | The draw's EID. |
| drawId: | The draw ID, starting from 1 and numbering each draw. |
| numIndices: | The number of vertices or indices in a draw. |
| baseVertex: | The base vertex value for an indexed draw. |
| indexOffset: | The index offset for an indexed draw. |
| vertexOffset: | The vertex offset for a non-indexed draw. |
| instanceOffset: | The instance offset for an instanced draw. |
| dispatchX: | The number of groups in the X dimension of a dispatch. |
| dispatchY: | The number of groups in the Y dimension of a dispatch. |
| dispatchZ: | The number of groups in the Z dimension of a dispatch. |
| dispatchSize: | The total number of groups (X * Y * Z) of a dispatch. |
| duration: | The listed duration of a drawcall (only available with durations). |
+Also available is the flags property. Drawcalls have different flags and properties
+and these can be queried with a filter such as $draw(flags & Clear|ClearDepthStencil)
+
The flags available are:
+ +| Clear: | This is a clear call, clearing all or a subset of a resource. |
| Drawcall: | This is a graphics pipeline drawcall, rasterizing polygons. |
| Dispatch: | This is a compute dispatch. |
| CmdList: | This is part of the book-keeping for a command list, secondary command buffer or bundle. |
| SetMarker: | This is an individual string debug marker, with no children. |
| PushMarker: | This is a push of a debug marker region, with some child drawcalls |
| PopMarker: | This is the pop of a debug marker region. |
| Present: | This is a graphics present to a window. |
| MultiDraw: | This is part of a multi-draw drawcall. |
| Copy: | This is a copy call, copying between one resource and another. |
| Resolve: | This is a resolve or non-identical blit, as opposed to a copy. |
| GenMips: | This call is generating mip-maps for a texture |
| PassBoundary: | This is the boundary of a 'pass' explicitly denoted by the API. |
| Indexed: | For graphics pipeline drawcalls, the call uses an index buffer. |
| Instanced: | For graphics pipeline drawcalls, the call uses instancing. |
| Auto: | For graphics pipeline drawcalls, it's automatic based on stream-out. |
| Indirect: | This is an indirect call, sourcing parameters from the GPU. |
| ClearColor: | For clear calls, color values are cleared. |
| ClearDepthStencil: | For clear calls, depth/stencil values are cleared. |
| BeginPass: | For pass boundaries, this begins a pass. A boundary could begin and end. |
| EndPass: | For pass boundaries, this ends a pass. A boundary could begin and end. |
| CommandBufferBoundary: | This denotes the boundary of an entire command buffer. |
| $dispatch() | - passes if an event is a dispatch. |
| $dispatch(condition) | - passes if an event is a dispatch and matches a condition. |
+If no condition is specified then the event is just included if it's a dispatch.
Otherwise the event is included if it's a dispatch AND if the condition is true.
+
Available numeric properties. Compare with $dispatch(prop > 100) or
+$dispatch(prop <= 200)
| EID: | The dispatch's EID. |
| drawId: | The dispatch's draw ID, starting from 1 and numbering each draw-type event. |
| x: | The number of groups in the X dimension of the dispatch. |
| y: | The number of groups in the Y dimension of the dispatch. |
| z: | The number of groups in the Z dimension of the dispatch. |
| size: | The total number of groups (X * Y * Z) of the dispatch. |
| duration: | The listed duration of the dispatch (only available with durations). |
| $parent(marker) +$childOf(marker) |
+- passes if an event is contained somewhere under a marker of the given name. |
Both aliases of this filter function in the same way. Any event that is a child of the given markers will pass the filter. This applies not just to immediate children but any grandchildren or further -nested. +nesting level. +
)EOD", "EventFilterModel"); } @@ -3933,65 +4014,93 @@ void EventBrowser::CreateFilterDialog() QString f = current->text(); if(m_FilterSettings.FuncList->row(current) == 0) { - m_FilterSettings.FuncDocs->setText(tr(R"EOD( -General filter help + m_FilterSettings.FuncDocs->setHtml(tr(R"EOD( +Filters loosely follow a general search-term syntax, by default matching an event if any of the terms matches. E.g. a filter such as: +
- Draw Clear Copy +
Draw Clear Copy+
would match each string against event names, and include any event that matches
-"Draw" OR "Clear" OR "Copy".
+Draw OR Clear OR Copy.
+
You can also exclude matches with - such as: +
- Draw Clear Copy -Depth +Draw Clear Copy -Depth+
which will match as in the first example, except exclude any events that match
-'Depth'.
+Depth.
+
You can also require matches, which overrides any optional matches: +
- +Draw +Indexed -Instanced ++Draw +Indexed -Instanced-which will match only events which match "Draw" and match "Indexed" but don't match -"Instanced". In this case adding a term with no + or - prefix will be ignored, +
+which will match only events which match Draw and match Indexed but don't match
+Instanced. In this case adding a term with no + or - prefix will be ignored,
since an event will be excluded if it doesn't match all the +required terms
anyway.
+
More complex expressions can be built with nesting: +
-+Draw +(Indexed Instanced) -Indirect ++Draw +(Indexed Instanced) -Indirect-Would match only events matching "Draw" which also match at least one of "Indexed" -or "Instanced" but not "Indirect". +
+Would match only events matching Draw which also match at least one of Indexed
+or Instanced but not Indirect.
+
Finally you can use filter functions for more advanced matching than just strings. These are documented on the left here, but for example +
- $draw(numIndices > 1000) Indexed +$draw(numIndices > 1000) Indexed+
will include any drawcall that matches "Indexed" as a plain string match, OR renders more than 1000 indices. +
)EOD").trimmed()); } else if(f == lit("Literal String")) { - m_FilterSettings.FuncDocs->setText(tr(R"EOD( -"Literal string" -literal_string - passes if the event's name contains a literal string + m_FilterSettings.FuncDocs->setHtml(tr(R"EOD( +| "Literal string" +literal_string |
+- passes if the event's name contains a literal substring anywhere in its name |
Any literal string, optionally included in quotes to include special characters
or whitespace, will be case-insensitively matched against the event name. Note that
this doesn't include all parameters, only those that appear in the name summary.
-For searching arbitrary parameters consider using the $param() function.
+For searching arbitrary parameters consider using the $param() function.
+