org.lwjgl.vulkan.KHRDescriptorUpdateTemplate Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of lwjgl-vulkan Show documentation
Show all versions of lwjgl-vulkan Show documentation
A new generation graphics and compute API that provides high-efficiency, cross-platform access to modern GPUs used in a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.
/*
* Copyright LWJGL. All rights reserved.
* License terms: https://www.lwjgl.org/license
* MACHINE GENERATED FILE, DO NOT EDIT
*/
package org.lwjgl.vulkan;
import java.nio.*;
import org.lwjgl.system.*;
import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;
import static org.lwjgl.system.MemoryUtil.*;
/**
* Applications may wish to update a fixed set of descriptors in a large number of descriptors sets very frequently, i.e. during initializaton phase or if it's required to rebuild descriptor sets for each frame. For those cases it's also not unlikely that all information required to update a single descriptor set is stored in a single struct. This extension provides a way to update a fixed set of descriptors in a single {@code VkDescriptorSet} with a pointer to a user defined data structure which describes the new descriptors.
*
* Examples
*
*
* // TODO: Write some sample code here.
* - Name String
* - {@code VK_KHR_descriptor_update_template}
* - Extension Type
* - Device extension
* - Registered Extension Number
* - 86
* - Revision
* - 1
* - Extension and Version Dependencies
*
* - Requires Vulkan 1.0
*
- Contact
*
* - Markus Tavenrath @mtavenrath
*
- Last Modified Date
* - 2016-01-11
* - IP Status
* - No known IP claims.
* - Interactions and External Dependencies
*
* - Interacts with VK_KHR_push_descriptor
*
- Contributors
*
* - Jeff Bolz, NVIDIA
* - Michael Worcester, Imagination Technologies
*
*/
public class KHRDescriptorUpdateTemplate {
/** The extension specification version. */
public static final int VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION = 1;
/** The extension name. */
public static final String VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME = "VK_KHR_descriptor_update_template";
/** Extends {@code VkStructureType}. */
public static final int VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR = 1000085000;
/** Extends {@code VkDebugReportObjectTypeEXT}. */
public static final int VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT = 1000085000;
/** Extends {@code VkObjectType}. */
public static final int VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR = 1000085000;
/**
* VkDescriptorUpdateTemplateTypeKHR - Indicates the valid usage of the descriptor update template
*
* Description
*
*
* - {@link #VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR} specifies that the descriptor update template will be used for descriptor set updates only.
* - {@link #VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR} specifies that the descriptor update template will be used for push descriptor updates only.
*
*
* See Also
*
* {@link VkDescriptorUpdateTemplateCreateInfoKHR}
*/
public static final int
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR = 0,
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR = 1;
protected KHRDescriptorUpdateTemplate() {
throw new UnsupportedOperationException();
}
static boolean isAvailable(VKCapabilitiesDevice caps) {
return checkFunctions(
caps.vkCreateDescriptorUpdateTemplateKHR, caps.vkDestroyDescriptorUpdateTemplateKHR, caps.vkUpdateDescriptorSetWithTemplateKHR,
caps.vkCmdPushDescriptorSetWithTemplateKHR
);
}
// --- [ vkCreateDescriptorUpdateTemplateKHR ] ---
/** Unsafe version of: {@link #vkCreateDescriptorUpdateTemplateKHR CreateDescriptorUpdateTemplateKHR} */
public static int nvkCreateDescriptorUpdateTemplateKHR(VkDevice device, long pCreateInfo, long pAllocator, long pDescriptorUpdateTemplate) {
long __functionAddress = device.getCapabilities().vkCreateDescriptorUpdateTemplateKHR;
if (CHECKS) {
check(__functionAddress);
VkDescriptorUpdateTemplateCreateInfoKHR.validate(pCreateInfo);
if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
}
return callPPPPI(__functionAddress, device.address(), pCreateInfo, pAllocator, pDescriptorUpdateTemplate);
}
/**
* Create a new descriptor update template.
*
* C Specification
*
* Updating a large {@code VkDescriptorSet} array can be an expensive operation since an application must specify one {@link VkWriteDescriptorSet} structure for each descriptor or descriptor array to update, each of which re-specifies the same state when updating the same descriptor in multiple descriptor sets. For cases when an application wishes to update the same set of descriptors in multiple descriptor sets allocated using the same {@code VkDescriptorSetLayout}, {@link #vkUpdateDescriptorSetWithTemplateKHR UpdateDescriptorSetWithTemplateKHR} can be used as a replacement for {@link VK10#vkUpdateDescriptorSets UpdateDescriptorSets}.
*
* {@code VkDescriptorUpdateTemplateKHR} allows implementations to convert a set of descriptor update operations on a single descriptor set to an internal format that, in conjunction with {@link #vkUpdateDescriptorSetWithTemplateKHR UpdateDescriptorSetWithTemplateKHR} or {@link #vkCmdPushDescriptorSetWithTemplateKHR CmdPushDescriptorSetWithTemplateKHR} , can be more efficient compared to calling {@link VK10#vkUpdateDescriptorSets UpdateDescriptorSets} or {@link KHRPushDescriptor#vkCmdPushDescriptorSetKHR CmdPushDescriptorSetKHR} . The descriptors themselves are not specified in the {@code VkDescriptorUpdateTemplateKHR}, rather, offsets into an application provided pointer to host memory are specified, which are combined with a pointer passed to {@link #vkUpdateDescriptorSetWithTemplateKHR UpdateDescriptorSetWithTemplateKHR} or {@link #vkCmdPushDescriptorSetWithTemplateKHR CmdPushDescriptorSetWithTemplateKHR} . This allows large batches of updates to be executed without having to convert application data structures into a strictly-defined Vulkan data structure.
*
* To create a descriptor update template, call:
*
*
* VkResult vkCreateDescriptorUpdateTemplateKHR(
* VkDevice device,
* const VkDescriptorUpdateTemplateCreateInfoKHR* pCreateInfo,
* const VkAllocationCallbacks* pAllocator,
* VkDescriptorUpdateTemplateKHR* pDescriptorUpdateTemplate);Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code pCreateInfo} must be a pointer to a valid {@link VkDescriptorUpdateTemplateCreateInfoKHR} structure
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a pointer to a valid {@link VkAllocationCallbacks} structure
* - {@code pDescriptorUpdateTemplate} must be a pointer to a {@code VkDescriptorUpdateTemplateKHR} 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}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
*
*
* See Also
*
* {@link VkAllocationCallbacks}, {@link VkDescriptorUpdateTemplateCreateInfoKHR}
*
* @param device the logical device that creates the descriptor update template.
* @param pCreateInfo a pointer to an instance of the {@link VkDescriptorUpdateTemplateCreateInfoKHR} structure specifying the set of descriptors to update with a single call to {@link #vkCmdPushDescriptorSetWithTemplateKHR CmdPushDescriptorSetWithTemplateKHR} or {@link #vkUpdateDescriptorSetWithTemplateKHR UpdateDescriptorSetWithTemplateKHR}.
* @param pAllocator controls host memory allocation as described in the Memory Allocation chapter.
* @param pDescriptorUpdateTemplate points to a {@code VkDescriptorUpdateTemplateKHR} handle in which the resulting descriptor update template object is returned.
*/
@NativeType("VkResult")
public static int vkCreateDescriptorUpdateTemplateKHR(VkDevice device, @NativeType("const VkDescriptorUpdateTemplateCreateInfoKHR *") VkDescriptorUpdateTemplateCreateInfoKHR pCreateInfo, @NativeType("const VkAllocationCallbacks *") VkAllocationCallbacks pAllocator, @NativeType("VkDescriptorUpdateTemplateKHR *") LongBuffer pDescriptorUpdateTemplate) {
if (CHECKS) {
check(pDescriptorUpdateTemplate, 1);
}
return nvkCreateDescriptorUpdateTemplateKHR(device, pCreateInfo.address(), memAddressSafe(pAllocator), memAddress(pDescriptorUpdateTemplate));
}
// --- [ vkDestroyDescriptorUpdateTemplateKHR ] ---
/** Unsafe version of: {@link #vkDestroyDescriptorUpdateTemplateKHR DestroyDescriptorUpdateTemplateKHR} */
public static void nvkDestroyDescriptorUpdateTemplateKHR(VkDevice device, long descriptorUpdateTemplate, long pAllocator) {
long __functionAddress = device.getCapabilities().vkDestroyDescriptorUpdateTemplateKHR;
if (CHECKS) {
check(__functionAddress);
if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
}
callPJPV(__functionAddress, device.address(), descriptorUpdateTemplate, pAllocator);
}
/**
* Destroy a descriptor update template object.
*
* C Specification
*
* To destroy a descriptor update template, call:
*
*
* void vkDestroyDescriptorUpdateTemplateKHR(
* VkDevice device,
* VkDescriptorUpdateTemplateKHR descriptorUpdateTemplate,
* const VkAllocationCallbacks* pAllocator);Valid Usage
*
*
* - If {@link VkAllocationCallbacks} were provided when {@code descriptorSetLayout} was created, a compatible set of callbacks must be provided here
* - If no {@link VkAllocationCallbacks} were provided when {@code descriptorSetLayout} was created, {@code pAllocator} must be {@code NULL}
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - If {@code descriptorUpdateTemplate} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code descriptorUpdateTemplate} must be a valid {@code VkDescriptorUpdateTemplateKHR} handle
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a pointer to a valid {@link VkAllocationCallbacks} structure
* - If {@code descriptorUpdateTemplate} is a valid handle, it must have been created, allocated, or retrieved from {@code device}
*
*
* Host Synchronization
*
*
* - Host access to {@code descriptorUpdateTemplate} must be externally synchronized
*
*
* See Also
*
* {@link VkAllocationCallbacks}
*
* @param device the logical device that has been used to create the descriptor update template
* @param descriptorUpdateTemplate the descriptor update template to destroy.
* @param pAllocator controls host memory allocation as described in the Memory Allocation chapter.
*/
public static void vkDestroyDescriptorUpdateTemplateKHR(VkDevice device, @NativeType("VkDescriptorUpdateTemplateKHR") long descriptorUpdateTemplate, @NativeType("const VkAllocationCallbacks *") VkAllocationCallbacks pAllocator) {
nvkDestroyDescriptorUpdateTemplateKHR(device, descriptorUpdateTemplate, memAddressSafe(pAllocator));
}
// --- [ vkUpdateDescriptorSetWithTemplateKHR ] ---
/**
* Update the contents of a descriptor set object using an update template.
*
* C Specification
*
* Once a {@code VkDescriptorUpdateTemplateKHR} has been created, descriptor sets can be updated by calling:
*
*
* void vkUpdateDescriptorSetWithTemplateKHR(
* VkDevice device,
* VkDescriptorSet descriptorSet,
* VkDescriptorUpdateTemplateKHR descriptorUpdateTemplate,
* const void* pData);Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code descriptorSet} must be a valid {@code VkDescriptorSet} handle
* - {@code descriptorUpdateTemplate} must be a valid {@code VkDescriptorUpdateTemplateKHR} handle
* - {@code pData} must be a pointer
* - {@code descriptorUpdateTemplate} must have been created, allocated, or retrieved from {@code device}
*
*
* Host Synchronization
*
*
* - Host access to {@code descriptorSet} must be externally synchronized
*
*
*
* struct AppBufferView {
* VkBufferView bufferView;
* uint32_t applicationRelatedInformation;
* };
*
* struct AppDataStructure
* {
* VkDescriptorImageInfo imageInfo; // a single image info
* VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array
* AppBufferView bufferView[2]; // An application defined structure containing a bufferView
* // ... some more application related data
* };
*
* const VkDescriptorUpdateTemplateEntryKHR descriptorUpdateTemplateEntries[] =
* {
* // binding to a single image descriptor
* {
* 0, // binding
* 0, // dstArrayElement
* 1, // descriptorCount
* VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType
* offsetof(AppDataStructure, imageInfo), // offset
* 0 // stride is not required if descriptorCount is 1.
* },
*
* // binding to an array of buffer descriptors
* {
* 0, // binding
* 0, // dstArrayElement
* 3, // descriptorCount
* VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType
* offsetof(AppDataStructure, bufferInfoArray), // offset
* sizeof(VkDescriptorBufferInfo) // stride, descriptor buffer infos are compact
* },
*
* // binding to an array of buffer views
* {
* 0, // binding
* 3, // dstArrayElement
* 1, // descriptorCount
* VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, // descriptorType
* offsetof(AppDataStructure, bufferView), // offset
* sizeof(AppBufferView) // stride, bufferViews do not have to be compact
* },
* };
*
* // create an descriptor update template for descriptor set updates
* const VkDescriptorUpdateTemplateCreateInfoKHR createInfo =
* {
* VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR, // sType
* NULL, // pNext
* 0, // flags
* 3, // descriptorUpdateEntryCount
* descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries
* VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR, // templateType
* myLayout, // descriptorSetLayout
* 0, // pipelineBindPoint, ignored by given templateType
* 0, // pipelineLayout, ignored by given templateType
* 0, // set, ignored by given templateType
* };
*
* VkDescriptorUpdateTemplateKHR myDescriptorUpdateTemplate;
* myResult = vkCreatePipelineLayout(
* myDevice,
* &createInfo,
* NULL,
* &myDescriptorUpdateTemplate);
* }
*
*
* AppDataStructure appData;
*
* // fill appData here or cache it in your engine
* vkUpdateDescriptorSetWithTemplateKHR(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData);C Specification
*
* It is also possible to use a descriptor update template to specify the push descriptors to update. To do so, call:
*
*
* void vkCmdPushDescriptorSetWithTemplateKHR(
* VkCommandBuffer commandBuffer,
* VkDescriptorUpdateTemplateKHR descriptorUpdateTemplate,
* VkPipelineLayout layout,
* uint32_t set,
* const void* pData);Valid Usage
*
*
* - The pipelineBindPoint specified during the creation of the descriptor update template must be supported by the {@code commandBuffer}’s parent {@code VkCommandPool}’s queue family
*
*
* Valid Usage (Implicit)
*
*
* - {@code commandBuffer} must be a valid {@code VkCommandBuffer} handle
* - {@code descriptorUpdateTemplate} must be a valid {@code VkDescriptorUpdateTemplateKHR} handle
* - {@code layout} must be a valid {@code VkPipelineLayout} handle
* - {@code pData} must be a pointer
* - {@code commandBuffer} must be in the recording state
* - The {@code VkCommandPool} that {@code commandBuffer} was allocated from must support graphics, or compute operations
* - Each of {@code commandBuffer}, {@code descriptorUpdateTemplate}, and {@code layout} must have been created, allocated, or retrieved from the same {@code VkDevice}
*
*
* Host Synchronization
*
*
* - Host access to {@code commandBuffer} must be externally synchronized
* - Host access to the {@code VkCommandPool} that {@code commandBuffer} was allocated from must be externally synchronized
*
*
* Command Properties
*
*
* Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type Primary Secondary Both Graphics compute
*
*
* struct AppBufferView {
* VkBufferView bufferView;
* uint32_t applicationRelatedInformation;
* };
*
* struct AppDataStructure
* {
* VkDescriptorImageInfo imageInfo; // a single image info
* // ... some more application related data
* };
*
* const VkDescriptorUpdateTemplateEntryKHR descriptorUpdateTemplateEntries[] =
* {
* // binding to a single image descriptor
* {
* 0, // binding
* 0, // dstArrayElement
* 1, // descriptorCount
* VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType
* offsetof(AppDataStructure, imageInfo), // offset
* 0 // stride is not required if descriptorCount is 1.
* }
*
* };
*
* // create an descriptor update template for descriptor set updates
* const VkDescriptorUpdateTemplateCreateInfoKHR createInfo =
* {
* VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR, // sType
* NULL, // pNext
* 0, // flags
* 1, // descriptorUpdateEntryCount
* descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries
* VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, // templateType
* 0, // descriptorSetLayout, ignored by given templateType
* VK_PIPELINE_BIND_POINT_GRAPHICS, // pipelineBindPoint
* myPipelineLayout, // pipelineLayout
* 0, // set
* };
*
* VkDescriptorUpdateTemplateKHR myDescriptorUpdateTemplate;
* myResult = vkCreatePipelineLayout(
* myDevice,
* &createInfo,
* NULL,
* &myDescriptorUpdateTemplate);
* }
*
* AppDataStructure appData;
* // fill appData here or cache it in your engine
* vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData);