Samples

Intel(R) GPA Framework provides a number of samples to demonstrate usage of specific features.

Build Samples

Samples can be built in any user writable folder.

Windows*

Requirements:

Visual Studio* 2019 or 2022 (64-bit)
CMake* (3.16+)
Python* 3.9+
Windows 11 SDK (10.0.22000.0) for Desktop C++
Vulkan* SDK (1.3.275.0)

To set up your build environment, use the following command (for Visual Studio 2019):

cmake -Ax64 -G "Visual Studio 16 2019" "%INTEL_GPA_FRAMEWORK%\samples"

To set up a Visual Studio 2022 build environment, use the following command:

cmake -Ax64 -G "Visual Studio 17 2022" "%INTEL_GPA_FRAMEWORK%\samples"

As GPA Framework installs by default to a location with elevated privileges (for example, C:\Program Files on Windows), you may wish to build the samples "out of tree". To do this, create a directory in a location of your choice, change to that directory, and run one of the commands above.

To build samples, execute the following command:

cmake --build . --config Release

The Release configuration is required to be specified because at this time, we do not distribute Debug binaries for any platform, and links will fail if you try to link a Debug build to the GPA Framework release-mode libraries.

You may also wish to "install" the samples to a directory tree, rather than run them from the build tree. For this, you can add the CMake CMAKE_INSTALL_PREFIX define to one of the commands above. For example, for Visual Studio 2019,

cmake -Ax64 -DCMAKE_INSTALL_PREFIX="%cd%\install" "%INTEL_GPA_FRAMEWORK%\samples"

which will install all samples to an install directory in the build root, when you specify the "install" target to the build command:

cmake --build . --config Release --target install

Please run gpa-env-vars.bat before launching the samples to set up the appropriate environment:

"%INTEL_GPA_FRAMEWORK%\bin\gpa-env-vars.bat"

Available Samples

Print API Log

To use the ApiLog class to extract API log information from previously captured stream data, do the following:

Create a Stream object and use it to open a data source (captured data directory).
Create an ApiLog object using the Stream instance.
Scan the ApiLog object for "ranges". The time required for the operation depends on the number of calls captured in total across all captured threads.

..note:

For Vulkan*, frame boundaries are typical, such as `vkQueuePresentKHR <https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkQueuePresentKHR.html>`.
various Present methods in D3D and presentDrawable are used.

Access one of the ranges (frames) by zero-based index within the range count returned from ApiLog::ScanForRanges().
(Optional) Sort the range by timestamp. This step is not usually required, because the range is already returned in timestamp order. But this part of the sample shows how to rearrange the returned CallableCache according to user preferencies.
Enumerate the callables in the CallableCache and perform the required work for each callable.

For more details, see the sample.

'Helloworld' Simple Layer

The sample shows the basic requirements for a Intel(R) GPA Framework compatible layer. This layer emits a message at GPA_TRACE when any present API call is made in Vulkan*, or DirectX*.

'Helloworld' Generated Layer

The sample functionally replicates the default logging layer. The sample demonstrates the jinja based code generation system built into the Intel(R) GPA Framework. Output is at the GPA_TRACE level. To see the output, use the argument -v trace from the command line at run. Observe the special templates in the template folder and how they are passed into the add_layer call.

Range Player

Range playback is one of the core functionalities of the Intel(R) GPA Framework. Understanding the mechanics is a prerequisite for all extraction and experiment samples relying on it. The sample demonstrates the range playback capabilities by allowing a particular range within a capture to be played back repeatedly.

Buffer Extractor

The sample shows basic buffer extraction. This sample uses MetadataExtractor class to extract information from a given buffer. It also shows how to use RequestedResource, ResourceDataRequest, and ResourceDataResult to extract the buffer data content.

Texture Extraction

The sample shows basic texture extraction. This sample uses MetadataExtractorEx class to extract information from a given texture. It also shows how to use ResourceExtractor::Request, and ResourceExtractor::Result to extract the texture data content that can be subsequently parsed and visualized appropriately.

Sampler Extractor

The sample demonstrates the usage of MetadataExtractor to extract sampler information from resources bound to a given event. It also demonstrates the usage of MetadataExtractor.GetResourceBindingsAtIndex to extract binding information, such as input and output resources with ResourceBindings.

Shader Extractor

The sample extends Sampler Extractor with extracting shader source through a ShaderRequest.

Disable Call in Range

This sample demonstrates how to selectively disable API calls during the range playback. Use the capability to determine the impact of removing a call's execution on the frame's execution time or the final rendered result.

Metrics Collection

This sample demonstrates how to use the Intel(R) GPA Framework to collect performance metrics from graphics calls. It requires a captured stream and frame of interest to be passed in via the command line. The sample first determines a set of collection ranges that span as many graphics calls in the frame as possible, and then collects and prints out the available metrics for all of those ranges.

Highlighting Experiment

This sample demonstrates usage of the SimpleFragmentShaderExperiment interface by replicating the highlighting experiment within Intel^®GPA.

Pipeline Experiment

This sample demonstrates usage of the PipelineExperiment interface by replicating the wireframe experiment within Intel^®GPA.

Texture Replacement Experiments

The sample demonstrates usage of the TwoByTwoTextureReplacementExperiment interface by replicating the wireframe experiment within Intel^®GPA. It also demonstrates how to use the ResourceExperiment to replace a texture with an arbitrary buffer.

Advanced Stream Playback

The sample is a low-level demonstration of the Intel(R) GPA Framework playback classes.

main.cpp functionality is identical to the Print API Log sample.

main2.cpp implements low-level Range Repeat, for example, repeated frame playback for metrics collection.

Stream Filter

The sample shows how to filter a stream by different queues (execution contexts). This sample uses MultiQueueFilter class to filter the stream data. It also demonstrates how to obtain a reference to a filtered event call and play to it.