org.lwjgl.vulkan

Class EXTValidationCache

java.lang.Object

org.lwjgl.vulkan.EXTValidationCache

public class EXTValidationCache
extends java.lang.Object

This extension provides a mechanism for caching the results of potentially expensive internal validation operations across multiple runs of a Vulkan application. At the core is the VkValidationCacheEXT object type, which is managed similarly to the existing VkPipelineCache.

The new struct VkShaderModuleValidationCacheCreateInfoEXT can be included in the pNext chain at CreateShaderModule time. It contains a VkValidationCacheEXT to use when validating the VkShaderModule.

Name String

VK_EXT_validation_cache

Extension Type

Device extension

Registered Extension Number

161

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0

Contact

• Cort Stratton cdwfs

Last Modified Date

2017-08-29

IP Status

No known IP claims.

Contributors

• Cort Stratton, Google
• Chris Forbes, Google

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VK_EXT_VALIDATION_CACHE_EXTENSION_NAME The extension name.
static int	VK_EXT_VALIDATION_CACHE_SPEC_VERSION The extension specification version.
static int	VK_OBJECT_TYPE_VALIDATION_CACHE_EXT Extends VkObjectType.
static int	VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT Extends VkStructureType.
static int	VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT Extends VkStructureType.
static int	VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT VkValidationCacheHeaderVersionEXT - Encode validation cache version

Method Summary

Modifier and Type	Method and Description
static int	nvkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device, long pCreateInfo, long pAllocator, long pValidationCache) Unsafe version of: CreateValidationCacheEXT
static void	nvkDestroyValidationCacheEXT(org.lwjgl.vulkan.VkDevice device, long validationCache, long pAllocator) Unsafe version of: DestroyValidationCacheEXT
static int	nvkGetValidationCacheDataEXT(org.lwjgl.vulkan.VkDevice device, long validationCache, long pDataSize, long pData) Unsafe version of: GetValidationCacheDataEXT
static int	nvkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device, long dstCache, int srcCacheCount, long pSrcCaches) Unsafe version of: MergeValidationCachesEXT
static int	vkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device, VkValidationCacheCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, long[] pValidationCache) Array version of: CreateValidationCacheEXT
static int	vkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device, VkValidationCacheCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pValidationCache) Creates a new validation cache.
static void	vkDestroyValidationCacheEXT(org.lwjgl.vulkan.VkDevice device, long validationCache, VkAllocationCallbacks pAllocator) Destroy a validation cache object.
static int	vkGetValidationCacheDataEXT(org.lwjgl.vulkan.VkDevice device, long validationCache, org.lwjgl.PointerBuffer pDataSize, java.nio.ByteBuffer pData) Get the data store from a validation cache.
static int	vkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device, long dstCache, long[] pSrcCaches) Array version of: MergeValidationCachesEXT
static int	vkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device, long dstCache, java.nio.LongBuffer pSrcCaches) Combine the data stores of validation caches.

Methods inherited from class java.lang.Object

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

Field Detail

VK_EXT_VALIDATION_CACHE_SPEC_VERSION

public static final int VK_EXT_VALIDATION_CACHE_SPEC_VERSION

The extension specification version.

See Also:

Constant Field Values

VK_EXT_VALIDATION_CACHE_EXTENSION_NAME

public static final java.lang.String VK_EXT_VALIDATION_CACHE_EXTENSION_NAME

The extension name.

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT

public static final int VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT
• STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

public static final int VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT
• STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT

See Also:

Constant Field Values

VK_OBJECT_TYPE_VALIDATION_CACHE_EXT

public static final int VK_OBJECT_TYPE_VALIDATION_CACHE_EXT

Extends VkObjectType.

See Also:

Constant Field Values

VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT

public static final int VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT

VkValidationCacheHeaderVersionEXT - Encode validation cache version

Description

• VALIDATION_CACHE_HEADER_VERSION_ONE_EXT specifies version one of the validation cache.

See Also

CreateValidationCacheEXT, GetValidationCacheDataEXT

See Also:

Constant Field Values

Method Detail

nvkCreateValidationCacheEXT

public static int nvkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device,
                                              long pCreateInfo,
                                              long pAllocator,
                                              long pValidationCache)

Unsafe version of: CreateValidationCacheEXT

vkCreateValidationCacheEXT

public static int vkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device,
                                             VkValidationCacheCreateInfoEXT pCreateInfo,
                                             @Nullable
                                             VkAllocationCallbacks pAllocator,
                                             java.nio.LongBuffer pValidationCache)

Creates a new validation cache.

C Specification

To create validation cache objects, call:

 VkResult vkCreateValidationCacheEXT(
     VkDevice                                    device,
     const VkValidationCacheCreateInfoEXT*       pCreateInfo,
     const VkAllocationCallbacks*                pAllocator,
     VkValidationCacheEXT*                       pValidationCache);

Description

Note

Applications can track and manage the total host memory size of a validation cache object using the pAllocator. Applications can limit the amount of data retrieved from a validation cache object in vkGetValidationCacheDataEXT. Implementations should not internally limit the total number of entries added to a validation cache object or the total host memory consumed.

Once created, a validation cache can be passed to the vkCreateShaderModule command by adding this object to the VkShaderModuleCreateInfo structure's pNext chain. If a VkShaderModuleValidationCacheCreateInfoEXT object is included in the VkShaderModuleCreateInfo::pNext chain, and its validationCache field is not NULL_HANDLE, the implementation will query it for possible reuse opportunities and update it with new content. The use of the validation cache object in these commands is internally synchronized, and the same validation cache object can be used in multiple threads simultaneously.

Note

Implementations should make every effort to limit any critical sections to the actual accesses to the cache, which is expected to be significantly shorter than the duration of the vkCreateShaderModule command.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pCreateInfo must be a valid pointer to a valid VkValidationCacheCreateInfoEXT structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pValidationCache must be a valid pointer to a VkValidationCacheEXT handle

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY

See Also

VkAllocationCallbacks, VkValidationCacheCreateInfoEXT

Parameters:

device - the logical device that creates the validation cache object.

pCreateInfo - a pointer to a VkValidationCacheCreateInfoEXT structure containing the initial parameters for the validation cache object.

pAllocator - controls host memory allocation as described in the Memory Allocation chapter.

pValidationCache - a pointer to a VkValidationCacheEXT handle in which the resulting validation cache object is returned.

nvkDestroyValidationCacheEXT

public static void nvkDestroyValidationCacheEXT(org.lwjgl.vulkan.VkDevice device,
                                                long validationCache,
                                                long pAllocator)

Unsafe version of: DestroyValidationCacheEXT

vkDestroyValidationCacheEXT

public static void vkDestroyValidationCacheEXT(org.lwjgl.vulkan.VkDevice device,
                                               long validationCache,
                                               @Nullable
                                               VkAllocationCallbacks pAllocator)

Destroy a validation cache object.

C Specification

To destroy a validation cache, call:

 void vkDestroyValidationCacheEXT(
     VkDevice                                    device,
     VkValidationCacheEXT                        validationCache,
     const VkAllocationCallbacks*                pAllocator);

Valid Usage

• If VkAllocationCallbacks were provided when validationCache was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when validationCache was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• If validationCache is not NULL_HANDLE, validationCache must be a valid VkValidationCacheEXT handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• If validationCache is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to validationCache must be externally synchronized

See Also

VkAllocationCallbacks

Parameters:

device - the logical device that destroys the validation cache object.

validationCache - the handle of the validation cache to destroy.

pAllocator - controls host memory allocation as described in the Memory Allocation chapter.

nvkMergeValidationCachesEXT

public static int nvkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device,
                                              long dstCache,
                                              int srcCacheCount,
                                              long pSrcCaches)

Unsafe version of: MergeValidationCachesEXT

Parameters:

srcCacheCount - the length of the pSrcCaches array.

vkMergeValidationCachesEXT

public static int vkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device,
                                             long dstCache,
                                             java.nio.LongBuffer pSrcCaches)

Combine the data stores of validation caches.

C Specification

Validation cache objects can be merged using the command:

 VkResult vkMergeValidationCachesEXT(
     VkDevice                                    device,
     VkValidationCacheEXT                        dstCache,
     uint32_t                                    srcCacheCount,
     const VkValidationCacheEXT*                 pSrcCaches);

Description

Note

The details of the merge operation are implementation dependent, but implementations should merge the contents of the specified validation caches and prune duplicate entries.

Valid Usage

• dstCache must not appear in the list of source caches

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• dstCache must be a valid VkValidationCacheEXT handle
• pSrcCaches must be a valid pointer to an array of srcCacheCount valid VkValidationCacheEXT handles
• srcCacheCount must be greater than 0
• dstCache must have been created, allocated, or retrieved from device
• Each element of pSrcCaches must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to dstCache must be externally synchronized

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

Parameters:

device - the logical device that owns the validation cache objects.

dstCache - the handle of the validation cache to merge results into.

pSrcCaches - a pointer to an array of validation cache handles, which will be merged into dstCache. The previous contents of dstCache are included after the merge.

nvkGetValidationCacheDataEXT

public static int nvkGetValidationCacheDataEXT(org.lwjgl.vulkan.VkDevice device,
                                               long validationCache,
                                               long pDataSize,
                                               long pData)

Unsafe version of: GetValidationCacheDataEXT

Parameters:

pDataSize - a pointer to a value related to the amount of data in the validation cache, as described below.

vkGetValidationCacheDataEXT

public static int vkGetValidationCacheDataEXT(org.lwjgl.vulkan.VkDevice device,
                                              long validationCache,
                                              org.lwjgl.PointerBuffer pDataSize,
                                              @Nullable
                                              java.nio.ByteBuffer pData)

Get the data store from a validation cache.

C Specification

Data can be retrieved from a validation cache object using the command:

 VkResult vkGetValidationCacheDataEXT(
     VkDevice                                    device,
     VkValidationCacheEXT                        validationCache,
     size_t*                                     pDataSize,
     void*                                       pData);

Description

If pData is NULL, then the maximum size of the data that can be retrieved from the validation cache, in bytes, is returned in pDataSize. Otherwise, pDataSize must point to a variable set by the user to the size of the buffer, in bytes, pointed to by pData, and on return the variable is overwritten with the amount of data actually written to pData.

If pDataSize is less than the maximum size that can be retrieved by the validation cache, at most pDataSize bytes will be written to pData, and vkGetValidationCacheDataEXT will return INCOMPLETE. Any data written to pData is valid and can be provided as the pInitialData member of the VkValidationCacheCreateInfoEXT structure passed to vkCreateValidationCacheEXT.

Two calls to vkGetValidationCacheDataEXT with the same parameters must retrieve the same data unless a command that modifies the contents of the cache is called between them.

Applications can store the data retrieved from the validation cache, and use these data, possibly in a future run of the application, to populate new validation cache objects. The results of validation, however, may depend on the vendor ID, device ID, driver version, and other details of the device. To enable applications to detect when previously retrieved data is incompatible with the device, the initial bytes written to pData must be a header consisting of the following members:

Layout for validation cache header version VALIDATION_CACHE_HEADER_VERSION_ONE_EXT

Offset	Size	Meaning
0	4	length in bytes of the entire validation cache header written as a stream of bytes, with the least significant byte first
4	4	a VkValidationCacheHeaderVersionEXT value written as a stream of bytes, with the least significant byte first
8	UUID_SIZE	a layer commit ID expressed as a UUID, which uniquely identifies the version of the validation layers used to generate these validation results

The first four bytes encode the length of the entire validation cache header, in bytes. This value includes all fields in the header including the validation cache version field and the size of the length field.

The next four bytes encode the validation cache version, as described for VkValidationCacheHeaderVersionEXT. A consumer of the validation cache should use the cache version to interpret the remainder of the cache header.

If pDataSize is less than what is necessary to store this header, nothing will be written to pData and zero will be written to pDataSize.

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• validationCache must be a valid VkValidationCacheEXT handle
• pDataSize must be a valid pointer to a size_t value
• If the value referenced by pDataSize is not 0, and pData is not NULL, pData must be a valid pointer to an array of pDataSize bytes
• validationCache must have been created, allocated, or retrieved from device

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

Parameters:

device - the logical device that owns the validation cache.

validationCache - the validation cache to retrieve data from.

pDataSize - a pointer to a value related to the amount of data in the validation cache, as described below.

pData - either NULL or a pointer to a buffer.

vkCreateValidationCacheEXT

public static int vkCreateValidationCacheEXT(org.lwjgl.vulkan.VkDevice device,
                                             VkValidationCacheCreateInfoEXT pCreateInfo,
                                             @Nullable
                                             VkAllocationCallbacks pAllocator,
                                             long[] pValidationCache)

Array version of: CreateValidationCacheEXT

vkMergeValidationCachesEXT

public static int vkMergeValidationCachesEXT(org.lwjgl.vulkan.VkDevice device,
                                             long dstCache,
                                             long[] pSrcCaches)

Array version of: MergeValidationCachesEXT