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 theVkValidationCacheEXT
object type, which is managed similarly to the existingVkPipelineCache
.The new struct
VkShaderModuleValidationCacheCreateInfoEXT
can be included in thepNext
chain atCreateShaderModule
time. It contains aVkValidationCacheEXT
to use when validating theVkShaderModule
.- 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 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
ExtendsVkObjectType
.static int
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXTExtendsVkStructureType
.static int
VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT
VkValidationCacheHeaderVersionEXT - Encode validation cache version
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static int
nvkCreateValidationCacheEXT(VkDevice device, long pCreateInfo, long pAllocator, long pValidationCache)
Unsafe version of:CreateValidationCacheEXT
static void
nvkDestroyValidationCacheEXT(VkDevice device, long validationCache, long pAllocator)
Unsafe version of:DestroyValidationCacheEXT
static int
nvkGetValidationCacheDataEXT(VkDevice device, long validationCache, long pDataSize, long pData)
Unsafe version of:GetValidationCacheDataEXT
static int
nvkMergeValidationCachesEXT(VkDevice device, long dstCache, int srcCacheCount, long pSrcCaches)
Unsafe version of:MergeValidationCachesEXT
static int
vkCreateValidationCacheEXT(VkDevice device, VkValidationCacheCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, long[] pValidationCache)
Array version of:CreateValidationCacheEXT
static int
vkCreateValidationCacheEXT(VkDevice device, VkValidationCacheCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pValidationCache)
Creates a new validation cache.static void
vkDestroyValidationCacheEXT(VkDevice device, long validationCache, VkAllocationCallbacks pAllocator)
Destroy a validation cache object.static int
vkGetValidationCacheDataEXT(VkDevice device, long validationCache, org.lwjgl.PointerBuffer pDataSize, java.nio.ByteBuffer pData)
Get the data store from a validation cache.static int
vkMergeValidationCachesEXT(VkDevice device, long dstCache, long[] pSrcCaches)
Array version of:MergeValidationCachesEXT
static int
vkMergeValidationCachesEXT(VkDevice device, long dstCache, java.nio.LongBuffer pSrcCaches)
Combine the data stores of validation caches.
-
-
-
Field Detail
-
VK_EXT_VALIDATION_CACHE_SPEC_VERSION
The extension specification version.
-
VK_EXT_VALIDATION_CACHE_EXTENSION_NAME
The extension name.
-
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT, VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT
ExtendsVkStructureType
.Enum values:
-
VK_OBJECT_TYPE_VALIDATION_CACHE_EXT
ExtendsVkObjectType
.
-
VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT
VkValidationCacheHeaderVersionEXT - Encode validation cache versionDescription
VALIDATION_CACHE_HEADER_VERSION_ONE_EXT
specifies version one of the validation cache.
See Also
-
-
Method Detail
-
nvkCreateValidationCacheEXT
public static int nvkCreateValidationCacheEXT(VkDevice device, long pCreateInfo, long pAllocator, long pValidationCache)
Unsafe version of:CreateValidationCacheEXT
-
vkCreateValidationCacheEXT
public static int vkCreateValidationCacheEXT(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 invkGetValidationCacheDataEXT
. 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 as part of theVkShaderModuleCreateInfo
pNext
chain. If aVkShaderModuleValidationCacheCreateInfoEXT
object is part of theVkShaderModuleCreateInfo
::pNext
chain, and itsvalidationCache
field is notNULL_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 validVkDevice
handlepCreateInfo
must be a valid pointer to a validVkValidationCacheCreateInfoEXT
structure- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure pValidationCache
must be a valid pointer to aVkValidationCacheEXT
handle
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
device
- the logical device that creates the validation cache object.pCreateInfo
- a pointer to aVkValidationCacheCreateInfoEXT
structure that contains the initial parameters for the validation cache object.pAllocator
- controls host memory allocation as described in the Memory Allocation chapter.pValidationCache
- a pointer to aVkValidationCacheEXT
handle in which the resulting validation cache object is returned.
-
nvkDestroyValidationCacheEXT
public static void nvkDestroyValidationCacheEXT(VkDevice device, long validationCache, long pAllocator)
Unsafe version of:DestroyValidationCacheEXT
-
vkDestroyValidationCacheEXT
public static void vkDestroyValidationCacheEXT(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 whenvalidationCache
was created, a compatible set of callbacks must be provided here - If no
VkAllocationCallbacks
were provided whenvalidationCache
was created,pAllocator
must beNULL
Valid Usage (Implicit)
device
must be a validVkDevice
handle- If
validationCache
is notNULL_HANDLE
,validationCache
must be a validVkValidationCacheEXT
handle - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure - If
validationCache
is a valid handle, it must have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
validationCache
must be externally synchronized
See Also
- 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.
- If
-
nvkMergeValidationCachesEXT
public static int nvkMergeValidationCachesEXT(VkDevice device, long dstCache, int srcCacheCount, long pSrcCaches)
Unsafe version of:MergeValidationCachesEXT
- Parameters:
srcCacheCount
- the length of thepSrcCaches
array.
-
vkMergeValidationCachesEXT
public static int vkMergeValidationCachesEXT(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 validVkDevice
handledstCache
must be a validVkValidationCacheEXT
handlepSrcCaches
must be a valid pointer to an array ofsrcCacheCount
validVkValidationCacheEXT
handlessrcCacheCount
must be greater than 0dstCache
must have been created, allocated, or retrieved fromdevice
- Each element of
pSrcCaches
must have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
dstCache
must be externally synchronized
Return Codes
- On success, this command returns
- On failure, this command returns
- Parameters:
device
- the logical device that owns the validation cache objects.dstCache
- the handle of the validation cache to merge results into.pSrcCaches
- an array of validation cache handles, which will be merged intodstCache
. The previous contents ofdstCache
are included after the merge.
-
nvkGetValidationCacheDataEXT
public static int nvkGetValidationCacheDataEXT(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(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
isNULL
, then the maximum size of the data that can be retrieved from the validation cache, in bytes, is returned inpDataSize
. Otherwise,pDataSize
must point to a variable set by the user to the size of the buffer, in bytes, pointed to bypData
, and on return the variable is overwritten with the amount of data actually written topData
.If
pDataSize
is less than the maximum size that can be retrieved by the validation cache, at mostpDataSize
bytes will be written topData
, andvkGetValidationCacheDataEXT
will returnINCOMPLETE
. Any data written topData
is valid and can be provided as thepInitialData
member of theVkValidationCacheCreateInfoEXT
structure passed tovkCreateValidationCacheEXT
.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 first8 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 topData
and zero will be written topDataSize
.Valid Usage (Implicit)
device
must be a validVkDevice
handlevalidationCache
must be a validVkValidationCacheEXT
handlepDataSize
must be a valid pointer to asize_t
value- If the value referenced by
pDataSize
is not 0, andpData
is notNULL
,pData
must be a valid pointer to an array ofpDataSize
bytes validationCache
must have been created, allocated, or retrieved fromdevice
Return Codes
- On success, this command returns
- On failure, this command returns
- 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
- eitherNULL
or a pointer to a buffer.
-
vkCreateValidationCacheEXT
public static int vkCreateValidationCacheEXT(VkDevice device, VkValidationCacheCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, long[] pValidationCache)
Array version of:CreateValidationCacheEXT
-
vkMergeValidationCachesEXT
public static int vkMergeValidationCachesEXT(VkDevice device, long dstCache, long[] pSrcCaches)
Array version of:MergeValidationCachesEXT
-
-