Graphics Pixel History
The Graphics Pixel History, which is one of the Graphics Diagnostics tools in Visual Studio, can help you understand how a particular pixel was affected by Direct3D events during a particular frame of your game or app.
This is the Graphics Pixel History window:
.png "A pixel with three Direct3D events in its history."){kind=tracking}
Note
Starting in Visual Studio 2013 Update 3, the Graphics Diagnostics tool windows are hosted in an independent copy of the Visual Studio shell. This customized shell, called Graphics Analysis, eliminates unnecessary menus and options, but otherwise the Pixel History and workflow are the same as before. For more information about this change, see Graphics Diagnostics Overview.
Understanding the pixel history
By using the Graphics Pixel History, you can analyze how a particular pixel of the render target is affected by Direct3D events during a particular frame. You can pinpoint a rendering problem to a specific Direct3D event, even when subsequent events—or subsequent primitives in the same event—continue to change the pixel's final color value. For example, a pixel might be rendered incorrectly and then obscured by another, semi-transparent pixel so that their colors are blended together in the framebuffer. This kind of problem would be difficult to diagnose if you only had the final contents of the render target to guide you.
The Graphics Pixel History window displays the complete history of a pixel over the course of the selected frame. The Final Frame Buffer at the top of the window displays the color that's written to the framebuffer at the end of the frame, together with additional information about the pixel such as the frame that it comes from and its screen coordinates. This area also contains the Render Alpha check box. When this check box is selected, the Final Frame Buffer color and intermediate color values are displayed with transparency over a checkerboard pattern. If the check box is cleared, the alpha channel of the color values is ignored.
The bottom part of the window displays the events that had a chance to affect the color of the pixel, together with the Initial and Final pseudo-events that represent the initial and final color values of the pixel in the framebuffer. The initial color value is determined by the first event that changed the color of the pixel (typically a Clear event). A pixel always has these two pseudo-events in its history, even when no other events affected it. When other events had a chance to affect the pixel, they are displayed between the Initial and Final events. The events can be expanded to show their details. For simple events such as those that clear a render target, the effect of the event is just a color value. More complex events such as draw calls generate one or more primitives that might contribute to the color of the pixel.
Primitives that were drawn by the event are identified by their primitive type and index, along with the total primitive count for the object. For example, an identifier such as Triangle (1456) of (6214) means that the primitive corresponds to the 1456th triangle in an object that's made up of 6214 triangles. To the left of each primitive identifier is an icon that summarizes the effect that the primitive had on the pixel. Primitives that affect the pixel color are represented by a rounded rectangle that's filled with the result color. Primitives that are excluded from having an effect on the pixel color are represented by icons that indicate the reason that the pixel was excluded. These icons are described in the section Primitive exclusion later in this article.
You can expand each primitive to examine how the pixel shader output was merged with the existing pixel color to produce the result color. From here you can also examine or debug the pixel shader code that's associated with the primitive, and you can further expand the vertex shader node to examine the vertex shader input.
Primitive exclusion
If a primitive is excluded from affecting the pixel color, the exclusion could occur for a variety of reasons. Each reason is represented by an icon that's described in this table:
Icon |
Reason for exclusion |
|---|---|
|
The pixel was excluded because it failed the depth test. |
|
The pixel was excluded because it failed the scissor test. |
|
The pixel was excluded because it failed the stencil test. |
.png "Depth test failure icon."){kind=icon}
.png "Scissor test failure icon."){kind=icon}
.png "Stencil test failure icon."){kind=icon}
Draw Call Exclusion
If all of the primitives in a draw call are excluded from affecting the render target because they fail a test, then the draw call cannot be expanded and an icon that corresponds to the reason for exclusion is displayed next to it. The reasons for draw-call exclusion resemble the reasons for primitive exclusion, and their icons are similar.
Viewing and debugging shader code
You can view the code for a Vertex Shader, Hull Shader, Domain Shader, Geometry Shader, or Pixel Shader, or debug it, by using the controls below the primitive that's associated with the shader.
To view a shader's source code
- Below the primitive that's associated with the shader that you want to view, choose the title of the shader—for example, choose Vertex Shader to view the vertex shader source code.
To debug a shader
- Below the primitive that's associated with the shader that you want to debug, to the right of the title of the shader, choose Start Debugging.
Links to graphics objects
To understand the graphics events in the pixel history, you might need information about the device state at the time of the event or about the Direct3D objects that are referenced by the event. For each event in the pixel history, the Graphics Pixel History provides links to the then-current device state and to related objects.