renderdoc/docs/Windows/EventBrowser.aml

<?xml version="1.0" encoding="utf-8"?>
<topic id="16D2B42E-65B0-40D1-AB91-AD2B156F5DA0" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
    <introduction>
      <para>The Event Browser is the primary method of browsing the frame and selecting
      different drawcalls. It displays the user-annotated hierarchical display of
      sections.</para>
    </introduction>
    <section address="annotation">
      <title>Annotating your frame</title>
      <content>
        <para>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.</para>
        <para>Doing this is API and platform specific. Example code for D3D11 is included
        below, using the D3DPERF library that is defined in d3d9.lib, which can still be used
        in D3D11. (The newer ID3DUserDefinedAnnotation API is also supported).</para>
        
<code language="cpp">
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();
</code>

		<para>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.</para>
      </content>
    </section>
    <section address="columns">
      <title>Selecting available columns</title>
      <content>
      	<para>By default, the columns in the event browser are EID and Name. Name cannot be removed as
      	it contains the tree, but otherwise the columns can be customised both to hide/display or
      	reorder and resize.</para>
      	<para>To select which columns should be visible, right click the header or click the
      	<mediaLinkInline><image xlink:href="timeline_marker"/></mediaLinkInline> select columns button.</para>
      	<para>To rearrange the columns simply click and drag on the header.</para>
      	
<alert class="note">
  <para>Note that when timing drawcalls the duration column will automatically be added to display the data.</para>
</alert>

      </content>
    </section>
    <section address="columns">
      <title>Timing drawcalls</title>
      <content>
      	<para>To time the GPU duration of each drawcall, click the timer button <mediaLinkInline><image xlink:href="time"/></mediaLinkInline></para>
      	<para>This will automatically run a process to get the time of each drawcall and display it in the duration column,
      	which will be added if necessary.</para>
      	<para>You can configure which time unit is used for the duration column on the fly in the
      	<link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" /></para>
      </content>
    </section>
    <section address="browsing">
      <title>Browsing the frame</title>
      <content>
        <para>The event browser is primarily intended as a tool to browse through the frame. Events
        are listed as entries in the browser and the hierarchical labels mentioned above become 
        tree nodes.</para>
        <para>The currently selected event is highlighted and indicated with a green flag
        <mediaLinkInline><image xlink:href="GreenFlag"/></mediaLinkInline>. This is the event
        that RenderDoc is inspecting and is reflected in all the other windows of the UI.</para>
        <mediaLink>
<caption placement="after" lead="Current Event">The Event browser showing several sections and the current event.</caption>
<image xlink:href="QuickStart4"/>
</mediaLink>
		<para>The EID column indicates the event ID of the drawcall listed. Event IDs are
		assigned starting from 1 and increase every time an API call is made - for this
		reason drawcall EIDs are not necessarily contiguous.</para>
        <para>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.</para>
        <para>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.</para>
        <para>The left and right arrows go into and out of hierarchy levels. When within a level
        pressing left will jump to the parent node of the current level. Pressing left again
        will collapse that node, and so on. Pressing right will (if on a node with children)
        expand that node.</para>
<alert class="note">
  <para>This window supports copy and paste, so simply select the entries and ctrl-c to
		copy to the clipboard</para>
</alert>
      </content>
    </section>
    <section address="bookmarks">
      <title>Bookmarks</title>
      <content>
        <para>The <mediaLinkInline><image xlink:href="asterisk_orange"/></mediaLinkInline> bookmark button will
        allow you to bookmark an event, the shortcut key is <command>CTRL-B</command>.</para>
<mediaLink>
<caption placement="after" lead="Bookmarks bar">The bookmarks bar with several EIDs bookmarks.</caption>
<image xlink:href="BookmarksBar"/>
</mediaLink>
        <para>A list of bookmarked events will show up on a toolbar at the top of the event browser, they and
        the shortcut keys <command>CTRL-1</command> to <command>CTRL-0</command> will jump to the
        respective bookmarked EID. These shortcuts will work anywhere in the application.</para>
      </content>
    </section>
    <section address="searching">
      <title>Searching and Jumping</title>
      <content>
        <para>There are two other controls available in the Event Browser to aid in navigating
        the frame.</para>
        <para>Pressing <command>Ctrl-F</command> will open the find-event toolbar
        <mediaLinkInline><image xlink:href="find"/></mediaLinkInline>. This toolbar
        allows you to type in a partial text filter that will be matched against both labels
        and drawcall events. The find will be executed when you press enter, although you can then
        adjust the text and re-search if you wish.</para>
        <para>If the event found lies inside an unexpanded section, the sections will be
        expanded until the matching event is visible.</para>
        <para>Matching events will be highlighted with a find icon
        <mediaLinkInline><image xlink:href="find"/></mediaLinkInline>, and pressing
        enter repeatedly will jump between matching events.</para>
        <para>The find toolbar isn't dismissed until you press escape in the text box, or click the close button
        <mediaLinkInline><image xlink:href="cross"/></mediaLinkInline>.</para>
        <para>You can also jump up and down between find results with the
        previous <mediaLinkInline><image xlink:href="stepprev"/></mediaLinkInline>
        and next <mediaLinkInline><image xlink:href="stepnext"/></mediaLinkInline>
        buttons.</para>
        <mediaLink>
<caption placement="after" lead="Highlighted Results">The results of a find are highlighted with an icon.</caption>
<image xlink:href="FindResults"/>
</mediaLink>
		<para>Pressing <command>Ctrl-G</command> 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 drawcalls, the closest matching EID will be jumped
		to.</para>
		<para>When you hit enter to jump to an EID, the toolbar closes and if you wish to jump again
		you must press <command>Ctrl-G</command> again</para>
        <mediaLink>
<caption placement="after" lead="Jumping around">The jump-to-EID toolbar prompting for an event.</caption>
<image xlink:href="JumpEID"/>
</mediaLink>
      </content>
    </section>
  </developerConceptualDocument>
</topic>