VkGpaSampleBeginInfoAMD(3)

# VkGpaSampleBeginInfoAMD(3) Manual Page

## Name

VkGpaSampleBeginInfoAMD - Structure specifying parameters of a GPA sample

## C Specification

The `VkGpaSampleBeginInfoAMD` structure is defined as:

    // Provided by VK_AMD_gpa_interface
    typedef struct VkGpaSampleBeginInfoAMD {
        VkStructureType               sType;
        const void*                   pNext;
        VkGpaSampleTypeAMD            sampleType;
        VkBool32                      sampleInternalOperations;
        VkBool32                      cacheFlushOnCounterCollection;
        VkBool32                      sqShaderMaskEnable;
        VkGpaSqShaderStageFlagsAMD    sqShaderMask;
        uint32_t                      perfCounterCount;
        const VkGpaPerfCounterAMD*    pPerfCounters;
        uint32_t                      streamingPerfTraceSampleInterval;
        VkDeviceSize                  perfCounterDeviceMemoryLimit;
        VkBool32                      sqThreadTraceEnable;
        VkBool32                      sqThreadTraceSuppressInstructionTokens;
        VkDeviceSize                  sqThreadTraceDeviceMemoryLimit;
        VkPipelineStageFlags          timingPreSample;
        VkPipelineStageFlags          timingPostSample;
    } VkGpaSampleBeginInfoAMD;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `sampleType` is a VkGpaSampleTypeAMD value specifying the type of sample.

- `sampleInternalOperations` is a boolean indicating whether internal driver operations are included in the results.

- `cacheFlushOnCounterCollection` is a boolean indicating whether the driver should insert cache flush and invalidate events before and after every sample.

- `sqShaderMaskEnable` is a boolean indicating whether `sqShaderMask` specifies the shader stages to sample. If VK_FALSE, all shader stages are sampled.

- `sqShaderMask` is a bitmask of VkGpaSqShaderStageFlagBitsAMD values specifying which shader stages to sample. Shader stage bits that are not relevant to the specific device are ignored.

- `perfCounterCount` is the number of counters in the `pPerfCounters` array

- `pPerfCounters` is a pointer to an array of VkGpaPerfCounterAMD structures specifying the counters to be sampled. If `sampleType` is VK_GPA_SAMPLE_TYPE_CUMULATIVE_AMD `pPerfCounters` specifies the counters that are sampled at the beginning and at end of the sample period. If `sampleType` is VK_GPA_SAMPLE_TYPE_TRACE_AMD then the SPM data will be added to the samples RGP data blob.

- `streamingPerfTraceSampleInterval` is a value specifying the period for SPM samples in cycles, and is ignored if `sampleType` is not VK_GPA_SAMPLE_TYPE_TRACE_AMD.

- `perfCounterDeviceMemoryLimit` is a value specifying the maximum amount of GPU memory that this sample can allocate for SPM data. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TRACE_AMD this value is ignored.

- `sqThreadTraceEnable` is a boolean specifying whether SQTT data should be included. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TRACE_AMD this value is ignored.

- `sqThreadTraceSuppressInstructionTokens` is a boolean specifying whether instruction-level SQTT tokens should be captured. If VK_FALSE, the amount of sample data is significantly reduced. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TRACE_AMD this value is ignored.

- `sqThreadTraceDeviceMemoryLimit` is a value specifying the maximum amount of GPU memory in bytes that this sample can allocate for the SQTT buffer. If `0`, the maximum size to prevent dropping tokens towards the end of the sample is allocated. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TRACE_AMD this value is ignored.

- `timingPreSample` is a VkPipelineStageFlags2 mask of pipeline stages specifying where the begin timestamp should take place. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TIMING_AMD this value is ignored.

- `timingPostSample` is a VkPipelineStageFlags2 mask of pipeline stages specifying where the end timestamp should take place. If `sampleType` is not VK_GPA_SAMPLE_TYPE_TIMING_AMD this value is ignored.

## Description

Valid Usage

- VUID-VkGpaSampleBeginInfoAMD-sampleType-12412
  If `sampleType` is VK_GPA_SAMPLE_TYPE_CUMULATIVE_AMD, the `VkPhysicalDeviceGpaFeaturesAMD`::`perfCounters` feature must be enabled

- VUID-VkGpaSampleBeginInfoAMD-sampleType-12413
  If `sampleType` is VK_GPA_SAMPLE_TYPE_TRACE_AMD, at least one of the `VkPhysicalDeviceGpaFeaturesAMD`::`streamingPerfCounters` or `VkPhysicalDeviceGpaFeaturesAMD`::`sqThreadTracing` features must be enabled

- VUID-VkGpaSampleBeginInfoAMD-sqThreadTraceEnable-12414
  If `sqThreadTraceEnable` is VK_TRUE, the `VkPhysicalDeviceGpaFeaturesAMD`::`sqThreadTracing` feature must be enabled

Valid Usage (Implicit)

- VUID-VkGpaSampleBeginInfoAMD-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_GPA_SAMPLE_BEGIN_INFO_AMD

- VUID-VkGpaSampleBeginInfoAMD-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkGpaSampleBeginInfoAMD-sampleType-parameter
  `sampleType` must be a valid VkGpaSampleTypeAMD value

- VUID-VkGpaSampleBeginInfoAMD-sqShaderMask-parameter
  `sqShaderMask` must be a valid combination of VkGpaSqShaderStageFlagBitsAMD values

- VUID-VkGpaSampleBeginInfoAMD-pPerfCounters-parameter
  `pPerfCounters` must be a valid pointer to an array of `perfCounterCount` valid VkGpaPerfCounterAMD structures

- VUID-VkGpaSampleBeginInfoAMD-timingPreSample-parameter
  `timingPreSample` must be a valid combination of VkPipelineStageFlagBits values

- VUID-VkGpaSampleBeginInfoAMD-timingPostSample-parameter
  `timingPostSample` must be a valid combination of VkPipelineStageFlagBits values

- VUID-VkGpaSampleBeginInfoAMD-perfCounterCount-arraylength
  `perfCounterCount` must be greater than `0`

## See Also

VK_AMD_gpa_interface, VkBool32, VkDeviceSize, VkGpaPerfCounterAMD, VkGpaSampleTypeAMD, VkGpaSqShaderStageFlagsAMD, VkPipelineStageFlags, VkStructureType, vkCmdBeginGpaSampleAMD

## Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0