PIX
Microsoft DirectX 9.0 SDK Update (October 2004)

PIX


PIX is a tool for analyzing applications that use Microsoft Direct3D. It has a wide variety of uses, both for programmers and for quality assurance engineers, depending on how it is configured. PIX can be used to perform tasks such as:

There are four main steps to using PIX:

  1. Preparing an Experiment File - Specify what application to analyze and what data to gather.
  2. Modifying the Target Program (Optional) - Modify the application to interoperate with PIX (optional).
  3. Running the Experiment - Gather the PIX data and save it to run files and image files.
  4. Analyzing PIX Data - View run files and image files generated by PIX.

Terminology Used
ItemDescription
Target ProgramThe user-specified application that is being profiled. This information is entered by the user in the experiment before data collection starts.
Experiment FileThe experiment file that contains all of the user-specified settings for collecting profiler data. Open the experiment file in PIX to set up the experiment to run. Specify per-frame data gathering options in the experiment by selecting one or more counters to collect data. (see PIX Counters)
Run FileThe output file that contains all of the profile data. Open this file from PIX to see all the data that was collected.

Preparing an Experiment File

A PIX "experiment" specifies what application to analyze, and what data to gather while analyzing it. This information can be saved to a PIX Experiment file (.PIXExp) for reuse in multiple analysis sessions. For several simple data-gathering scenarios, it is possible to use the Basic View of experiments to generate the experiment file without needing to understand the structure of PIX experiments. The Advanced View of experiments lets you control analysis behavior in greater detail. The experiment consists of two main areas, each on its own tab within Experiment Advanced View: Triggers/Actions and Target Program.

PIX Advanced View, showing Triggers and Actions

Triggers and Actions

PIX experiments specify triggers, such as a time, frame number, or event, that cause actions to be executed. Actions are behaviors that PIX can take such as gathering data or changing state. Each trigger can have multiple actions attached to it. A typical experiment will have several triggers, each of which has some actions attached to it. The triggers and actions are represented as a tree in the PIX experiment user interface.

TriggerDescription
Program StartExecute the attached actions when the target program starts.
FrameExecute the attached actions on the specified frame.
TimeExecute the attached actions at the specified time.
User MarkerExecute the attached actions when the target program calls D3DPERF_SetMarker with the specified marker name.
Begin User EventExecute the attached actions when the target program calls D3DPERF_BeginEvent with the specified event name.
End User EventExecute the attached actions when the target program calls D3DPERF_EndEvent to end the event with the specified name.

Each trigger can specify one or more of the following actions:

ActionDescription
Create Run FileOpen a new PIX run file.
Grab ScreenshotCopy the contents of the frame buffer and save it to an image file.
Modify Direct3D DeviceAt the next CreateDevice call, force the device to switch from hardware acceleration to the REF device. This trigger is often used when performing two screen captures to compare performance between the correct (but slow) rendering of a reference device and the fast rendering of a hardware accelerated device.
Modify Draw CallsEnable or disable draw calls.
Set Per-Frame CountersIdentify one or more counters. Each counter gathers some information per frame.
Set Call CaptureCapture all the calls executed. This call stream is in the order in which the API commands are executed. Use this stream to identify all the API calls between frames, time markers, or user markers, for instance.
Terminate ProgramEnd the target application. In the data-gathering mode, this terminates the collection of data and closes the PIXRun file that has been collecting per-frame counter data (see Analyzing PIX Data). In the data-analysis mode, this action terminates the PIX window.

Target Program Settings

PIX experiments also specify information about what application to launch in order to start the analysis session. In the Experiment Advanced View, click the Target Program tab to specify the path, startup folder, and command-line arguments to be used when launching the application. In some situations the application launched may be a helper program that ends up launching the application that you want to analyze. In this situation, you can set a number in Skip processes before gathering to instruct PIX which application to analyze.

Modifying the Target Program (Optional)

PIX can analyze applications without the need to modify them at all. However, more powerful analysis is possible when the target program makes certain Direct3D calls to communicate with PIX. It is also possible to modify an application so that PIX cannot analyze it.

Use the following API calls to instrument (or modify) an application for PIX analysis:

FunctionDescription
D3DPERF_SetMarkerSpecifies a user marker that PIX can use to trigger actions.
D3DPERF_BeginEvent or D3DPERF_EndEventSpecifies a user event that PIX can use to trigger actions. PIX also uses events to add structure to logged calls.
D3DPERF_SetOptionsControls how PIX behaves. Currently the only defined behavior is that calling D3DPERF_SetOptions(1) tells PIX to not analyze the application.

Running the Experiment

A PIX experiment can be started using the user interface, or from the command line. From the user interface, click the Start Experiment button or choose Start Experiment from the File menu with an experiment file open.

From the command line, you can issue a command like this, assuming that PIXWin.exe is in the path:

start /wait PIXWin.exe file.PIXExp -start 

Command-line operation may be more convenient when setting up an automated batch action such as overnight testing.

Analyzing PIX Data

During an experiment, PIX generates one of three types of data:

PIX generates a .PIXRun run file that contains per-frame counter data, depending on what you selected in the experiment. When the experiment is finished collecting data (stopping according to values you set in the experiment), the run file can be opened and displayed by PIX.

The run file data can be viewed in three separate ways:

TimeLine View

The timeline window contains two displays: the top half displays CPU and graphics processing unit (GPU) load, and the bottom half displays graphs for the values of up to four counters. In the top half, each CPU frame is shown as a gray rectangle, and each GPU frame is shown as a green rectangle. Slow frames show mostly the interior color of the rectangles, while fast frames (which are very narrow) are entirely black because each rectangle has a black outline. The magnifying glass buttons at the bottom of the timeline view can be used to zoom in on the timeline.

Display of counters in PIX TimeLine View

You can use a mouse to select the frame arrow and drag it to any frame. The lower half of this window graphically displays up to four counters using four thin, colored lines.

PIX Timeline View showing CPU and GPU processing loads

Use the drop-down list boxes to specify which counter you want to display. In this example, the black line displays the number of frames displayed per second, and the red line displays the duration of each frame.

Events View

The events window contains a list of all your specified events for which data will be collected. Each event displays some generic attributes like start time, duration, and frame number, as well as the specific attributes that you specify to collect. Click on an event, such as a particular frame, to get the timeline to display information about that event during that frame.

Summary View

The summary window contains a record of what was profiled, and where it is. A user specifies the application to profile, saves settings in the experiment file, and views results in the run file.

Related Topics



© 2004 Microsoft Corporation. All rights reserved.
Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center.