Getting Started
Use this guide to learn how to use the Intel® GPA Framework to do the following:
Capture a stream of a running application using gpa-injector
Play the stream back using gpa-player
Become familiar with the layering system
Introduction
From the root folder, where Intel® GPA Framework was unzipped, navigate to:
cd bin/Release/
The root folder contains all utilities used within the Intel® GPA Framework, including the layers.
The following utilities control capture and playback of applications, respectively:
> gpa-injector
> gpa-player
gpa-injector takes in the executable of the application to capture and controls injection of the graphics API.
gpa-player takes a stream folder as input and plays back the given stream.
To learn more about the utilities capabilities and parameters, refer to the Utilities reference page.
Layer Framework Primer
Intel® GPA Framework provides a cross-platform, cross-API layer system similar to the Vulkan* layer paradigm. The layers control what is intercepted and can inject the required code. For example, the hud-layer hooks the Present equivalent function calls across graphics APIs and injects the required code to create an overlay on the rendered surface.
gpa-injector and gpa-player take layers as input, but the capture layer is exclusive to the gpa-injector application. This layer controls graphics APIs capturing and serialization into the generated multi-frame capture stream files.
You can specify layers with the --layer [layer_name] flag. The available layers are stored in the bin/Release/layers folder.
Note
Layer usage and available parameters can be queried by supplying the desired layer to the gpa-help.exe executable.
Intel® GPA Framework is packaged with various utility layers and allows users to create custom layers. To learn more about the capture layer and other available layers, see the Layers page. The hello_simple_layer and hello_generated_layer samples are a great starting point to create custom layers.
Capture a Stream
To capture and playback an application, run the following command:
> gpa-injector --layer capture [path_to_executable]
Note
gpa-injector does not capture data from the running application. The data is captured by the capture layer.
The command starts execution of the application specified by [path_to_executable] with the capture layer instrumented. The capture layer records all graphics API commands issued by the application and saves them into a stream file in the user [user]/Documents/GPA/ folder.
Note
Intel® GPA Framework instruments and captures only the graphics APIs from the Supported Graphics APIs.
Capturing lasts while the executable is running. To stop capturing, exit, close or force close the application once the desired information is gathered in a stream. A new stream file is stored in [user]/Documents/GPA/[stream_folder]. The name of [stream_folder] consists of the workload name and the capture date in the DD/MM/YYYY format.
Play Back Stream
To play back a stream, execute the following command:
> gpa-player [path_to_stream_folder]
The command opens a window to replay the stream contents. On the playback completion, the window closes and gpa-player ends execution.
gpa-player can take several arguments that control a playback mode, a frame to start from (if the stream is captured with enabled keyframing), and optionally repeat a certain range of calls. For more information on the parameters, see the Utilities section.
Stack Multiple Layers
To add the hud-layer, supply the --layer hud-layer argument to gpa-injector.
Note
If you include the hud-layer before --layer capture, the command is also captured in a stream and played back. To avoid such behavior, include the hud-layer after the capture layer.
You can also use the hud-layer in playback by running the --post-layer hud-layer command. The command adds the HUD to the stream playback and can help identify the frame number you may be interested in.
Next Steps
To identify further possible steps, see the samples page to identify a sample that suits your use case.