Package org.lwjgl.vulkan

Class KHRPipelineExecutableProperties

java.lang.Object

org.lwjgl.vulkan.KHRPipelineExecutableProperties

public class KHRPipelineExecutableProperties
extends java.lang.Object

When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. This extension adds a mechanism to query properties and statistics about the different executables produced by the pipeline compilation process. This is intended to be used by debugging and performance tools to allow them to provide more detailed information to the user. Certain compile-time shader statistics provided through this extension may be useful to developers for debugging or performance analysis.

Name String

VK_KHR_pipeline_executable_properties

Extension Type

Device extension

Registered Extension Number

270

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0

Contact

• Jason Ekstrand jekstrand

Last Modified Date

2019-05-28

IP Status

No known IP claims.

Contributors

• Jason Ekstrand, Intel
• Ian Romanick, Intel
• Kenneth Graunke, Intel
• Baldur Karlsson, Valve
• Jesse Hall, Google
• Jeff Bolz, Nvidia
• Piers Daniel, Nvidia
• Tobias Hector, AMD
• Jan-Harald Fredriksen, ARM
• Tom Olson, ARM
• Daniel Koch, Nvidia
• Spencer Fricke, Samsung

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_EXTENSION_NAME	The extension name.
static int	VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_SPEC_VERSION	The extension specification version.
static int	VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR	Extends VkPipelineCreateFlagBits.
static int	VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR	VkPipelineExecutableStatisticFormatKHR - Enum describing a pipeline executable statistic
static int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nvkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device, long pExecutableInfo, long pInternalRepresentationCount, long pInternalRepresentations)	Unsafe version of: GetPipelineExecutableInternalRepresentationsKHR
static int	nvkGetPipelineExecutablePropertiesKHR(VkDevice device, long pPipelineInfo, long pExecutableCount, long pProperties)	Unsafe version of: GetPipelineExecutablePropertiesKHR
static int	nvkGetPipelineExecutableStatisticsKHR(VkDevice device, long pExecutableInfo, long pStatisticCount, long pStatistics)	Unsafe version of: GetPipelineExecutableStatisticsKHR
static int	vkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device, VkPipelineExecutableInfoKHR pExecutableInfo, int[] pInternalRepresentationCount, VkPipelineExecutableInternalRepresentationKHR.Buffer pInternalRepresentations)	Array version of: GetPipelineExecutableInternalRepresentationsKHR
static int	vkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device, VkPipelineExecutableInfoKHR pExecutableInfo, java.nio.IntBuffer pInternalRepresentationCount, VkPipelineExecutableInternalRepresentationKHR.Buffer pInternalRepresentations)	Get internal representations of the pipeline executable.
static int	vkGetPipelineExecutablePropertiesKHR(VkDevice device, VkPipelineInfoKHR pPipelineInfo, int[] pExecutableCount, VkPipelineExecutablePropertiesKHR.Buffer pProperties)	Array version of: GetPipelineExecutablePropertiesKHR
static int	vkGetPipelineExecutablePropertiesKHR(VkDevice device, VkPipelineInfoKHR pPipelineInfo, java.nio.IntBuffer pExecutableCount, VkPipelineExecutablePropertiesKHR.Buffer pProperties)	Get the executables associated with a pipeline.
static int	vkGetPipelineExecutableStatisticsKHR(VkDevice device, VkPipelineExecutableInfoKHR pExecutableInfo, int[] pStatisticCount, VkPipelineExecutableStatisticKHR.Buffer pStatistics)	Array version of: GetPipelineExecutableStatisticsKHR
static int	vkGetPipelineExecutableStatisticsKHR(VkDevice device, VkPipelineExecutableInfoKHR pExecutableInfo, java.nio.IntBuffer pStatisticCount, VkPipelineExecutableStatisticKHR.Buffer pStatistics)	Get compile time statistics associated with a pipeline executable.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_SPEC_VERSION

The extension specification version.

VK_KHR_PIPELINE_EXECUTABLE_PROPERTIES_EXTENSION_NAME

The extension name.

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR, VK_STRUCTURE_TYPE_PIPELINE_INFO_KHR, VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR, VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR, VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR, VK_STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_EXECUTABLE_PROPERTIES_FEATURES_KHR
• STRUCTURE_TYPE_PIPELINE_INFO_KHR
• STRUCTURE_TYPE_PIPELINE_EXECUTABLE_PROPERTIES_KHR
• STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INFO_KHR
• STRUCTURE_TYPE_PIPELINE_EXECUTABLE_STATISTIC_KHR
• STRUCTURE_TYPE_PIPELINE_EXECUTABLE_INTERNAL_REPRESENTATION_KHR

VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR, VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

Extends VkPipelineCreateFlagBits.

Enum values:

• PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
• PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR

VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR, VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR, VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR, VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR

VkPipelineExecutableStatisticFormatKHR - Enum describing a pipeline executable statistic

Description

• PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR specifies that the statistic is returned as a 32-bit boolean value which must be either TRUE or FALSE and should be read from the b32 field of VkPipelineExecutableStatisticValueKHR.
• PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR specifies that the statistic is returned as a signed 64-bit integer and should be read from the i64 field of VkPipelineExecutableStatisticValueKHR.
• PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR specifies that the statistic is returned as an unsigned 64-bit integer and should be read from the u64 field of VkPipelineExecutableStatisticValueKHR.
• PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR specifies that the statistic is returned as a 64-bit floating-point value and should be read from the f64 field of VkPipelineExecutableStatisticValueKHR.

See Also

VkPipelineExecutableStatisticKHR

Method Detail

nvkGetPipelineExecutablePropertiesKHR

public static int nvkGetPipelineExecutablePropertiesKHR(VkDevice device,
                                                        long pPipelineInfo,
                                                        long pExecutableCount,
                                                        long pProperties)

Unsafe version of: GetPipelineExecutablePropertiesKHR

Parameters:

pExecutableCount - a pointer to an integer related to the number of pipeline executables available or queried, as described below.

vkGetPipelineExecutablePropertiesKHR

public static int vkGetPipelineExecutablePropertiesKHR(VkDevice device,
                                                       VkPipelineInfoKHR pPipelineInfo,
                                                       java.nio.IntBuffer pExecutableCount,
                                                       @Nullable
                                                       VkPipelineExecutablePropertiesKHR.Buffer pProperties)

Get the executables associated with a pipeline.

C Specification

When a pipeline is created, its state and shaders are compiled into zero or more device-specific executables, which are used when executing commands against that pipeline. To query the properties of these executables, call:

 VkResult vkGetPipelineExecutablePropertiesKHR(
     VkDevice                                    device,
     const VkPipelineInfoKHR*                    pPipelineInfo,
     uint32_t*                                   pExecutableCount,
     VkPipelineExecutablePropertiesKHR*          pProperties);

Description

If pProperties is NULL, then the number of executables associated with the pipeline is returned in pExecutableCount. Otherwise, pExecutableCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pExecutableCount is less than the number of executables associated with the pipeline, at most pExecutableCount structures will be written and vkGetPipelineExecutablePropertiesKHR will return INCOMPLETE.

Valid Usage

• pipelineExecutableProperties must be enabled.
• pipeline member of pPipelineInfo must have been created with device.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pPipelineInfo must be a valid pointer to a valid VkPipelineInfoKHR structure
• pExecutableCount must be a valid pointer to a uint32_t value
• If the value referenced by pExecutableCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pExecutableCount VkPipelineExecutablePropertiesKHR structures

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkPipelineExecutablePropertiesKHR, VkPipelineInfoKHR

Parameters:

device - the device that created the pipeline.

pPipelineInfo - describes the pipeline being queried.

pExecutableCount - a pointer to an integer related to the number of pipeline executables available or queried, as described below.

pProperties - either NULL or a pointer to an array of VkPipelineExecutablePropertiesKHR structures.

nvkGetPipelineExecutableStatisticsKHR

public static int nvkGetPipelineExecutableStatisticsKHR(VkDevice device,
                                                        long pExecutableInfo,
                                                        long pStatisticCount,
                                                        long pStatistics)

Unsafe version of: GetPipelineExecutableStatisticsKHR

Parameters:

pStatisticCount - a pointer to an integer related to the number of statistics available or queried, as described below.

vkGetPipelineExecutableStatisticsKHR

public static int vkGetPipelineExecutableStatisticsKHR(VkDevice device,
                                                       VkPipelineExecutableInfoKHR pExecutableInfo,
                                                       java.nio.IntBuffer pStatisticCount,
                                                       @Nullable
                                                       VkPipelineExecutableStatisticKHR.Buffer pStatistics)

Get compile time statistics associated with a pipeline executable.

C Specification

Each pipeline executable may have a set of statistics associated with it that are generated by the pipeline compilation process. These statistics may include things such as instruction counts, amount of spilling (if any), maximum number of simultaneous threads, or anything else which may aid developers in evaluating the expected performance of a shader. To query the compile-time statistics associated with a pipeline executable, call:

 VkResult vkGetPipelineExecutableStatisticsKHR(
     VkDevice                                    device,
     const VkPipelineExecutableInfoKHR*          pExecutableInfo,
     uint32_t*                                   pStatisticCount,
     VkPipelineExecutableStatisticKHR*           pStatistics);

Description

If pStatistics is NULL, then the number of statistics associated with the pipeline executable is returned in pStatisticCount. Otherwise, pStatisticCount must point to a variable set by the user to the number of elements in the pStatistics array, and on return the variable is overwritten with the number of structures actually written to pStatistics. If pStatisticCount is less than the number of statistics associated with the pipeline executable, at most pStatisticCount structures will be written and vkGetPipelineExecutableStatisticsKHR will return INCOMPLETE.

Valid Usage

• pipelineExecutableInfo must be enabled.
• pipeline member of pExecutableInfo must have been created with device.
• pipeline member of pExecutableInfo must have been created with PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR set in the flags field of VkGraphicsPipelineCreateInfo or VkComputePipelineCreateInfo.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure
• pStatisticCount must be a valid pointer to a uint32_t value
• If the value referenced by pStatisticCount is not 0, and pStatistics is not NULL, pStatistics must be a valid pointer to an array of pStatisticCount VkPipelineExecutableStatisticKHR structures

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkPipelineExecutableInfoKHR, VkPipelineExecutableStatisticKHR

Parameters:

device - the device that created the pipeline.

pExecutableInfo - describes the pipeline executable being queried.

pStatisticCount - a pointer to an integer related to the number of statistics available or queried, as described below.

pStatistics - either NULL or a pointer to an array of VkPipelineExecutableStatisticKHR structures.

nvkGetPipelineExecutableInternalRepresentationsKHR

public static int nvkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device,
                                                                     long pExecutableInfo,
                                                                     long pInternalRepresentationCount,
                                                                     long pInternalRepresentations)

Unsafe version of: GetPipelineExecutableInternalRepresentationsKHR

Parameters:

pInternalRepresentationCount - a pointer to an integer related to the number of internal representations available or queried, as described below.

vkGetPipelineExecutableInternalRepresentationsKHR

public static int vkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device,
                                                                    VkPipelineExecutableInfoKHR pExecutableInfo,
                                                                    java.nio.IntBuffer pInternalRepresentationCount,
                                                                    @Nullable
                                                                    VkPipelineExecutableInternalRepresentationKHR.Buffer pInternalRepresentations)

Get internal representations of the pipeline executable.

C Specification

Each pipeline executable may have one or more text or binary internal representations associated with it which are generated as part of the compile process. These may include the final shader assembly, a binary form of the compiled shader, or the shader compiler's internal representation at any number of intermediate compile steps. To query the internal representations associated with a pipeline executable, call:

 VkResult vkGetPipelineExecutableInternalRepresentationsKHR(
     VkDevice                                    device,
     const VkPipelineExecutableInfoKHR*          pExecutableInfo,
     uint32_t*                                   pInternalRepresentationCount,
     VkPipelineExecutableInternalRepresentationKHR* pInternalRepresentations);

Description

If pInternalRepresentations is NULL, then the number of internal representations associated with the pipeline executable is returned in pInternalRepresentationCount. Otherwise, pInternalRepresentationCount must point to a variable set by the user to the number of elements in the pInternalRepresentations array, and on return the variable is overwritten with the number of structures actually written to pInternalRepresentations. If pInternalRepresentationCount is less than the number of internal representations associated with the pipeline executable, at most pInternalRepresentationCount structures will be written and vkGetPipelineExecutableInternalRepresentationsKHR will return INCOMPLETE.

While the details of the internal representations remain implementation dependent, the implementation should order the internal representations in the order in which they occur in the compile pipeline with the final shader assembly (if any) last.

Valid Usage

• pipelineExecutableProperties must be enabled.
• pipeline member of pExecutableInfo must have been created with device.
• pipeline member of pExecutableInfo must have been created with PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR set in the flags field of VkGraphicsPipelineCreateInfo or VkComputePipelineCreateInfo.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pExecutableInfo must be a valid pointer to a valid VkPipelineExecutableInfoKHR structure
• pInternalRepresentationCount must be a valid pointer to a uint32_t value
• If the value referenced by pInternalRepresentationCount is not 0, and pInternalRepresentations is not NULL, pInternalRepresentations must be a valid pointer to an array of pInternalRepresentationCount VkPipelineExecutableInternalRepresentationKHR structures

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkPipelineExecutableInfoKHR, VkPipelineExecutableInternalRepresentationKHR

Parameters:

device - the device that created the pipeline.

pExecutableInfo - describes the pipeline executable being queried.

pInternalRepresentationCount - a pointer to an integer related to the number of internal representations available or queried, as described below.

pInternalRepresentations - either NULL or a pointer to an array of VkPipelineExecutableInternalRepresentationKHR structures.

vkGetPipelineExecutablePropertiesKHR

public static int vkGetPipelineExecutablePropertiesKHR(VkDevice device,
                                                       VkPipelineInfoKHR pPipelineInfo,
                                                       int[] pExecutableCount,
                                                       @Nullable
                                                       VkPipelineExecutablePropertiesKHR.Buffer pProperties)

Array version of: GetPipelineExecutablePropertiesKHR

vkGetPipelineExecutableStatisticsKHR

public static int vkGetPipelineExecutableStatisticsKHR(VkDevice device,
                                                       VkPipelineExecutableInfoKHR pExecutableInfo,
                                                       int[] pStatisticCount,
                                                       @Nullable
                                                       VkPipelineExecutableStatisticKHR.Buffer pStatistics)

Array version of: GetPipelineExecutableStatisticsKHR

vkGetPipelineExecutableInternalRepresentationsKHR

public static int vkGetPipelineExecutableInternalRepresentationsKHR(VkDevice device,
                                                                    VkPipelineExecutableInfoKHR pExecutableInfo,
                                                                    int[] pInternalRepresentationCount,
                                                                    @Nullable
                                                                    VkPipelineExecutableInternalRepresentationKHR.Buffer pInternalRepresentations)

Array version of: GetPipelineExecutableInternalRepresentationsKHR