Intel® Graphics Performance Analyzers Framework (Intel® GPA Framework)

Introduction

When profiling games or other rendering applications, you will often capture streams. As a stream is a set of frames, these streams may end up being rather large files. Opening these large files and navigating to points of interest may be extremely time consuming as there is typically a significant amount of data in each frame and you may often capture streams that contain hundreds, or even thousands of frames.

Several years ago, to alleviate this issue of dealing with huge data sets, we implemented keyframing. Now we have implemented two features that take the place of keyframing and offer more refined functionality and versatility: deferred capture and sub-capture.

These Features - Defined

Keyframing

Keyframing allowed users to choose where in a stream, during capture, to insert keyframes either manually with a key press or at a regular interval. With keyframes added, users could play back a stream starting at any keyframe instead of starting from the beginning.

This feature will be removed. Starting in Intel® Graphics Performance Analyzers Framework (Intel® GPA Framework) version 2023.1, keyframing will no longer be available. Please use deferred capture and sub-capture.

Deferred Capture

Deferred capture allows you to choose when to start and end each capture. In fact, you can collect several captures in the same capture instance.

Sub-capture

Sub-capture allows you to create a capture file that is a subset of another capture file.

Use Cases

Historically, for the following use cases you would capture one or more streams while running your application. Playing through the game, when you notice something like framerate dropping you would trigger a keyframe placement. The keyframing has some drawbacks, so we have replaced keyframing with  other features which allow you to more easily capture the data that you want to analyze.

Starting Playback At A Point of Interest

With keyframing, if you want to analyze the frames immediately prior to a keyframe of your stream, you would need to open the stream from the previous keyframe (or from the beginning of the stream if you have no previous keyframes). Opening a stream at a previous keyframe can take more time to the point of interest due to having to playback previous frames.

Now, with the sub-capture feature, if you want to analyze some frames just before a particular location in the stream, you can quickly subcapture the section of interest by identifying the stream and any range of frames you are interested in.

# Capture frames from a previously captured stream, producing a new stream with the chosen frames and named with the current timestamp

# Usage: gpa-subcapture-recorder [options] <stream>

# Capture frames 10 to 100 from stream aStream
# Usage: gpa-subcapture-recorder -s [range] <path-to-stream/stream>
$ ./gpa-subcapture-recorder -s [10..100] .../aStream/

# Capture frames 10 to 100 from stream aStream
#    Create new stream without filtering -- object states are derived from the entire playback
#    Put this new stream in the Games directory
# Usage: gpa-subcapture-recorder --disable-filtering --directory <outputDirectory> -s [range] <stream>
$ ./gpa-subcapture-recorder --disable-filtering --directory .../Games/  -s [10..100]  .../Games/aStream/

# Capture frames 10 and 11 from stream aStream
#    Compress the resulting stream
#    Create the new stream without filtering
#    Enable compression -- compress the new stream
#    Put this new stream in the Games directory
# Usage: gpa-subcapture-recorder --disable-filtering --directory --enable-compression --directory .../Games/  -s [10..11] .../Games/aStream
$ ./gpa-subcapture-recorder --disable-filtering --enable-compression --directory .../Games/  -s [10..11]  .../Games/aStream

Finding The Optimal Place Of Interest For Profiling

Seeking the optimal place for analysis is prone to trial and error. For example, due to the flux in speed of hitting the keyframe trigger you may miss capturing the data of interest. Also, there is the potential hazzard of looking away from gameplay and missing the most interesting part of the stream.

The sub-capture feature, together with the gpa-stream-analyzer feature, allows you to programmatically find places of interest, like low framerates. (Then you would have the option to use the sub-capture feature, described above, to capture the exact region where, say framerate dropped below 30 FPS.)

Process

1. Capture a stream
2. Find regions of interest using gpa-stream-analyzer.exe. For example: Locate the regions of frames that fit certain criteria, such as regions that drop below a certain framerate. Refer to Profiling: Finding Regions of Interest.
3. Use gpa-subcapture-recorder.exe to extract that region of frames from the original stream capture.
4. Now you have a smaller file with precisely the frames you need to analyze

# Capture a stream
./gpa-injector -L hud-layer --layer capture .../asteroids_d3d12.exe

# Locate the ranges of frames in the stream that drop below 30fps
$ gpa-stream-analyzer  .../GPA/asteroids_d3d12-Stream/   >  .../GPA/streamData.csv
$ python moving-average.py  -i  .../GPA/streamData.csv  -p  30  cpu_frame_ms  >  .../GPA/movingAverage.csv
$ python partition.py  cpu_frame_ms_moving_average_30 30  -i  .../GPA/movingAverage.csv  >   .../GPA/partitionData.csv  
$ python summarize.py cpu_frame_ms_moving_average_30_gt_30_partition cpu_frame_ms_moving_average_30_gt_30 -i  .../GPA/partitionData.csv  > .../GPA/summarizeData.csv

# Via the above method, one of the ranges in the stream that dropped below 30fps was the set of frames from 536 to 542, so extract that portion of the stream into a separate stream so that you can analyze this smaller stream
$ subcapture-recorder.exe .../GPA/asteroids_d3d12-Stream  -s  [536..542]  --post-layer  hud-layer
 

Using the sub-capture method gives you the freedom to look away, even walk away, from your monitor while capturing a stream, and yet still extract the most useful section of your stream.

Saving Time and Reducing Memory Requirements

Maybe your profiling process incorporates storage of streams so that you can test them on various platforms. Or maybe you store them so that you can do regression testing. Whatever the reason, you rarely need to store entire streams. You need only store the parts that demonstrate particular features or particular issues.

Now, perhaps, from the use cases above, you might realize that most of the time you need not store huge streams. If your profiling process incorporates storing streams regularly - once/day or once/week, for example, you may now see that with deferred capture and sub-capture you can minimize your storage requirements.

Using deferred capture can save you time because you can advance to the part in your application where you want to start analysis before even beginning to capture, thereby creating smaller streams.

Then, with sub-capture, you can extract just the portion of streams with interesting results. Again, minimizing stream size.

And finally, the compression feature of sub-capture allows you to further shrink your stream sizes.