Graphics Event List

The Graphics Event List, which is one of the Graphics Diagnostics tools in Visual Studio, can help you explore the Direct3D events that occurred during a particular frame of your game or app and analyze their effects. This includes supporting events like device or object creation.

This is the Graphics Event List:

Navigating the Graphics Event List

Because so many Direct3D events can be generated by just one frame in a typical game or app, the Graphics Event List has features that can help you find important events and related information quickly.

To reduce the number of uninteresting events in the Graphic Event List, AddRef and Release events are omitted, and you can filter events by name, either one at a time—as shown in the previous illustration, which is filtered to display events that have Vertex in their names—or by using a semicolon-delimited list of keywords—for example, "Draw;Primitive" to display events that have either Draw or Primitive in their names.

Note

The filter list is sensitive to spaces—for example, "Draw;Primitive" and "Draw; Primitive" are different.

Because Draw calls are especially important events, the Graphics Event List provides the Go to the next draw call and Go to the previous draw call buttons, which are located in the upper-left corner of the window, so that you can find and move between them quickly.

Event categories

The events that are displayed in the Graphics Event List are organized in four categories; three that represent individual events, and a fourth that's used to group related events. Each event is displayed together with an icon that indicates the category that it belongs to.

Category	Description
Draw event	Marks a draw event that occurred during the captured frame.
Pre-frame event	Marks an event that occurred before the captured frame—for example, device or object creation.
User-defined event marker or group	Marks a single event, or a group of related events, as defined by the app. Groups can be expanded to show the events that they include.

The in-frame and pre-frame events are built into the Direct3D runtime, and correspond to Direct3D API calls. You don't have to do anything to enable these events.

User-defined events and groups are specific to a particular app. You can use user-defined events to mark significant events that occur in your app so that you can correlate them to the graphics events in the Graphics Event List. For example, you could use a marker when a certain kind of object is drawn so that you can easily find its draw call in the Graphics Event List. You can use user-defined event groups to organize related events into groups or hierarchies so that you can browse the Graphics Event List more easily. For example, you could group events that are related to interface rendering.

To create user-defined event markers and user-defined event groups in your app, use the same APIs that Direct3D uses to mark events and groups for use in other Direct3D tools. In Direct3D 11.1, the APIs belong to the ID3DUserDefinedAnnotation interface; for earlier versions of Direct3D, use the D3DPERF_ family of APIs.

API Description	API (Direct3D 11.1)	API (Direct3D 11.0 and earlier)
Begin a user-defined event group	ID3DUserDefinedAnnotation::BeginEvent	D3DPerf_BeginEvent
End a user-defined event group	ID3DUserDefinedAnnotation::EndEvent	D3DPerf_EndEvent
Create a user-defined event marker	ID3DUserDefinedAnnotation::SetMarker	D3DPerf_SetMarker

Links to graphics objects

To understand graphics events, you might need additional information about the current device state or Direct3D objects that are referenced by the event. The Graphics Event List provides links to this information for each event.

Using the Graphics Event List to find rendering problems

By using the Graphics Event List together with other Graphics Diagnostics tools, you can pinpoint rendering problems to a specific Direct3D event. When you have identified the event in which the problem first appears, you can use other Graphics Diagnostics tools to determine the cause of the problem.

For rendering problems in which an object is missing—that is, the object doesn't appear where you expect it to—you can use the Graphics Event List together with the Graphics Pipeline Stages window. When you select a Draw or Dispatch event in the event list, the Graphics Pipeline Stages window displays the effect of the event on each stage of the pipeline. By stepping through these events and watching the pipeline stages, you can detect when the object was rendered, even if it isn't displayed on the render target.

To better understand rendering problems in which an object is rendered incorrectly—that is, the object is present, but has an incorrect appearance—you can use the Graphics Event List to examine the events that are captured in the graphics log document. When you select a Draw or Dispatch event in the event list, Visual Studio displays the render target as it existed when the event occurred. By stepping through these events and watching how the render target changes in the graphics log document window, you can observe the effect of specific events and thereby understand how the final render target was built up by many events—sometimes a rendering error is caused by how different events interact in the render target.

See Also

Tasks

Walkthrough: Missing Objects Due to Device State