Circular Timing Captures

Steven Pratschner

Starting with the 2402.07 version of PIX on Windows and version 1.0.231030001 of the WinPIXEventRuntime, Timing Captures can now be run in a new “Circular”, or “ring-buffer” mode, in addition to the previously available “Sequential” mode.  The new Circular mode is available both through the PIX UI and programmatically using the PIXBeginCapture API. 

When capturing in Circular mode, PIX stores the capture data in a fixed sized buffer on disk. When the buffer is full, the oldest capture data is aged out to make room for newer data. Because the amount of space needed to store capture data is fixed, Circular captures can be run continuously.  The on-disk buffer is stored in the user’s %TEMP% directory and is deleted when the capturing process is complete.

The new Capture Mode setting in the PIX UI is used to choose between Circular and Sequential mode.

When Capture Mode is set to Circular, use the edit field or the slider to specify the size of the on-disk buffer.

Note that capturing GPU timings and GPU resources are not currently supported in Circular mode.

Both Circular and Sequential capture are stopped from the PIX UI using the Stop Timing Capture button.

Circular Timing Captures are particularly useful when taken programmatically using PIXBeginCapture.  In this scenario, a capture can be started and left running until a spike in frame time, or any other event that’s significant from a performance perspective, is detected.  The capture can then be stopped using PIXEndCapture.  The resulting capture will contain the last N seconds of data, depending on the size of the on-disk buffer and the amount of capture data generated.

Two values must be set in the PIXCaptureParameters structure to enable Circular captures.  First, specify the value PIXCaptureParameters::FileCircular for the CaptureStorage field. Next, set the MaximumToolingMemorySizeMb field to specify the size of the on-disk buffer.  Remember that your game must be running with administrator permissions to take a capture Timing Capture programmatically.

Circular timing capture code sample:

        #include pix3.h        
         
        g_hTimingCapturer = PIXLoadLatestWinPixTimingCapturerLibrary();
        if (g_hTimingCapturer == NULL)
        {
            // process error
        }

        PIXCaptureParameters captureParams = {};

        captureParams.TimingCaptureParameters.FileName = L"c:\\captures\\hitch_detected.wpix";
        captureParams.TimingCaptureParameters.CaptureCpuSamples = true;
        captureParams.TimingCaptureParameters.CaptureCallstacks = true;
        captureParams.TimingCaptureParameters.CpuSamplesPerSecond = 4000;
        captureParams.TimingCaptureParameters.MaximumToolingMemorySizeMb = 256;
        captureParams.TimingCaptureParameters.CaptureStorage = PIXCaptureParameters::FileCircular;

        HRESULT hrProgCapture = PIXBeginCapture(PIX_CAPTURE_TIMING, &captureParams);

        if (!SUCCEEDED(hrProgCapture))
        {
            // process error
        }
        
        // title code runs - stop the capture when an interesting performance event is detected
        HRESULT hrEndCapture = PIXEndCapture(false);

        if (!SUCCEEDED(hrEndCapture))
        {
            // process error
        }

As always, keep sending us bug reports and feature requests using the PIX Feedback button in the upper right corner of the PIX UI.

Steven.

Steven Pratschner Program Manager, PIX on Windows

Follow