org.lwjgl.vulkan.EXTValidationCache Maven / Gradle / Ivy
Show all versions of lwjgl-vulkan Show documentation
/*
* Copyright LWJGL. All rights reserved.
* License terms: https://www.lwjgl.org/license
* MACHINE GENERATED FILE, DO NOT EDIT
*/
package org.lwjgl.vulkan;
import javax.annotation.*;
import java.nio.*;
import org.lwjgl.*;
import org.lwjgl.system.*;
import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;
import static org.lwjgl.system.MemoryUtil.*;
/**
* 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 {@code VkValidationCacheEXT} object type, which is managed similarly to the existing {@code VkPipelineCache}.
*
* The new struct {@link VkShaderModuleValidationCacheCreateInfoEXT} can be included in the {@code pNext} chain at {@link VK10#vkCreateShaderModule CreateShaderModule} time. It contains a {@code VkValidationCacheEXT} to use when validating the {@code VkShaderModule}.
*
* VK_EXT_validation_cache
*
*
* - Name String
* - {@code 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
*
*
* Other Extension Metadata
*
*
* - Last Modified Date
* - 2017-08-29
* - IP Status
* - No known IP claims.
* - Contributors
*
* - Cort Stratton, Google
* - Chris Forbes, Google
*
*/
public class EXTValidationCache {
/** The extension specification version. */
public static final int VK_EXT_VALIDATION_CACHE_SPEC_VERSION = 1;
/** The extension name. */
public static final String VK_EXT_VALIDATION_CACHE_EXTENSION_NAME = "VK_EXT_validation_cache";
/**
* Extends {@code VkStructureType}.
*
* Enum values:
*
*
* - {@link #VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT}
* - {@link #VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT}
*
*/
public static final int
VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160000,
VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160001;
/** Extends {@code VkObjectType}. */
public static final int VK_OBJECT_TYPE_VALIDATION_CACHE_EXT = 1000160000;
/**
* VkValidationCacheHeaderVersionEXT - Encode validation cache version
*
* Description
*
*
* - {@link #VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT VALIDATION_CACHE_HEADER_VERSION_ONE_EXT} specifies version one of the validation cache.
*
*
* See Also
*
* {@link #vkCreateValidationCacheEXT CreateValidationCacheEXT}, {@link #vkGetValidationCacheDataEXT GetValidationCacheDataEXT}
*/
public static final int VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT = 1;
protected EXTValidationCache() {
throw new UnsupportedOperationException();
}
// --- [ vkCreateValidationCacheEXT ] ---
/** Unsafe version of: {@link #vkCreateValidationCacheEXT CreateValidationCacheEXT} */
public static int nvkCreateValidationCacheEXT(VkDevice device, long pCreateInfo, long pAllocator, long pValidationCache) {
long __functionAddress = device.getCapabilities().vkCreateValidationCacheEXT;
if (CHECKS) {
check(__functionAddress);
VkValidationCacheCreateInfoEXT.validate(pCreateInfo);
if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
}
return callPPPPI(device.address(), pCreateInfo, pAllocator, pValidationCache, __functionAddress);
}
/**
* 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 {@code pAllocator}. Applications can limit the amount of data retrieved from a validation cache object in {@code 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 {@code vkCreateShaderModule} command by adding this object to the {@link VkShaderModuleCreateInfo} structure’s {@code pNext} chain. If a {@link VkShaderModuleValidationCacheCreateInfoEXT} object is included in the {@link VkShaderModuleCreateInfo}{@code ::pNext} chain, and its {@code validationCache} field is not {@link VK10#VK_NULL_HANDLE 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 {@code vkCreateShaderModule} command.
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code pCreateInfo} must be a valid pointer to a valid {@link VkValidationCacheCreateInfoEXT} structure
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a valid pointer to a valid {@link VkAllocationCallbacks} structure
* - {@code pValidationCache} must be a valid pointer to a {@code VkValidationCacheEXT} handle
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
*
- On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
*
*
* See Also
*
* {@link VkAllocationCallbacks}, {@link VkValidationCacheCreateInfoEXT}
*
* @param device the logical device that creates the validation cache object.
* @param pCreateInfo a pointer to a {@link VkValidationCacheCreateInfoEXT} structure containing the initial parameters for the validation cache object.
* @param pAllocator controls host memory allocation as described in the Memory Allocation chapter.
* @param pValidationCache a pointer to a {@code VkValidationCacheEXT} handle in which the resulting validation cache object is returned.
*/
@NativeType("VkResult")
public static int vkCreateValidationCacheEXT(VkDevice device, @NativeType("VkValidationCacheCreateInfoEXT const *") VkValidationCacheCreateInfoEXT pCreateInfo, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator, @NativeType("VkValidationCacheEXT *") LongBuffer pValidationCache) {
if (CHECKS) {
check(pValidationCache, 1);
}
return nvkCreateValidationCacheEXT(device, pCreateInfo.address(), memAddressSafe(pAllocator), memAddress(pValidationCache));
}
// --- [ vkDestroyValidationCacheEXT ] ---
/** Unsafe version of: {@link #vkDestroyValidationCacheEXT DestroyValidationCacheEXT} */
public static void nvkDestroyValidationCacheEXT(VkDevice device, long validationCache, long pAllocator) {
long __functionAddress = device.getCapabilities().vkDestroyValidationCacheEXT;
if (CHECKS) {
check(__functionAddress);
if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
}
callPJPV(device.address(), validationCache, pAllocator, __functionAddress);
}
/**
* 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 {@link VkAllocationCallbacks} were provided when {@code validationCache} was created, a compatible set of callbacks must be provided here
* - If no {@link VkAllocationCallbacks} were provided when {@code validationCache} was created, {@code pAllocator} must be {@code NULL}
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - If {@code validationCache} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code validationCache} must be a valid {@code VkValidationCacheEXT} handle
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a valid pointer to a valid {@link VkAllocationCallbacks} structure
* - If {@code validationCache} is a valid handle, it must have been created, allocated, or retrieved from {@code device}
*
*
* Host Synchronization
*
*
* - Host access to {@code validationCache} must be externally synchronized
*
*
* See Also
*
* {@link VkAllocationCallbacks}
*
* @param device the logical device that destroys the validation cache object.
* @param validationCache the handle of the validation cache to destroy.
* @param pAllocator controls host memory allocation as described in the Memory Allocation chapter.
*/
public static void vkDestroyValidationCacheEXT(VkDevice device, @NativeType("VkValidationCacheEXT") long validationCache, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator) {
nvkDestroyValidationCacheEXT(device, validationCache, memAddressSafe(pAllocator));
}
// --- [ vkMergeValidationCachesEXT ] ---
/**
* Unsafe version of: {@link #vkMergeValidationCachesEXT MergeValidationCachesEXT}
*
* @param srcCacheCount the length of the {@code pSrcCaches} array.
*/
public static int nvkMergeValidationCachesEXT(VkDevice device, long dstCache, int srcCacheCount, long pSrcCaches) {
long __functionAddress = device.getCapabilities().vkMergeValidationCachesEXT;
if (CHECKS) {
check(__functionAddress);
}
return callPJPI(device.address(), dstCache, srcCacheCount, pSrcCaches, __functionAddress);
}
/**
* 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
*
*
* - {@code dstCache} must not appear in the list of source caches
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code dstCache} must be a valid {@code VkValidationCacheEXT} handle
* - {@code pSrcCaches} must be a valid pointer to an array of {@code srcCacheCount} valid {@code VkValidationCacheEXT} handles
* - {@code srcCacheCount} must be greater than 0
* - {@code dstCache} must have been created, allocated, or retrieved from {@code device}
* - Each element of {@code pSrcCaches} must have been created, allocated, or retrieved from {@code device}
*
*
* Host Synchronization
*
*
* - Host access to {@code dstCache} must be externally synchronized
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
*
- On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
*
*
* @param device the logical device that owns the validation cache objects.
* @param dstCache the handle of the validation cache to merge results into.
* @param pSrcCaches a pointer to an array of validation cache handles, which will be merged into {@code dstCache}. The previous contents of {@code dstCache} are included after the merge.
*/
@NativeType("VkResult")
public static int vkMergeValidationCachesEXT(VkDevice device, @NativeType("VkValidationCacheEXT") long dstCache, @NativeType("VkValidationCacheEXT const *") LongBuffer pSrcCaches) {
return nvkMergeValidationCachesEXT(device, dstCache, pSrcCaches.remaining(), memAddress(pSrcCaches));
}
// --- [ vkGetValidationCacheDataEXT ] ---
/**
* Unsafe version of: {@link #vkGetValidationCacheDataEXT GetValidationCacheDataEXT}
*
* @param pDataSize a pointer to a value related to the amount of data in the validation cache, as described below.
*/
public static int nvkGetValidationCacheDataEXT(VkDevice device, long validationCache, long pDataSize, long pData) {
long __functionAddress = device.getCapabilities().vkGetValidationCacheDataEXT;
if (CHECKS) {
check(__functionAddress);
}
return callPJPPI(device.address(), validationCache, pDataSize, pData, __functionAddress);
}
/**
* 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 {@code pData} is {@code NULL}, then the maximum size of the data that can be retrieved from the validation cache, in bytes, is returned in {@code pDataSize}. Otherwise, {@code pDataSize} must point to a variable set by the user to the size of the buffer, in bytes, pointed to by {@code pData}, and on return the variable is overwritten with the amount of data actually written to {@code pData}. If {@code pDataSize} is less than the maximum size that can be retrieved by the validation cache, at most {@code pDataSize} bytes will be written to {@code pData}, and {@code vkGetValidationCacheDataEXT} will return {@link VK10#VK_INCOMPLETE INCOMPLETE} instead of {@link VK10#VK_SUCCESS SUCCESS}, to indicate that not all of the validation cache was returned.
*
* Any data written to {@code pData} is valid and can be provided as the {@code pInitialData} member of the {@link VkValidationCacheCreateInfoEXT} structure passed to {@code vkCreateValidationCacheEXT}.
*
* Two calls to {@code 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 {@code pData} must be a header consisting of the following members:
*
* Layout for validation cache header version {@link #VK_VALIDATION_CACHE_HEADER_VERSION_ONE_EXT 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 {@code VkValidationCacheHeaderVersionEXT} value written as a stream of bytes, with the least significant byte first 8 {@link VK10#VK_UUID_SIZE 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 {@code VkValidationCacheHeaderVersionEXT}. A consumer of the validation cache should use the cache version to interpret the remainder of the cache header.
*
* If {@code pDataSize} is less than what is necessary to store this header, nothing will be written to {@code pData} and zero will be written to {@code pDataSize}.
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code validationCache} must be a valid {@code VkValidationCacheEXT} handle
* - {@code pDataSize} must be a valid pointer to a {@code size_t} value
* - If the value referenced by {@code pDataSize} is not 0, and {@code pData} is not {@code NULL}, {@code pData} must be a valid pointer to an array of {@code pDataSize} bytes
* - {@code validationCache} must have been created, allocated, or retrieved from {@code device}
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
* - {@link VK10#VK_INCOMPLETE INCOMPLETE}
*
- On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
*
*
* @param device the logical device that owns the validation cache.
* @param validationCache the validation cache to retrieve data from.
* @param pDataSize a pointer to a value related to the amount of data in the validation cache, as described below.
* @param pData either {@code NULL} or a pointer to a buffer.
*/
@NativeType("VkResult")
public static int vkGetValidationCacheDataEXT(VkDevice device, @NativeType("VkValidationCacheEXT") long validationCache, @NativeType("size_t *") PointerBuffer pDataSize, @Nullable @NativeType("void *") ByteBuffer pData) {
if (CHECKS) {
check(pDataSize, 1);
checkSafe(pData, pDataSize.get(pDataSize.position()));
}
return nvkGetValidationCacheDataEXT(device, validationCache, memAddress(pDataSize), memAddressSafe(pData));
}
/** Array version of: {@link #vkCreateValidationCacheEXT CreateValidationCacheEXT} */
@NativeType("VkResult")
public static int vkCreateValidationCacheEXT(VkDevice device, @NativeType("VkValidationCacheCreateInfoEXT const *") VkValidationCacheCreateInfoEXT pCreateInfo, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator, @NativeType("VkValidationCacheEXT *") long[] pValidationCache) {
long __functionAddress = device.getCapabilities().vkCreateValidationCacheEXT;
if (CHECKS) {
check(__functionAddress);
check(pValidationCache, 1);
VkValidationCacheCreateInfoEXT.validate(pCreateInfo.address());
if (pAllocator != null) { VkAllocationCallbacks.validate(pAllocator.address()); }
}
return callPPPPI(device.address(), pCreateInfo.address(), memAddressSafe(pAllocator), pValidationCache, __functionAddress);
}
/** Array version of: {@link #vkMergeValidationCachesEXT MergeValidationCachesEXT} */
@NativeType("VkResult")
public static int vkMergeValidationCachesEXT(VkDevice device, @NativeType("VkValidationCacheEXT") long dstCache, @NativeType("VkValidationCacheEXT const *") long[] pSrcCaches) {
long __functionAddress = device.getCapabilities().vkMergeValidationCachesEXT;
if (CHECKS) {
check(__functionAddress);
}
return callPJPI(device.address(), dstCache, pSrcCaches.length, pSrcCaches, __functionAddress);
}
}