Resource Creation
Vulkan supports two primary resource types: buffers and images. Resources are views of memory with associated formatting and dimensionality. Buffers provide access to raw arrays of bytes, whereas images can be multidimensional and may have associated metadata.
Other resource types, such as acceleration structures and micromaps use buffers as the backing store for opaque data structures.
Buffers
Buffers represent linear arrays of data which are used for various purposes by binding them to a graphics or compute pipeline via descriptor sets or certain commands, or by directly specifying them as parameters to certain commands.
Buffers are represented by VkBuffer handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)To create buffers, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateBuffer(
VkDevice device,
const VkBufferCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBuffer* pBuffer);-
deviceis the logical device that creates the buffer object. -
pCreateInfois a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pBufferis a pointer to a VkBuffer handle in which the resulting buffer object is returned.
The VkBufferCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferCreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferCreateFlags flags;
VkDeviceSize size;
VkBufferUsageFlags usage;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
} VkBufferCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBufferCreateFlagBits specifying additional parameters of the buffer. -
sizeis the size in bytes of the buffer to be created. -
usageis a bitmask of VkBufferUsageFlagBits specifying allowed usages of the buffer. -
sharingModeis a VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access this buffer. It is ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT.
If the pNext chain includes a VkBufferUsageFlags2CreateInfo
structure, VkBufferUsageFlags2CreateInfo::usage from that
structure is used instead of usage from this structure.
The VkBufferUsageFlags2CreateInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkBufferUsageFlags2CreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferUsageFlags2 usage;
} VkBufferUsageFlags2CreateInfo;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlags2CreateInfo VkBufferUsageFlags2CreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
usageis a bitmask of VkBufferUsageFlagBits2 specifying allowed usages of the buffer.
If this structure is included in the pNext chain of a buffer creation
structure, usage is used instead of the corresponding usage
value passed in that creation structure, allowing additional usage flags to
be specified.
If this structure is included in the pNext chain of a buffer query
structure, the usage flags of the buffer are returned in usage of this
structure, and the usage flags representable in usage of the buffer
query structure are also returned in that field.
Bits which can be set in VkBufferUsageFlags2CreateInfo::usage,
specifying usage behavior of a buffer, are:
// Provided by VK_VERSION_1_4
// Flag bits for VkBufferUsageFlagBits2
typedef VkFlags64 VkBufferUsageFlagBits2;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT = 0x00000001ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT = 0x00000002ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT = 0x00000008ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT = 0x00000010ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT = 0x00000020ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT = 0x00000040ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT = 0x00000080ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT = 0x00000100ULL;
// Provided by VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT = 0x00020000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue with VK_KHR_maintenance5 or VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000ULL;
#endif
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_conditional_rendering
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with (VK_VERSION_1_2 or VK_KHR_buffer_device_address) or VK_EXT_buffer_device_address
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_STORAGE_BIT_EXT = 0x01000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT = 0x80000000ULL;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlagBits2 VkBufferUsageFlagBits2KHR;-
VK_BUFFER_USAGE_2_TRANSFER_SRC_BITspecifies that the buffer can be used as the source of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT). -
VK_BUFFER_USAGE_2_TRANSFER_DST_BITspecifies that the buffer can be used as the destination of a transfer command. -
VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. -
VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. -
VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_2_STORAGE_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_2_INDEX_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBindIndexBuffer2 and vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_2_VERTEX_BUFFER_BITspecifies that the buffer is suitable for passing as an element of thepBuffersarray to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV,vkCmdDrawMeshTasksIndirectEXT,vkCmdDrawMeshTasksIndirectCountEXT, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffermember ofVkIndirectCommandsStreamNV, orsequencesCountBufferorsequencesIndexBufferorpreprocessedBuffermember ofVkGeneratedCommandsInfoNV. It is also suitable for passing as the underlying buffer of either thepreprocessAddressorsequenceCountAddressmembers ofVkGeneratedCommandsInfoEXT. -
VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXTspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBeginConditionalRenderingEXT. -
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXTspecifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT. -
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXTspecifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT. -
VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain sampler and combined image sampler descriptors when bound as a descriptor buffer. Buffers containing combined image sampler descriptors must also specifyVK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. -
VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer. -
VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer, when bound, can be used by the implementation to support push descriptors when using descriptor buffers. -
VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NVspecifies that the buffer is suitable for use in vkCmdTraceRaysNV. -
VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHRspecifies that the buffer is suitable for use as a Shader Binding Table. -
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHRspecifies that the buffer is suitable for use as a read-only input to an acceleration structure build. -
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHRspecifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR. -
VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BITspecifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader. -
VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHRspecifies that the buffer can be used as the source video bitstream buffer in a video decode operation. -
VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination video bitstream buffer in a video encode operation. -
VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDXspecifies that the buffer can be used for as scratch memory for execution graph dispatch. -
VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXTspecifies that the buffer can be used as a preprocess buffer for Device-Generated Commands.
// Provided by VK_VERSION_1_4
typedef VkFlags64 VkBufferUsageFlags2;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkBufferUsageFlags2 VkBufferUsageFlags2KHR;VkBufferUsageFlags2 is a bitmask type for setting a mask of zero or
more VkBufferUsageFlagBits2.
Bits which can be set in VkBufferCreateInfo::usage, specifying
usage behavior of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferUsageFlagBits {
VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
// Provided by VK_VERSION_1_2
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000,
// Provided by VK_KHR_video_decode_queue
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00004000,
// Provided by VK_EXT_transform_feedback
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800,
// Provided by VK_EXT_transform_feedback
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000,
// Provided by VK_EXT_conditional_rendering
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue
VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000,
#endif
// Provided by VK_KHR_acceleration_structure
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000,
// Provided by VK_KHR_acceleration_structure
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000,
// Provided by VK_KHR_ray_tracing_pipeline
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400,
// Provided by VK_KHR_video_encode_queue
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000,
// Provided by VK_KHR_video_encode_queue
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000,
// Provided by VK_EXT_opacity_micromap
VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000,
// Provided by VK_EXT_opacity_micromap
VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT = 0x01000000,
// Provided by VK_NV_ray_tracing
VK_BUFFER_USAGE_RAY_TRACING_BIT_NV = VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR,
// Provided by VK_EXT_buffer_device_address
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
// Provided by VK_KHR_buffer_device_address
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
} VkBufferUsageFlagBits;-
VK_BUFFER_USAGE_TRANSFER_SRC_BITspecifies that the buffer can be used as the source of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT). -
VK_BUFFER_USAGE_TRANSFER_DST_BITspecifies that the buffer can be used as the destination of a transfer command. -
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. -
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BITspecifies that the buffer can be used to create aVkBufferViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. -
VK_BUFFER_USAGE_UNIFORM_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFERorVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_STORAGE_BUFFER_BITspecifies that the buffer can be used in aVkDescriptorBufferInfosuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFERorVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. -
VK_BUFFER_USAGE_INDEX_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBindIndexBuffer2 and vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_VERTEX_BUFFER_BITspecifies that the buffer is suitable for passing as an element of thepBuffersarray to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_INDIRECT_BUFFER_BITspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV,vkCmdDrawMeshTasksIndirectEXT,vkCmdDrawMeshTasksIndirectCountEXT, vkCmdDrawClusterIndirectHUAWEI, or vkCmdDispatchIndirect. It is also suitable for passing as thebuffermember ofVkIndirectCommandsStreamNV, orsequencesCountBufferorsequencesIndexBufferorpreprocessedBuffermember ofVkGeneratedCommandsInfoNV. It is also suitable for passing as the underlying buffer of either thepreprocessAddressorsequenceCountAddressmembers ofVkGeneratedCommandsInfoEXT. -
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXTspecifies that the buffer is suitable for passing as thebufferparameter to vkCmdBeginConditionalRenderingEXT. -
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXTspecifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT. -
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXTspecifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT. -
VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain sampler and combined image sampler descriptors when bound as a descriptor buffer. Buffers containing combined image sampler descriptors must also specifyVK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. -
VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer is suitable to contain resource descriptors when bound as a descriptor buffer. -
VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXTspecifies that the buffer, when bound, can be used by the implementation to support push descriptors when using descriptor buffers. -
VK_BUFFER_USAGE_RAY_TRACING_BIT_NVspecifies that the buffer is suitable for use in vkCmdTraceRaysNV. -
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHRspecifies that the buffer is suitable for use as a Shader Binding Table. -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHRspecifies that the buffer is suitable for use as a read-only input to an acceleration structure build. -
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHRspecifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR. -
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BITspecifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader. -
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHRspecifies that the buffer can be used as the source video bitstream buffer in a video decode operation. -
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHRspecifies that the buffer can be used as the destination video bitstream buffer in a video encode operation. -
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHRis reserved for future use. -
VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDXspecifies that the buffer can be used for as scratch memory for execution graph dispatch.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferUsageFlags;VkBufferUsageFlags is a bitmask type for setting a mask of zero or
more VkBufferUsageFlagBits.
Bits which can be set in VkBufferCreateInfo::flags, specifying
additional parameters of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferCreateFlagBits {
VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
// Provided by VK_VERSION_1_1
VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
// Provided by VK_VERSION_1_2
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000010,
// Provided by VK_EXT_descriptor_buffer
VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000020,
// Provided by VK_KHR_video_maintenance1
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00000040,
// Provided by VK_EXT_buffer_device_address
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
// Provided by VK_KHR_buffer_device_address
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
} VkBufferCreateFlagBits;-
VK_BUFFER_CREATE_SPARSE_BINDING_BITspecifies that the buffer will be backed using sparse memory binding. -
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BITspecifies that the buffer can be partially backed using sparse memory binding. Buffers created with this flag must also be created with theVK_BUFFER_CREATE_SPARSE_BINDING_BITflag. -
VK_BUFFER_CREATE_SPARSE_ALIASED_BITspecifies that the buffer will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another buffer (or another portion of the same buffer). Buffers created with this flag must also be created with theVK_BUFFER_CREATE_SPARSE_BINDING_BITflag. -
VK_BUFFER_CREATE_PROTECTED_BITspecifies that the buffer is a protected buffer. -
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BITspecifies that the buffer’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferOpaqueCaptureAddressCreateInfo for more detail. -
VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the buffer can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRspecifies that the buffer can be used in video coding operations without having to specify at buffer creation time the set of video profiles the buffer will be used with.
See Sparse Resource Features and Physical Device Features for details of the sparse memory features supported on a device.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferCreateFlags;VkBufferCreateFlags is a bitmask type for setting a mask of zero or
more VkBufferCreateFlagBits.
If the pNext chain includes a
VkDedicatedAllocationBufferCreateInfoNV structure, then that structure
includes an enable controlling whether the buffer will have a dedicated
memory allocation bound to it.
The VkDedicatedAllocationBufferCreateInfoNV structure is defined as:
// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationBufferCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 dedicatedAllocation;
} VkDedicatedAllocationBufferCreateInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dedicatedAllocationspecifies whether the buffer will have a dedicated allocation bound to it.
To define a set of external memory handle types that may be used as backing
store for a buffer, add a VkExternalMemoryBufferCreateInfo structure
to the pNext chain of the VkBufferCreateInfo structure.
The VkExternalMemoryBufferCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryBufferCreateInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlags handleTypes;
} VkExternalMemoryBufferCreateInfo;or the equivalent
// Provided by VK_KHR_external_memory
typedef VkExternalMemoryBufferCreateInfo VkExternalMemoryBufferCreateInfoKHR;|
A |
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.
To request a specific device address for a buffer, add a
VkBufferOpaqueCaptureAddressCreateInfo structure to the pNext
chain of the VkBufferCreateInfo structure.
The VkBufferOpaqueCaptureAddressCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkBufferOpaqueCaptureAddressCreateInfo {
VkStructureType sType;
const void* pNext;
uint64_t opaqueCaptureAddress;
} VkBufferOpaqueCaptureAddressCreateInfo;or the equivalent
// Provided by VK_KHR_buffer_device_address
typedef VkBufferOpaqueCaptureAddressCreateInfo VkBufferOpaqueCaptureAddressCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
opaqueCaptureAddressis the opaque capture address requested for the buffer.
If opaqueCaptureAddress is zero, no specific address is requested.
If opaqueCaptureAddress is not zero, then it should be an address
retrieved from vkGetBufferOpaqueCaptureAddress for an identically
created buffer on the same implementation.
If this structure is not present, it is as if opaqueCaptureAddress is
zero.
Applications should avoid creating buffers with application-provided
addresses and implementation-provided addresses in the same process, to
reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS
errors.
|
The expected usage for this is that a trace capture/replay tool will add the
Implementations are expected to separate such buffers in the GPU address
space so normal allocations will avoid using these addresses.
Applications and tools should avoid mixing application-provided and
implementation-provided addresses for buffers created with
|
Alternatively, to
request a specific device address for a buffer, add a
VkBufferDeviceAddressCreateInfoEXT structure to the pNext chain
of the VkBufferCreateInfo structure.
The VkBufferDeviceAddressCreateInfoEXT structure is defined as:
// Provided by VK_EXT_buffer_device_address
typedef struct VkBufferDeviceAddressCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceAddress deviceAddress;
} VkBufferDeviceAddressCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis the device address requested for the buffer.
If deviceAddress is zero, no specific address is requested.
If deviceAddress is not zero, then it must be an address retrieved
from an identically created buffer on the same implementation.
The buffer must also be bound to an identically created
VkDeviceMemory object.
If this structure is not present, it is as if deviceAddress is zero.
Applications should avoid creating buffers with application-provided
addresses and implementation-provided addresses in the same process, to
reduce the likelihood of VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors.
The VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionBufferCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCollectionFUCHSIA collection;
uint32_t index;
} VkBufferCollectionBufferCreateInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexis the index of the buffer in the buffer collection from which the memory will be imported
To destroy a buffer, call:
// Provided by VK_VERSION_1_0
void vkDestroyBuffer(
VkDevice device,
VkBuffer buffer,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the buffer. -
bufferis the buffer to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Buffer Views
A buffer view represents a contiguous range of a buffer and a specific format to be used to interpret the data. Buffer views are used to enable shaders to access buffer contents using image operations. In order to create a valid buffer view, the buffer must have been created with at least one of the following usage flags:
-
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT -
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
Buffer views are represented by VkBufferView handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)To create a buffer view, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateBufferView(
VkDevice device,
const VkBufferViewCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBufferView* pView);-
deviceis the logical device that creates the buffer view. -
pCreateInfois a pointer to a VkBufferViewCreateInfo structure containing parameters to be used to create the buffer view. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pViewis a pointer to a VkBufferView handle in which the resulting buffer view object is returned.
The VkBufferViewCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferViewCreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferViewCreateFlags flags;
VkBuffer buffer;
VkFormat format;
VkDeviceSize offset;
VkDeviceSize range;
} VkBufferViewCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis reserved for future use. -
bufferis a VkBuffer on which the view will be created. -
formatis a VkFormat describing the format of the data elements in the buffer. -
offsetis an offset in bytes from the base address of the buffer. Accesses to the buffer view from shaders use addressing that is relative to this starting offset. -
rangeis a size in bytes of the buffer view. Ifrangeis equal toVK_WHOLE_SIZE, the range fromoffsetto the end of the buffer is used. IfVK_WHOLE_SIZEis used and the remaining size of the buffer is not a multiple of the texel block size offormat, the nearest smaller multiple is used.
The buffer view has a buffer view usage identifying which descriptor types
can be created from it.
This usage
can be defined by including the VkBufferUsageFlags2CreateInfo
structure in the pNext chain, and specifying the usage value
there.
If this structure is not included, it
is equal to the VkBufferCreateInfo::usage value used to create
buffer.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferViewCreateFlags;VkBufferViewCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
To destroy a buffer view, call:
// Provided by VK_VERSION_1_0
void vkDestroyBufferView(
VkDevice device,
VkBufferView bufferView,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the buffer view. -
bufferViewis the buffer view to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Buffer View Format Features
Valid uses of a VkBufferView may depend on the buffer view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is supported, then the buffer view’s set of format features is the value of VkFormatProperties3::bufferFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkBufferViewCreateInfo::format.
Images
Images represent multidimensional - up to 3 - arrays of data which can be used for various purposes (e.g. attachments, textures), by binding them to a graphics or compute pipeline via descriptor sets, or by directly specifying them as parameters to certain commands.
Images are represented by VkImage handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)To create images, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateImage(
VkDevice device,
const VkImageCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkImage* pImage);-
deviceis the logical device that creates the image. -
pCreateInfois a pointer to a VkImageCreateInfo structure containing parameters to be used to create the image. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pImageis a pointer to a VkImage handle in which the resulting image object is returned.
The VkImageCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageCreateFlags flags;
VkImageType imageType;
VkFormat format;
VkExtent3D extent;
uint32_t mipLevels;
uint32_t arrayLayers;
VkSampleCountFlagBits samples;
VkImageTiling tiling;
VkImageUsageFlags usage;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
VkImageLayout initialLayout;
} VkImageCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCreateFlagBits describing additional parameters of the image. -
imageTypeis a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type. -
formatis a VkFormat describing the format and type of the texel blocks that will be contained in the image. -
extentis a VkExtent3D describing the number of data elements in each dimension of the base level. -
mipLevelsdescribes the number of levels of detail available for minified sampling of the image. -
arrayLayersis the number of layers in the image. -
samplesis a VkSampleCountFlagBits value specifying the number of samples per texel. -
tilingis a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory. -
usageis a bitmask of VkImageUsageFlagBits describing the intended usage of the image. -
sharingModeis a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access this image. It is ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT. -
initialLayoutis a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.
Images created with tiling equal to VK_IMAGE_TILING_LINEAR have
further restrictions on their limits and capabilities compared to images
created with tiling equal to VK_IMAGE_TILING_OPTIMAL.
Creation of images with tiling VK_IMAGE_TILING_LINEAR may not be
supported unless other parameters meet all of the constraints:
-
imageTypeisVK_IMAGE_TYPE_2D -
formatis not a depth/stencil format -
mipLevelsis 1 -
arrayLayersis 1 -
samplesisVK_SAMPLE_COUNT_1_BIT -
usageonly includesVK_IMAGE_USAGE_TRANSFER_SRC_BITand/orVK_IMAGE_USAGE_TRANSFER_DST_BIT
Images created with one of the formats that require a sampler Y′CBCR conversion, have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:
-
imageTypeisVK_IMAGE_TYPE_2D -
mipLevelsis 1 -
arrayLayersis 1, unless theycbcrImageArraysfeature is enabled, or otherwise indicated by VkImageFormatProperties::maxArrayLayers, as returned by vkGetPhysicalDeviceImageFormatProperties -
samplesisVK_SAMPLE_COUNT_1_BIT
Implementations may support additional limits and capabilities beyond those listed above.
To determine the set of valid usage bits for a given format, call
vkGetPhysicalDeviceFormatProperties.
If the size of the resultant image would exceed maxResourceSize, then
vkCreateImage must fail and return
VK_ERROR_OUT_OF_DEVICE_MEMORY.
This failure may occur even when all image creation parameters satisfy
their valid usage requirements.
If the implementation reports VK_TRUE in
VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirements,
usage of VK_IMAGE_USAGE_HOST_TRANSFER_BIT must not affect the memory
type requirements of the image as described in
Sparse Resource Memory Requirements and
Resource Memory Association.
|
For images created without For images created with |
The VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionImageCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCollectionFUCHSIA collection;
uint32_t index;
} VkBufferCollectionImageCreateInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexis the index of the buffer in the buffer collection from which the memory will be imported
The VkImageStencilUsageCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkImageStencilUsageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags stencilUsage;
} VkImageStencilUsageCreateInfo;or the equivalent
// Provided by VK_EXT_separate_stencil_usage
typedef VkImageStencilUsageCreateInfo VkImageStencilUsageCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
stencilUsageis a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.
If the pNext chain of VkImageCreateInfo includes a
VkImageStencilUsageCreateInfo structure, then that structure includes
the usage flags specific to the stencil aspect of the image for an image
with a depth-stencil format.
This structure specifies image usages which only apply to the stencil aspect
of a depth/stencil format image.
When this structure is included in the pNext chain of
VkImageCreateInfo, the stencil aspect of the image must only be used
as specified by stencilUsage.
When this structure is not included in the pNext chain of
VkImageCreateInfo, the stencil aspect of an image must only be used
as specified by VkImageCreateInfo::usage.
Use of other aspects of an image are unaffected by this structure.
This structure can also be included in the pNext chain of
VkPhysicalDeviceImageFormatInfo2 to query additional capabilities
specific to image creation parameter combinations including a separate set
of usage flags for the stencil aspect of the image using
vkGetPhysicalDeviceImageFormatProperties2.
When this structure is not included in the pNext chain of
VkPhysicalDeviceImageFormatInfo2 then the implicit value of
stencilUsage matches that of
VkPhysicalDeviceImageFormatInfo2::usage.
If the pNext chain includes a
VkDedicatedAllocationImageCreateInfoNV structure, then that structure
includes an enable controlling whether the image will have a dedicated
memory allocation bound to it.
The VkDedicatedAllocationImageCreateInfoNV structure is defined as:
// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationImageCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 dedicatedAllocation;
} VkDedicatedAllocationImageCreateInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
dedicatedAllocationspecifies whether the image will have a dedicated allocation bound to it.
|
Using a dedicated allocation for color and depth/stencil attachments or other large images may improve performance on some devices. |
To define a set of external memory handle types that may be used as backing
store for an image, add a VkExternalMemoryImageCreateInfo structure to
the pNext chain of the VkImageCreateInfo structure.
The VkExternalMemoryImageCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryImageCreateInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlags handleTypes;
} VkExternalMemoryImageCreateInfo;or the equivalent
// Provided by VK_KHR_external_memory
typedef VkExternalMemoryImageCreateInfo VkExternalMemoryImageCreateInfoKHR;|
A |
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.
If the pNext chain includes a VkExternalMemoryImageCreateInfoNV
structure, then that structure defines a set of external memory handle types
that may be used as backing store for the image.
The VkExternalMemoryImageCreateInfoNV structure is defined as:
// Provided by VK_NV_external_memory
typedef struct VkExternalMemoryImageCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagsNV handleTypes;
} VkExternalMemoryImageCreateInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypesis zero or a bitmask of VkExternalMemoryHandleTypeFlagBitsNV specifying one or more external memory handle types.
VkExternalFormatANDROID is defined as:
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkExternalFormatANDROID {
VkStructureType sType;
void* pNext;
uint64_t externalFormat;
} VkExternalFormatANDROID;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalFormatis an implementation-defined identifier for the external format
When included in the pNext chain of another structure, it indicates
additional format information beyond what is provided by VkFormat values for an
Android hardware buffer.
If externalFormat is zero, it indicates that no external format is
used, and implementations should rely only on other format information.
If this structure is not present, it is equivalent to setting
externalFormat to zero.
To create an image with an
QNX Screen external format, add a VkExternalFormatQNX structure in the pNext chain
of VkImageCreateInfo.
VkExternalFormatQNX is defined as:
// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkExternalFormatQNX {
VkStructureType sType;
void* pNext;
uint64_t externalFormat;
} VkExternalFormatQNX;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalFormatis an implementation-defined identifier for the external format
If externalFormat is zero, the effect is as if the
VkExternalFormatQNX structure was not present.
Otherwise, the image will have the specified external format.
If the pNext chain of VkImageCreateInfo includes a
VkImageSwapchainCreateInfoKHR structure, then that structure includes
a swapchain handle indicating that the image will be bound to memory from
that swapchain.
The VkImageSwapchainCreateInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkImageSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
} VkImageSwapchainCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis VK_NULL_HANDLE or a handle of a swapchain that the image will be bound to.
If the pNext chain of VkImageCreateInfo includes a
VkImageFormatListCreateInfo structure, then that structure contains a
list of all formats that can be used when creating views of this image.
The VkImageFormatListCreateInfo structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkImageFormatListCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t viewFormatCount;
const VkFormat* pViewFormats;
} VkImageFormatListCreateInfo;or the equivalent
// Provided by VK_KHR_image_format_list
typedef VkImageFormatListCreateInfo VkImageFormatListCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
viewFormatCountis the number of entries in thepViewFormatsarray. -
pViewFormatsis a pointer to an array of VkFormat values specifying all formats which can be used when creating views of this image.
If viewFormatCount is zero, pViewFormats is ignored and the
image is created as if the VkImageFormatListCreateInfo structure were
not included in the pNext chain of VkImageCreateInfo.
If the pNext chain of VkImageCreateInfo includes a
VkImageDrmFormatModifierListCreateInfoEXT structure, then the image
will be created with one of the Linux DRM format modifiers listed in the structure.
The choice of modifier is implementation-dependent.
The VkImageDrmFormatModifierListCreateInfoEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierListCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t drmFormatModifierCount;
const uint64_t* pDrmFormatModifiers;
} VkImageDrmFormatModifierListCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierCountis the length of thepDrmFormatModifiersarray. -
pDrmFormatModifiersis a pointer to an array of Linux DRM format modifiers.
If the pNext chain of VkImageCreateInfo includes a
VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the
image will be created with the Linux DRM format modifier and memory layout defined by the structure.
The VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierExplicitCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint64_t drmFormatModifier;
uint32_t drmFormatModifierPlaneCount;
const VkSubresourceLayout* pPlaneLayouts;
} VkImageDrmFormatModifierExplicitCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifieris the Linux DRM format modifier with which the image will be created. -
drmFormatModifierPlaneCountis the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of thepPlaneLayoutsarray. -
pPlaneLayoutsis a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.
The ith member of pPlaneLayouts describes the layout of the
image’s ith memory plane (that is,
VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT).
In each element of pPlaneLayouts, the implementation must ignore
size.
The implementation calculates the size of each plane, which the application
can query with vkGetImageSubresourceLayout.
When creating an image with
VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application’s
responsibility to satisfy all valid usage requirements.
However, the implementation must validate that the provided
pPlaneLayouts, when combined with the provided drmFormatModifier
and other creation parameters in VkImageCreateInfo and its pNext
chain, produce a valid image.
(This validation is necessarily implementation-dependent and outside the
scope of Vulkan, and therefore not described by valid usage requirements).
If this validation fails, then vkCreateImage returns
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
If the pNext list of VkImageCreateInfo includes a
VkImageCompressionControlEXT structure, then that structure describes
compression controls for this image.
The VkImageCompressionControlEXT structure is defined as:
// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionControlEXT {
VkStructureType sType;
const void* pNext;
VkImageCompressionFlagsEXT flags;
uint32_t compressionControlPlaneCount;
VkImageCompressionFixedRateFlagsEXT* pFixedRateFlags;
} VkImageCompressionControlEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageCompressionFlagBitsEXT describing compression controls for the image. -
compressionControlPlaneCountis the number of entries in thepFixedRateFlagsarray. -
pFixedRateFlagsisNULLor a pointer to an array of VkImageCompressionFixedRateFlagsEXT bitfields describing allowed fixed-rate compression rates of each image plane. It is ignored ifflagsdoes not includeVK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT.
If enabled, fixed-rate compression is done in an implementation-defined manner and may be applied at block granularity. In that case, a write to an individual texel may modify the value of other texels in the same block.
|
Some combinations of compression properties may not be supported. For example, some implementations may not support different fixed-rate compression rates per plane of a multi-planar format and will not be able to enable fixed-rate compression for any plane if the requested rates differ. |
Possible values of VkImageCompressionControlEXT::flags,
specifying compression controls for an image, are:
// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFlagBitsEXT {
VK_IMAGE_COMPRESSION_DEFAULT_EXT = 0,
VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT = 0x00000001,
VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT = 0x00000002,
VK_IMAGE_COMPRESSION_DISABLED_EXT = 0x00000004,
} VkImageCompressionFlagBitsEXT;-
VK_IMAGE_COMPRESSION_DEFAULT_EXTspecifies that the default image compression setting is used. Implementations must not apply fixed-rate compression. -
VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXTspecifies that the implementation may choose any supported fixed-rate compression setting in an implementation-defined manner based on the properties of the image. -
VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXTspecifies that fixed-rate compression may be used and that the allowed compression rates are specified by VkImageCompressionControlEXT::pFixedRateFlags. -
VK_IMAGE_COMPRESSION_DISABLED_EXTspecifies that all lossless and fixed-rate compression should be disabled.
If VkImageCompressionControlEXT::flags is
VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then the ith
member of the pFixedRateFlags array specifies the allowed compression
rates for the image’s ith plane.
|
If |
// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFlagsEXT;VkImageCompressionFlagsEXT is a bitmask type for setting a mask of
zero or more VkImageCompressionFlagBitsEXT.
// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFixedRateFlagsEXT;VkImageCompressionFixedRateFlagsEXT is a bitmask type for setting a
mask of zero or more VkImageCompressionFixedRateFlagBitsEXT.
Bits which can be set in
VkImageCompressionControlEXT::pFixedRateFlags, specifying
allowed compression rates for an image plane, are:
// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFixedRateFlagBitsEXT {
VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT = 0,
VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT = 0x00000001,
VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT = 0x00000002,
VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT = 0x00000004,
VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT = 0x00000008,
VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT = 0x00000010,
VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT = 0x00000020,
VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT = 0x00000040,
VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT = 0x00000080,
VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT = 0x00000100,
VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT = 0x00000200,
VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT = 0x00000400,
VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT = 0x00000800,
VK_IMAGE_COMPRESSION_FIXED_RATE_13BPC_BIT_EXT = 0x00001000,
VK_IMAGE_COMPRESSION_FIXED_RATE_14BPC_BIT_EXT = 0x00002000,
VK_IMAGE_COMPRESSION_FIXED_RATE_15BPC_BIT_EXT = 0x00004000,
VK_IMAGE_COMPRESSION_FIXED_RATE_16BPC_BIT_EXT = 0x00008000,
VK_IMAGE_COMPRESSION_FIXED_RATE_17BPC_BIT_EXT = 0x00010000,
VK_IMAGE_COMPRESSION_FIXED_RATE_18BPC_BIT_EXT = 0x00020000,
VK_IMAGE_COMPRESSION_FIXED_RATE_19BPC_BIT_EXT = 0x00040000,
VK_IMAGE_COMPRESSION_FIXED_RATE_20BPC_BIT_EXT = 0x00080000,
VK_IMAGE_COMPRESSION_FIXED_RATE_21BPC_BIT_EXT = 0x00100000,
VK_IMAGE_COMPRESSION_FIXED_RATE_22BPC_BIT_EXT = 0x00200000,
VK_IMAGE_COMPRESSION_FIXED_RATE_23BPC_BIT_EXT = 0x00400000,
VK_IMAGE_COMPRESSION_FIXED_RATE_24BPC_BIT_EXT = 0x00800000,
} VkImageCompressionFixedRateFlagBitsEXT;-
VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXTspecifies that fixed-rate compression must not be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [1,2) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [2,3) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [3,4) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [4,5) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [5,6) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [6,7) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [7,8) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [8,9) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [9,10) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [10,11) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of [11,12) bits per component may be used. -
VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXTspecifies that fixed-rate compression with a bitrate of at least 12 bits per component may be used.
If the format has a different bit rate for different components,
VkImageCompressionControlEXT::pFixedRateFlags describes the rate
of the component with the largest number of bits assigned to it, scaled pro
rata.
For example, to request that a VK_FORMAT_A2R10G10B10_UNORM_PACK32
format be stored at a rate of 8 bits per pixel, use
VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT (10 bits for the largest
component, stored at quarter the original size, 2.5 bits, rounded down).
If flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT,
and multiple bits are set in
VkImageCompressionControlEXT::pFixedRateFlags for a plane,
implementations should apply the lowest allowed bitrate that is supported.
|
The choice of “bits per component” terminology was chosen so that the same
compression rate describes the same degree of compression applied to formats
that differ only in the number of components.
For example, |
To query the compression properties of an image, add a
VkImageCompressionPropertiesEXT structure to the pNext chain of
the VkSubresourceLayout2 structure in a call to
vkGetImageSubresourceLayout2 or
vkGetImageSubresourceLayout2.
To determine the compression rates that are supported for a given image
format, add a VkImageCompressionPropertiesEXT structure to the
pNext chain of the VkImageFormatProperties2 structure in a call
to vkGetPhysicalDeviceImageFormatProperties2.
|
Since fixed-rate compression is disabled by default, the
VkImageCompressionPropertiesEXT structure passed to
vkGetPhysicalDeviceImageFormatProperties2 will not indicate any
fixed-rate compression support unless a VkImageCompressionControlEXT
structure is also included in the |
The VkImageCompressionPropertiesEXT structure is defined as:
// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionPropertiesEXT {
VkStructureType sType;
void* pNext;
VkImageCompressionFlagsEXT imageCompressionFlags;
VkImageCompressionFixedRateFlagsEXT imageCompressionFixedRateFlags;
} VkImageCompressionPropertiesEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageCompressionFlagsreturns a value describing the compression controls that apply to the image. The value will be eitherVK_IMAGE_COMPRESSION_DEFAULT_EXTto indicate no fixed-rate compression,VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXTto indicate fixed-rate compression, orVK_IMAGE_COMPRESSION_DISABLED_EXTto indicate no compression. -
imageCompressionFixedRateFlagsreturns a VkImageCompressionFixedRateFlagsEXT value describing the compression rates that apply to the specified aspect of the image.
If the pNext list of VkImageCreateInfo includes a
VkImageAlignmentControlCreateInfoMESA structure, then that structure
describes desired alignment for this image.
The VkImageAlignmentControlCreateInfoMESA structure is defined as:
// Provided by VK_MESA_image_alignment_control
typedef struct VkImageAlignmentControlCreateInfoMESA {
VkStructureType sType;
const void* pNext;
uint32_t maximumRequestedAlignment;
} VkImageAlignmentControlCreateInfoMESA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maximumRequestedAlignmentspecifies the maximum alignment for the image.
If maximumRequestedAlignment is not 0, the implementation should
choose an image memory layout that requires an alignment no larger than
maximumRequestedAlignment as reported in
VkMemoryRequirements::alignment.
If such a layout does not exist for the given image creation parameters, the
implementation should return the smallest alignment which is supported in
VkMemoryRequirements.
If an implementation needs to disable image compression for
maximumRequestedAlignment to be honored -
where a larger alignment would enable image compression -
the implementation should not use maximumRequestedAlignment, and
should return the smallest alignment which does not compromise compression.
If the imageCompressionControl
feature is enabled, the application can chain a
VkImageCompressionControlEXT with
VK_IMAGE_COMPRESSION_DISABLED_EXT.
In this case, image compression considerations should not apply when
implementation decides alignment.
Bits which can be set in
-
VkImageViewUsageCreateInfo::
usage -
VkImageStencilUsageCreateInfo::
stencilUsage -
VkImageCreateInfo::
usage
specify intended usage of an image, and are:
// Provided by VK_VERSION_1_0
typedef enum VkImageUsageFlagBits {
VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
// Provided by VK_VERSION_1_4
VK_IMAGE_USAGE_HOST_TRANSFER_BIT = 0x00400000,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00000400,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00000800,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR = 0x00001000,
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
// Provided by VK_KHR_fragment_shading_rate
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00000100,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00002000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00004000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR = 0x00008000,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x00080000,
// Provided by VK_HUAWEI_invocation_mask
VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
// Provided by VK_QCOM_image_processing
VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM = 0x00100000,
// Provided by VK_QCOM_image_processing
VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM = 0x00200000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x02000000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR = 0x04000000,
// Provided by VK_NV_shading_rate_image
VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
// Provided by VK_EXT_host_image_copy
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT = VK_IMAGE_USAGE_HOST_TRANSFER_BIT,
} VkImageUsageFlagBits;-
VK_IMAGE_USAGE_TRANSFER_SRC_BITspecifies that the image can be used as the source of a transfer command. -
VK_IMAGE_USAGE_TRANSFER_DST_BITspecifies that the image can be used as the destination of a transfer command. -
VK_IMAGE_USAGE_SAMPLED_BITspecifies that the image can be used to create aVkImageViewsuitable for occupying aVkDescriptorSetslot either of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGEorVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a shader. -
VK_IMAGE_USAGE_STORAGE_BITspecifies that the image can be used to create aVkImageViewsuitable for occupying aVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGE. -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for use as a color or resolve attachment in aVkFramebuffer. -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for use as a depth/stencil or depth/stencil resolve attachment in aVkFramebuffer. -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITspecifies that implementations may support using memory allocations with theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITto back an image with this usage. This bit can be set for any image that can be used to create aVkImageViewsuitable for use as a color, resolve, depth/stencil, or input attachment. -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BITspecifies that the image can be used to create aVkImageViewsuitable for occupyingVkDescriptorSetslot of typeVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer. -
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXTspecifies that the image can be used to create aVkImageViewsuitable for use as a fragment density map image. -
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRspecifies that the image can be used to create aVkImageViewsuitable for use as a fragment shading rate attachment or shading rate image -
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRspecifies that the image can be used as a decode output picture in a video decode operation. -
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRspecifies that the image can be used as an output reconstructed picture or an input reference picture in a video decode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHRis reserved for future use. -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRspecifies that the image can be used as an encode input picture in a video encode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRspecifies that the image can be used as an output reconstructed picture or an input reference picture in a video encode operation. -
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTspecifies that the image can be transitioned to theVK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTlayout to be used as a color or depth/stencil attachment in aVkFramebufferand/or as a read-only input resource in a shader (sampled image, combined image sampler or input attachment) in the same render pass. -
VK_IMAGE_USAGE_HOST_TRANSFER_BITspecifies that the image can be used with host copy commands and host layout transitions. -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRspecifies that the image can be used as a quantization delta map in a video encode operation. -
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHRspecifies that the image can be used as an emphasis map in a video encode operation.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;VkImageUsageFlags is a bitmask type for setting a mask of zero or more
VkImageUsageFlagBits.
When creating a VkImageView one of the following
VkImageUsageFlagBits must be set:
-
VK_IMAGE_USAGE_SAMPLED_BIT -
VK_IMAGE_USAGE_STORAGE_BIT -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT -
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT -
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR -
VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM -
VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM -
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR -
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR
Bits which can be set in VkImageCreateInfo::flags, specifying
additional parameters of an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageCreateFlagBits {
VK_IMAGE_CREATE_SPARSE_BINDING_BIT = 0x00000001,
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT = 0x00000008,
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_ALIAS_BIT = 0x00000400,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT = 0x00000040,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT = 0x00000080,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT = 0x00000100,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_PROTECTED_BIT = 0x00000800,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_DISJOINT_BIT = 0x00000200,
// Provided by VK_NV_corner_sampled_image
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV = 0x00002000,
// Provided by VK_EXT_sample_locations
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT = 0x00001000,
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT = 0x00004000,
// Provided by VK_EXT_descriptor_buffer
VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00010000,
// Provided by VK_EXT_multisampled_render_to_single_sampled
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT = 0x00040000,
// Provided by VK_EXT_image_2d_view_of_3d
VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT = 0x00020000,
// Provided by VK_QCOM_fragment_density_map_offset
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM = 0x00008000,
// Provided by VK_KHR_video_maintenance1
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00100000,
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT,
// Provided by VK_KHR_maintenance1
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT,
// Provided by VK_KHR_maintenance2
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT,
// Provided by VK_KHR_maintenance2
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR = VK_IMAGE_CREATE_EXTENDED_USAGE_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_IMAGE_CREATE_DISJOINT_BIT_KHR = VK_IMAGE_CREATE_DISJOINT_BIT,
// Provided by VK_KHR_bind_memory2
VK_IMAGE_CREATE_ALIAS_BIT_KHR = VK_IMAGE_CREATE_ALIAS_BIT,
} VkImageCreateFlagBits;-
VK_IMAGE_CREATE_SPARSE_BINDING_BITspecifies that the image will be backed using sparse memory binding. -
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BITspecifies that the image can be partially backed using sparse memory binding. Images created with this flag must also be created with theVK_IMAGE_CREATE_SPARSE_BINDING_BITflag. -
VK_IMAGE_CREATE_SPARSE_ALIASED_BITspecifies that the image will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another image (or another portion of the same image). Images created with this flag must also be created with theVK_IMAGE_CREATE_SPARSE_BINDING_BITflag. -
VK_IMAGE_CREATE_MUTABLE_FORMAT_BITspecifies that the image can be used to create aVkImageViewwith a different format from the image. For multi-planar formats,VK_IMAGE_CREATE_MUTABLE_FORMAT_BITspecifies that aVkImageViewcan be created of a plane of the image. -
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BITspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_CUBEorVK_IMAGE_VIEW_TYPE_CUBE_ARRAY. -
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BITspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_2DorVK_IMAGE_VIEW_TYPE_2D_ARRAY. -
VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXTspecifies that the image can be used to create aVkImageViewof typeVK_IMAGE_VIEW_TYPE_2D. -
VK_IMAGE_CREATE_PROTECTED_BITspecifies that the image is a protected image. -
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITspecifies that the image can be used with a non-zero value of thesplitInstanceBindRegionCountmember of a VkBindImageMemoryDeviceGroupInfo structure passed into vkBindImageMemory2. This flag also has the effect of making the image use the standard sparse image block dimensions. -
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BITspecifies that the image having a compressed format can be used to create aVkImageViewwith an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image. -
VK_IMAGE_CREATE_EXTENDED_USAGE_BITspecifies that the image can be created with usage flags that are not supported for the format the image is created with but are supported for at least one format aVkImageViewcreated from the image can have. -
VK_IMAGE_CREATE_DISJOINT_BITspecifies that an image with a multi-planar format must have each plane separately bound to memory, rather than having a single memory binding for the whole image; the presence of this bit distinguishes a disjoint image from an image without this bit set. -
VK_IMAGE_CREATE_ALIAS_BITspecifies that two images created with the same creation parameters and aliased to the same memory can interpret the contents of the memory consistently with each other, subject to the rules described in the Memory Aliasing section. This flag further specifies that each plane of a disjoint image can share an in-memory non-linear representation with single-plane images, and that a single-plane image can share an in-memory non-linear representation with a plane of a multi-planar disjoint image, according to the rules in Compatible Formats of Planes of Multi-Planar Formats. If thepNextchain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whosehandleTypesmember is not0, it is as ifVK_IMAGE_CREATE_ALIAS_BITis set. -
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXTspecifies that an image with a depth or depth/stencil format can be used with custom sample locations when used as a depth/stencil attachment. -
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NVspecifies that the image is a corner-sampled image. -
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXTspecifies that an image can be in a subsampled format which may be more optimal when written as an attachment by a render pass that has a fragment density map attachment. Accessing a subsampled image has additional considerations:-
Image data read as an image sampler will have undefined values if the sampler was not created with
flagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXTor was not sampled through the use of a combined image sampler with an immutable sampler inVkDescriptorSetLayoutBinding. -
Image data read with an input attachment will have undefined values if the contents were not written as an attachment in an earlier subpass of the same render pass.
-
Image data read as an image sampler in the fragment shader will be additionally be read by the device during
VK_PIPELINE_STAGE_VERTEX_SHADER_BITifVkPhysicalDeviceFragmentDensityMap2PropertiesEXT::subsampledCoarseReconstructionEarlyAccessisVK_TRUEand the sampler was created withflagscontainingVK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT. -
Image data read with load operations are resampled to the fragment density of the render pass if
VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::subsampledLoadsisVK_TRUE. Otherwise, values of image data are undefined. -
Image contents outside of the render area take on undefined values if the image is stored as a render pass attachment.
-
-
VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOMspecifies that an image can be used in a render pass with non-zero fragment density map offsets. In a render pass with non-zero offsets, fragment density map attachments, input attachments, color attachments, depth/stencil attachment, resolve attachments, and preserve attachments must be created withVK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM. -
VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the image can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXTspecifies that an image can be used with multisampled rendering as a single-sampled framebuffer attachment -
VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHRspecifies that the image can be used in video coding operations without having to specify at image creation time the set of video profiles the image will be used with, except for images used only as DPB pictures, as long as the image is otherwise compatible with the video profile in question.This enables exchanging video picture data without additional copies or conversions when used as:
-
Decode output pictures, indifferent of the video profile used to produce them.
-
Encode input pictures, indifferent of the video profile used to consume them.
This includes images created with both
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRandVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, which is necessary to use the same video picture as the reconstructed picture and decode output picture in a video decode operation on implementations supportingVK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR.However, images with only DPB usage remain tied to the video profiles the image was created with, as the data layout of such DPB-only images may be implementation- and codec-dependent.
If an application would like to share or reuse the device memory backing such images (e.g. for the purposes of temporal aliasing), then it should create separate image objects for each video profile and bind them to the same underlying device memory range, similar to how memory resources can be shared across separate video sessions or any other memory-backed resource.
-
See Sparse Resource Features and Sparse Physical Device Features for more details.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageCreateFlags;VkImageCreateFlags is a bitmask type for setting a mask of zero or
more VkImageCreateFlagBits.
Possible values of VkImageCreateInfo::imageType, specifying the
basic dimensionality of an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageType {
VK_IMAGE_TYPE_1D = 0,
VK_IMAGE_TYPE_2D = 1,
VK_IMAGE_TYPE_3D = 2,
} VkImageType;-
VK_IMAGE_TYPE_1Dspecifies a one-dimensional image. -
VK_IMAGE_TYPE_2Dspecifies a two-dimensional image. -
VK_IMAGE_TYPE_3Dspecifies a three-dimensional image.
Possible values of VkImageCreateInfo::tiling, specifying the
tiling arrangement of texel blocks in an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageTiling {
VK_IMAGE_TILING_OPTIMAL = 0,
VK_IMAGE_TILING_LINEAR = 1,
// Provided by VK_EXT_image_drm_format_modifier
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000,
} VkImageTiling;-
VK_IMAGE_TILING_OPTIMALspecifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more efficient memory access). -
VK_IMAGE_TILING_LINEARspecifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row). -
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXTspecifies that the image’s tiling is defined by a Linux DRM format modifier. The modifier is specified at image creation with VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT, and can be queried with vkGetImageDrmFormatModifierPropertiesEXT.
To query the memory layout of an image subresource, call:
// Provided by VK_VERSION_1_0
void vkGetImageSubresourceLayout(
VkDevice device,
VkImage image,
const VkImageSubresource* pSubresource,
VkSubresourceLayout* pLayout);-
deviceis the logical device that owns the image. -
imageis the image whose layout is being queried. -
pSubresourceis a pointer to a VkImageSubresource structure selecting a specific image subresource from the image. -
pLayoutis a pointer to a VkSubresourceLayout structure in which the layout is returned.
If the image is linear, then the returned layout is valid for host access.
If the image’s
tiling is VK_IMAGE_TILING_LINEAR and its
format is a multi-planar format, then
vkGetImageSubresourceLayout describes one
format plane
of the image.
If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then
vkGetImageSubresourceLayout describes one memory plane of the image.
If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and
the image is non-linear, then the returned
layout has an implementation-dependent meaning; the vendor of the image’s
DRM format modifier may provide
documentation that explains how to interpret the returned layout.
vkGetImageSubresourceLayout is invariant for the lifetime of a single
image.
However, the subresource layout of images in Android hardware buffer or QNX
Screen buffer external memory is not known until the image has been bound to
memory, so applications must not call vkGetImageSubresourceLayout for
such an image before it has been bound.
The VkImageSubresource structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresource {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t arrayLayer;
} VkImageSubresource;-
aspectMaskis a VkImageAspectFlags value selecting the image aspect. -
mipLevelselects the mipmap level. -
arrayLayerselects the array layer.
Information about the layout of the image subresource is returned in a
VkSubresourceLayout structure:
// Provided by VK_VERSION_1_0
typedef struct VkSubresourceLayout {
VkDeviceSize offset;
VkDeviceSize size;
VkDeviceSize rowPitch;
VkDeviceSize arrayPitch;
VkDeviceSize depthPitch;
} VkSubresourceLayout;-
offsetis the byte offset from the start of the image or the plane where the image subresource begins. -
sizeis the size in bytes of the image subresource.sizeincludes any extra memory that is required based onrowPitch. -
rowPitchdescribes the number of bytes between each row of texels in an image. -
arrayPitchdescribes the number of bytes between each array layer of an image. -
depthPitchdescribes the number of bytes between each slice of 3D image.
If the image is linear, then rowPitch,
arrayPitch and depthPitch describe the layout of the image
subresource in linear memory.
For uncompressed formats, rowPitch is the number of bytes between
texels with the same x coordinate in adjacent rows (y coordinates differ by
one).
arrayPitch is the number of bytes between texels with the same x and y
coordinate in adjacent array layers of the image (array layer values differ
by one).
depthPitch is the number of bytes between texels with the same x and y
coordinate in adjacent slices of a 3D image (z coordinates differ by one).
Expressed as an addressing formula, the starting byte of a texel in the
image subresource has address:
// (x,y,z,layer) are in texel coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offsetFor compressed formats, the rowPitch is the number of bytes between
compressed texel blocks in adjacent rows.
arrayPitch is the number of bytes between compressed texel blocks in
adjacent array layers.
depthPitch is the number of bytes between compressed texel blocks in
adjacent slices of a 3D image.
// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;The value of arrayPitch is undefined for images that were not created
as arrays.
depthPitch is defined only for 3D images.
If the image has a
single-plane
color format
and its tiling is VK_IMAGE_TILING_LINEAR
, then the aspectMask member of VkImageSubresource must be
VK_IMAGE_ASPECT_COLOR_BIT.
If the image has a depth/stencil format
and its tiling is VK_IMAGE_TILING_LINEAR
, then aspectMask must be either VK_IMAGE_ASPECT_DEPTH_BIT or
VK_IMAGE_ASPECT_STENCIL_BIT.
On implementations that store depth and stencil aspects separately, querying
each of these image subresource layouts will return a different offset
and size representing the region of memory used for that aspect.
On implementations that store depth and stencil aspects interleaved, the
same offset and size are returned and represent the interleaved
memory allocation.
If the image has a multi-planar format
and its tiling is VK_IMAGE_TILING_LINEAR
, then the aspectMask member of VkImageSubresource must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or
(for 3-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT.
Querying each of these image subresource layouts will return a different
offset and size representing the region of memory used for that
plane.
If the image is disjoint, then the offset is relative to the base
address of the plane.
If the image is non-disjoint, then the offset is relative to the
base address of the image.
If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then
the aspectMask member of VkImageSubresource must be one of
VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT, where the maximum allowed
plane index i is defined by the
VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount
associated with the image’s VkImageCreateInfo::format and
modifier.
The memory range used by the subresource is described by offset and
size.
If the image is disjoint, then the offset is relative to the base
address of the memory plane.
If the image is non-disjoint, then the offset is relative to the
base address of the image.
If the image is non-linear, then
rowPitch, arrayPitch, and depthPitch have an
implementation-dependent meaning.
To query the memory layout of an image subresource, call:
// Provided by VK_VERSION_1_4
void vkGetImageSubresourceLayout2(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);or the equivalent command
// Provided by VK_KHR_maintenance5
void vkGetImageSubresourceLayout2KHR(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);or the equivalent command
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
void vkGetImageSubresourceLayout2EXT(
VkDevice device,
VkImage image,
const VkImageSubresource2* pSubresource,
VkSubresourceLayout2* pLayout);-
deviceis the logical device that owns the image. -
imageis the image whose layout is being queried. -
pSubresourceis a pointer to a VkImageSubresource2 structure selecting a specific image for the image subresource. -
pLayoutis a pointer to a VkSubresourceLayout2 structure in which the layout is returned.
vkGetImageSubresourceLayout2 behaves similarly to
vkGetImageSubresourceLayout, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.
It is legal to call vkGetImageSubresourceLayout2 with an image
created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the
members of VkSubresourceLayout2::subresourceLayout will have
undefined values in this case.
|
Structures chained from VkImageSubresource2:: |
The VkImageSubresource2 structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkImageSubresource2 {
VkStructureType sType;
void* pNext;
VkImageSubresource imageSubresource;
} VkImageSubresource2;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkImageSubresource2 VkImageSubresource2KHR;or the equivalent
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkImageSubresource2 VkImageSubresource2EXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageSubresourceis a VkImageSubresource structure.
Information about the layout of the image subresource is returned in a
VkSubresourceLayout2 structure:
// Provided by VK_VERSION_1_4
typedef struct VkSubresourceLayout2 {
VkStructureType sType;
void* pNext;
VkSubresourceLayout subresourceLayout;
} VkSubresourceLayout2;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkSubresourceLayout2 VkSubresourceLayout2KHR;or the equivalent
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
typedef VkSubresourceLayout2 VkSubresourceLayout2EXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
subresourceLayoutis a VkSubresourceLayout structure.
To query the memory size needed to copy to or from an image using
vkCopyMemoryToImage or vkCopyImageToMemory when the
VK_HOST_IMAGE_COPY_MEMCPY flag is specified, add a
VkSubresourceHostMemcpySize structure to the pNext chain of the
VkSubresourceLayout2 structure in a call to
vkGetImageSubresourceLayout2.
The VkSubresourceHostMemcpySize structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkSubresourceHostMemcpySize {
VkStructureType sType;
void* pNext;
VkDeviceSize size;
} VkSubresourceHostMemcpySize;or the equivalent
// Provided by VK_EXT_host_image_copy
typedef VkSubresourceHostMemcpySize VkSubresourceHostMemcpySizeEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sizeis the size in bytes of the image subresource.
To query the memory layout of an image subresource, without an image object, call:
// Provided by VK_VERSION_1_4
void vkGetDeviceImageSubresourceLayout(
VkDevice device,
const VkDeviceImageSubresourceInfo* pInfo,
VkSubresourceLayout2* pLayout);or the equivalent command
// Provided by VK_KHR_maintenance5
void vkGetDeviceImageSubresourceLayoutKHR(
VkDevice device,
const VkDeviceImageSubresourceInfo* pInfo,
VkSubresourceLayout2* pLayout);-
deviceis the logical device that owns the image. -
pInfois a pointer to a VkDeviceImageSubresourceInfo structure containing parameters required for the subresource layout query. -
pLayoutis a pointer to a VkSubresourceLayout2 structure in which the layout is returned.
vkGetDeviceImageSubresourceLayout behaves similarly to
vkGetImageSubresourceLayout2, but uses a VkImageCreateInfo
structure to specify the image rather than a VkImage object.
The VkDeviceImageSubresourceInfo structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkDeviceImageSubresourceInfo {
VkStructureType sType;
const void* pNext;
const VkImageCreateInfo* pCreateInfo;
const VkImageSubresource2* pSubresource;
} VkDeviceImageSubresourceInfo;or the equivalent
// Provided by VK_KHR_maintenance5
typedef VkDeviceImageSubresourceInfo VkDeviceImageSubresourceInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkImageCreateInfo structure containing parameters affecting creation of the image to query. -
pSubresourcepSubresource is a pointer to a VkImageSubresource2 structure selecting a specific image subresource for the query.
If an image was created with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT,
then the image has a Linux DRM format modifier.
To query the modifier, call:
// Provided by VK_EXT_image_drm_format_modifier
VkResult vkGetImageDrmFormatModifierPropertiesEXT(
VkDevice device,
VkImage image,
VkImageDrmFormatModifierPropertiesEXT* pProperties);-
deviceis the logical device that owns the image. -
imageis the queried image. -
pPropertiesis a pointer to a VkImageDrmFormatModifierPropertiesEXT structure in which properties of the image’s DRM format modifier are returned.
The VkImageDrmFormatModifierPropertiesEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierPropertiesEXT {
VkStructureType sType;
void* pNext;
uint64_t drmFormatModifier;
} VkImageDrmFormatModifierPropertiesEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifierreturns the image’s Linux DRM format modifier.
If the image was created with
VkImageDrmFormatModifierListCreateInfoEXT, then the returned
drmFormatModifier must belong to the list of modifiers provided at
time of image creation in
VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers.
If the image was created with
VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned
drmFormatModifier must be the modifier provided at time of image
creation in
VkImageDrmFormatModifierExplicitCreateInfoEXT::drmFormatModifier.
To destroy an image, call:
// Provided by VK_VERSION_1_0
void vkDestroyImage(
VkDevice device,
VkImage image,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the image. -
imageis the image to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Image Format Features
Valid uses of a VkImage may depend on the image’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If the image was created with
VK_IMAGE_TILING_LINEAR, then its set of format features is the value of VkFormatProperties::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageCreateInfo::format. -
If the image was created with
VK_IMAGE_TILING_OPTIMAL, but without an Android hardware buffer external format, or a QNX Screen Buffer external format or an VkBufferCollectionImageCreateInfoFUCHSIA, then its set of format features is the value of VkFormatProperties::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageCreateInfo::format. -
If the image was created with an Android hardware buffer external format, then its set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::
formatFeaturesfound by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the image is bound. -
If the image was created with an QNX Screen buffer external format, then its set of format features is the value of VkScreenBufferFormatPropertiesQNX::
formatFeaturesfound by calling vkGetScreenBufferPropertiesQNX on the QNX Screen buffer that was imported to the VkDeviceMemory to which the image is bound. -
If the image was created with
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then:-
The image’s DRM format modifier is the value of VkImageDrmFormatModifierPropertiesEXT::
drmFormatModifierfound by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierPropertiesbe the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageCreateInfo::format. -
Let
VkDrmFormatModifierPropertiesEXT propbe the array element whosedrmFormatModifiermember is the value of the image’s DRM format modifier. -
Then the image’s set of format features is the value of
prop::drmFormatModifierTilingFeatures.
-
Corner-Sampled Images
A corner-sampled image is an image where unnormalized texel coordinates are centered on integer values rather than half-integer values.
A corner-sampled image has a number of differences compared to conventional texture image:
-
Texels are centered on integer coordinates. See Unnormalized Texel Coordinate Operations
-
Normalized coordinates are scaled using coord × (dim - 1) rather than coord × dim, where dim is the size of one dimension of the image. See normalized texel coordinate transform.
-
Partial derivatives are scaled using coord × (dim - 1) rather than coord × dim. See Scale Factor Operation.
-
Calculation of the next higher LOD size goes according to ⌈dim / 2⌉ rather than ⌊dim / 2⌋. See Image Mip Level Sizing.
-
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Mip Level Sizing.
Corner-sampling is only supported for 2D and 3D images.
When sampling a corner-sampled image, the sampler addressing mode must be
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Corner-sampled images are not supported as cube maps or depth/stencil
images.
Image Mip Level Sizing
A complete mipmap chain is the full set of mip levels, from the largest mip level provided, down to the minimum mip level size.
Conventional Images
For conventional images, the dimensions of each successive mip level, n+1, are:
-
widthn+1 = max(⌊widthn/2⌋, 1) -
heightn+1 = max(⌊heightn/2⌋, 1) -
depthn+1 = max(⌊depthn/2⌋, 1)
where widthn, heightn, and depthn
are the dimensions of the next larger mip level, n.
The minimum mip level size is:
-
1 for one-dimensional images,
-
1x1 for two-dimensional images, and
-
1x1x1 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌊log2(max(
width0,height0,depth0))⌋ + 1
where width0, height0, and depth0
are the dimensions of the largest (most detailed) mip level, 0.
Corner-Sampled Images
For corner-sampled images, the dimensions of each successive mip level, n+1, are:
-
widthn+1 = max(⌈widthn/2⌉, 2) -
heightn+1 = max(⌈heightn/2⌉, 2) -
depthn+1 = max(⌈depthn/2⌉, 2)
where widthn, heightn, and depthn
are the dimensions of the next larger mip level, n.
The minimum mip level size is:
-
2x2 for two-dimensional images, and
-
2x2x2 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌈log2(max(
width0,height0,depth0))⌉
where width0, height0, and depth0
are the dimensions of the largest (most detailed) mip level, 0.
Image Layouts
Images are stored in implementation-dependent opaque layouts in memory.
Each layout has limitations on what kinds of operations are supported for
image subresources using the layout.
At any given time, the data representing an image subresource in memory
exists in a particular layout which is determined by the most recent layout
transition that was performed on that image subresource.
Applications have control over which layout each image subresource uses, and
can transition an image subresource from one layout to another.
Transitions can happen with an image memory barrier, included as part of a
vkCmdPipelineBarrier or a vkCmdWaitEvents command buffer command
(see Image Memory Barriers), or as part of a subpass
dependency within a render pass (see VkSubpassDependency).
Image layout is per-image subresource.
Separate image subresources of the same image can be in different layouts
at the same time, with the exception that depth and stencil aspects of a
given image subresource can only be in different layouts if the
separateDepthStencilLayouts
feature is enabled.
When an VkImageView descriptor is accessed on the device, all image
subresources must be in a valid image layout.
|
Each layout may offer optimal performance for a specific usage of image
memory.
For example, an image with a layout of
|
Upon creation, all image subresources of an image are initially in the same
layout, where that layout is selected by the
VkImageCreateInfo::initialLayout member.
The initialLayout must be either VK_IMAGE_LAYOUT_UNDEFINED or
VK_IMAGE_LAYOUT_PREINITIALIZED.
If it is VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can be
preinitialized by the host while using this layout, and the transition away
from this layout will preserve that data.
If it is VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are
considered to be undefined, and the transition away from this layout is not
guaranteed to preserve that data.
For either of these initial layouts, any image subresources must be
transitioned to another layout before they are accessed by the device.
Host access to image memory is only well-defined for
linear images and for image subresources of
those images which are currently in either the
VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL
layout.
Calling vkGetImageSubresourceLayout for a linear image returns a
subresource layout mapping that is valid for either of those image layouts.
The set of image layouts consists of:
// Provided by VK_VERSION_1_0
typedef enum VkImageLayout {
VK_IMAGE_LAYOUT_UNDEFINED = 0,
VK_IMAGE_LAYOUT_GENERAL = 1,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL = 2,
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL = 3,
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL = 4,
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL = 5,
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL = 6,
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL = 7,
VK_IMAGE_LAYOUT_PREINITIALIZED = 8,
// Provided by VK_VERSION_1_1
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
// Provided by VK_VERSION_1_1
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL = 1000241000,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL = 1000241001,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL = 1000241002,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL = 1000241003,
// Provided by VK_VERSION_1_3
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL = 1000314000,
// Provided by VK_VERSION_1_3
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL = 1000314001,
// Provided by VK_VERSION_1_4
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ = 1000232000,
// Provided by VK_KHR_swapchain
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR = 1000024000,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR = 1000024001,
// Provided by VK_KHR_video_decode_queue
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR = 1000024002,
// Provided by VK_KHR_shared_presentable_image
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
// Provided by VK_KHR_fragment_shading_rate
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR = 1000164003,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR = 1000299000,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR = 1000299001,
// Provided by VK_KHR_video_encode_queue
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR = 1000299002,
// Provided by VK_EXT_attachment_feedback_loop_layout
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT = 1000339000,
// Provided by VK_KHR_video_encode_quantization_map
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR = 1000553000,
// Provided by VK_KHR_maintenance2
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
// Provided by VK_KHR_maintenance2
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
// Provided by VK_NV_shading_rate_image
VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV = VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR,
// Provided by VK_KHR_dynamic_rendering_local_read
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR = VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL,
// Provided by VK_KHR_separate_depth_stencil_layouts
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,
// Provided by VK_KHR_synchronization2
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL,
// Provided by VK_KHR_synchronization2
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL,
} VkImageLayout;The type(s) of device access supported by each layout are:
-
VK_IMAGE_LAYOUT_UNDEFINEDspecifies that the layout is unknown. Image memory cannot be transitioned into this layout. This layout can be used as theinitialLayoutmember of VkImageCreateInfo. This layout can be used in place of the current image layout in a layout transition, but doing so will cause the contents of the image’s memory to be undefined. -
VK_IMAGE_LAYOUT_PREINITIALIZEDspecifies that an image’s memory is in a defined layout and can be populated by data, but that it has not yet been initialized by the driver. Image memory cannot be transitioned into this layout. This layout can be used as theinitialLayoutmember of VkImageCreateInfo. This layout is intended to be used as the initial layout for an image whose contents are written by the host, and hence the data can be written to memory immediately, without first executing a layout transition. Currently,VK_IMAGE_LAYOUT_PREINITIALIZEDis only useful with linear images because there is not a standard layout defined forVK_IMAGE_TILING_OPTIMALimages. -
VK_IMAGE_LAYOUT_GENERALsupports all types of device access, unless specified otherwise. -
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMALspecifies a layout that must only be used with attachment accesses in the graphics pipeline. -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMALspecifies a layout allowing read only access as an attachment, or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMALmust only be used as a color or resolve attachment in aVkFramebuffer. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITusage bit enabled. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMALspecifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read and write access as a depth/stencil attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMALspecifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read only access as a depth/stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMALspecifies a layout for depth/stencil format images allowing read and write access to the stencil aspect as a stencil attachment, and read only access to the depth aspect as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMALspecifies a layout for depth/stencil format images allowing read and write access to the depth aspect as a depth attachment, and read only access to the stencil aspect as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMALandVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMALspecifies a layout for the depth aspect of a depth/stencil format image allowing read and write access as a depth attachment. -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMALspecifies a layout for the depth aspect of a depth/stencil format image allowing read-only access as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMALspecifies a layout for the stencil aspect of a depth/stencil format image allowing read and write access as a stencil attachment. -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMALspecifies a layout for the stencil aspect of a depth/stencil format image allowing read-only access as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMALspecifies a layout allowing read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_SAMPLED_BITorVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITusage bits enabled. -
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMALmust only be used as a source image of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT). This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_TRANSFER_SRC_BITusage bit enabled. -
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMALmust only be used as a destination image of a transfer command. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_TRANSFER_DST_BITusage bit enabled. -
VK_IMAGE_LAYOUT_PRESENT_SRC_KHRmust only be used for presenting a presentable image for display. -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHRis valid only for shared presentable images, and must be used for any usage the image supports. -
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHRmust only be used as a fragment shading rate attachment or shading rate image. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXTmust only be used as a fragment density map attachment in aVkRenderPass. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXTusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHRmust only be used as a decode output picture in a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHRis reserved for future use. -
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHRmust only be used as an output reconstructed picture or an input reference picture in a video decode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHRis reserved for future use. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHRmust only be used as an encode input picture in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHRmust only be used as an output reconstructed picture or an input reference picture in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHRusage bit enabled. -
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXTmust only be used as either a color attachment or depth/stencil attachment in aVkFramebufferand/or read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXTusage bit enabled and either theVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITorVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BITand either theVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITorVK_IMAGE_USAGE_SAMPLED_BITusage bits enabled. -
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READmust only be used as either a storage image, or a color or depth/stencil attachment and an input attachment. This layout is valid only for image subresources of images created with eitherVK_IMAGE_USAGE_STORAGE_BIT, or bothVK_IMAGE_USAGE_INPUT_ATTACHMENT_BITand either ofVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITorVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT. -
VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHRmust only be used as a quantization map in a video encode operation. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHRorVK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHRusage bit enabled.
The layout of each image subresource is not a state of the image subresource
itself, but is rather a property of how the data in memory is organized, and
thus for each mechanism of accessing an image in the API the application
must specify a parameter or structure member that indicates which image
layout the image subresource(s) are considered to be in when the image will
be accessed.
For transfer commands, this is a parameter to the command (see Clear Commands
and Copy Commands).
For use as a framebuffer attachment, this is a member in the substructures
of the VkRenderPassCreateInfo (see Render Pass).
For use in a descriptor set, this is a member in the
VkDescriptorImageInfo structure (see Descriptor Set Updates).
|
|
|
While |
Image Layout Matching Rules
At the time that any command buffer command accessing an image executes on any queue, the layouts of the image subresources that are accessed must all match exactly the layout specified via the API controlling those accesses, except in case of accesses to an image with a depth/stencil format performed through descriptors referring to only a single aspect of the image, where the following relaxed matching rules apply:
-
Descriptors referring just to the depth aspect of a depth/stencil image only need to match in the image layout of the depth aspect, thus
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMALandVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMALare considered to match. -
Descriptors referring just to the stencil aspect of a depth/stencil image only need to match in the image layout of the stencil aspect, thus
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMALandVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMALare considered to match.
When performing a layout transition on an image subresource, the old layout
value must either equal the current layout of the image subresource (at the
time the transition executes), or else be VK_IMAGE_LAYOUT_UNDEFINED
(implying that the contents of the image subresource need not be preserved).
The new layout used in a transition must not be
VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.
The image layout of each image subresource of a depth/stencil image created
with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is
dependent on the last sample locations used to render to the image
subresource as a depth/stencil attachment, thus applications must provide
the same sample locations that were last used to render to the given image
subresource whenever a layout transition of the image subresource happens,
otherwise the contents of the depth aspect of the image subresource become
undefined.
In addition, depth reads from a depth/stencil attachment referring to an
image subresource range of a depth/stencil image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
different sample locations than what have been last used to perform depth
writes to the image subresources of the same image subresource range return
undefined values.
Similarly, depth writes to a depth/stencil attachment referring to an image
subresource range of a depth/stencil image created with
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
different sample locations than what have been last used to perform depth
writes to the image subresources of the same image subresource range make
the contents of the depth aspect of those image subresources undefined.
Image Views
Image objects are not directly accessed by pipeline shaders for reading or writing image data. Instead, image views representing contiguous ranges of the image subresources and containing additional metadata are used for that purpose. Views must be created on images of compatible types, and must represent a valid subset of image subresources.
Image views are represented by VkImageView handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)VK_REMAINING_ARRAY_LAYERS is a special constant value used for image
views to indicate that all remaining array layers in an image after the base
layer should be included in the view.
#define VK_REMAINING_ARRAY_LAYERS (~0U)VK_REMAINING_MIP_LEVELS is a special constant value used for image
views to indicate that all remaining mipmap levels in an image after the
base level should be included in the view.
#define VK_REMAINING_MIP_LEVELS (~0U)The types of image views that can be created are:
// Provided by VK_VERSION_1_0
typedef enum VkImageViewType {
VK_IMAGE_VIEW_TYPE_1D = 0,
VK_IMAGE_VIEW_TYPE_2D = 1,
VK_IMAGE_VIEW_TYPE_3D = 2,
VK_IMAGE_VIEW_TYPE_CUBE = 3,
VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
} VkImageViewType;To create an image view, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateImageView(
VkDevice device,
const VkImageViewCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkImageView* pView);-
deviceis the logical device that creates the image view. -
pCreateInfois a pointer to a VkImageViewCreateInfo structure containing parameters to be used to create the image view. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pViewis a pointer to a VkImageView handle in which the resulting image view object is returned.
The VkImageViewCreateInfo structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageViewCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageViewCreateFlags flags;
VkImage image;
VkImageViewType viewType;
VkFormat format;
VkComponentMapping components;
VkImageSubresourceRange subresourceRange;
} VkImageViewCreateInfo;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkImageViewCreateFlagBits specifying additional parameters of the image view. -
imageis a VkImage on which the view will be created. -
viewTypeis a VkImageViewType value specifying the type of the image view. -
formatis a VkFormat specifying the format and type used to interpret texel blocks of the image. -
componentsis a VkComponentMapping structure specifying a remapping of color components (or of depth or stencil components after they have been converted into color components). -
subresourceRangeis a VkImageSubresourceRange structure selecting the set of mipmap levels and array layers to be accessible to the view.
Some of the image creation parameters are inherited by the view.
In particular, image view creation inherits the implicit parameter
usage specifying the allowed usages of the image view that, by
default, takes the value of the corresponding usage parameter
specified in VkImageCreateInfo at image creation time.
The implicit usage can be overridden by adding a
VkImageViewUsageCreateInfo structure to the pNext chain, but the
view usage must be a subset of the image usage.
If image has a depth-stencil format and was created with a
VkImageStencilUsageCreateInfo structure included in the pNext
chain of VkImageCreateInfo, the usage is calculated based on the
subresource.aspectMask provided:
-
If
aspectMaskincludes onlyVK_IMAGE_ASPECT_STENCIL_BIT, the implicitusageis equal to VkImageStencilUsageCreateInfo::stencilUsage. -
If
aspectMaskincludes onlyVK_IMAGE_ASPECT_DEPTH_BIT, the implicitusageis equal to VkImageCreateInfo::usage. -
If both aspects are included in
aspectMask, the implicitusageis equal to the intersection of VkImageCreateInfo::usageand VkImageStencilUsageCreateInfo::stencilUsage.
If image is a 3D image, its Z range can be restricted to a subset by
adding a VkImageViewSlicedCreateInfoEXT to the pNext chain.
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
flag,
and if the format of the image is not multi-planar
format can be different from the image’s format, but if
image was created without the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and
they are not equal they must be compatible.
Image format compatibility is defined in the
Format Compatibility Classes section.
Views of compatible formats will have the same mapping between texel
coordinates and memory locations irrespective of the format, with only
the interpretation of the bit pattern changing.
If image was created with a multi-planar format, and the image view’s aspectMask is one of
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or
VK_IMAGE_ASPECT_PLANE_2_BIT, the view’s aspect mask is considered to
be equivalent to VK_IMAGE_ASPECT_COLOR_BIT when used as a framebuffer
attachment.
|
Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating-point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating-point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point. |
If image was created with the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format
must be compatible with the image’s format as described above; or must
be an uncompressed format, in which case it must be
size-compatible with the image’s format.
In this case, the resulting image view’s texel dimensions equal the
dimensions of the selected mip level divided by the compressed texel block
size and rounded up.
The VkComponentMapping components member describes a remapping
from components of the image to components of the vector returned by shader
image instructions.
This remapping must be the identity swizzle for storage image descriptors,
input attachment descriptors,
framebuffer attachments, and any VkImageView used with a combined
image sampler that enables sampler Y′CBCR conversion.
If the image view is to be used with a sampler which supports
sampler Y′CBCR conversion, an identically
defined object of type VkSamplerYcbcrConversion to that used to
create the sampler must be passed to vkCreateImageView in a
VkSamplerYcbcrConversionInfo included in the pNext chain of
VkImageViewCreateInfo.
Conversely, if a VkSamplerYcbcrConversion object is passed to
vkCreateImageView, an identically defined
VkSamplerYcbcrConversion object must be used when sampling the image.
If the image has a multi-planar format,
subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, and
usage includes VK_IMAGE_USAGE_SAMPLED_BIT, then the format
must be identical to the image format and the sampler to be used with
the image view must enable sampler Y′CBCR conversion.
When such an image is used in a video coding operation, the sampler Y′CBCR conversion has no effect.
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
and the image has a multi-planar format, and if
subresourceRange.aspectMask is VK_IMAGE_ASPECT_PLANE_0_BIT,
VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT,
format must be compatible with the
corresponding plane of the image, and the sampler to be used with the image
view must not enable sampler Y′CBCR conversion.
The width and height of the single-plane image view must be
derived from the multi-planar image’s dimensions in the manner listed for
plane compatibility for the plane.
Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the components of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.
| Image View Type | Compatible Image Types |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Bits which can be set in VkImageViewCreateInfo::flags,
specifying additional parameters of an image view, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageViewCreateFlagBits {
// Provided by VK_EXT_fragment_density_map
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT = 0x00000001,
// Provided by VK_EXT_descriptor_buffer
VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000004,
// Provided by VK_EXT_fragment_density_map2
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT = 0x00000002,
} VkImageViewCreateFlagBits;-
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXTspecifies that the fragment density map will be read by device duringVK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT -
VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXTspecifies that the fragment density map will be read by the host during vkEndCommandBuffer for the primary command buffer that the render pass is recorded into -
VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the image view can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageViewCreateFlags;VkImageViewCreateFlags is a bitmask type for setting a mask of zero or
more VkImageViewCreateFlagBits.
The set of usages for the created image view can be restricted compared to
the parent image’s usage flags by adding a
VkImageViewUsageCreateInfo structure to the pNext chain of
VkImageViewCreateInfo.
The VkImageViewUsageCreateInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageViewUsageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags usage;
} VkImageViewUsageCreateInfo;or the equivalent
// Provided by VK_KHR_maintenance2
typedef VkImageViewUsageCreateInfo VkImageViewUsageCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
usageis a bitmask of VkImageUsageFlagBits specifying allowed usages of the image view.
When this structure is chained to VkImageViewCreateInfo the
usage field overrides the implicit usage parameter inherited
from image creation time and its value is used instead for the purposes of
determining the valid usage conditions of VkImageViewCreateInfo.
The range of 3D slices for the created image view can be restricted to a
subset of the parent image’s Z range by adding a
VkImageViewSlicedCreateInfoEXT structure to the pNext chain of
VkImageViewCreateInfo.
The VkImageViewSlicedCreateInfoEXT structure is defined as:
// Provided by VK_EXT_image_sliced_view_of_3d
typedef struct VkImageViewSlicedCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t sliceOffset;
uint32_t sliceCount;
} VkImageViewSlicedCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
sliceOffsetis the Z-offset for the first 3D slice accessible to the image view. -
sliceCountis the number of 3D slices accessible to the image view.
When this structure is chained to VkImageViewCreateInfo the
sliceOffset field is treated as a Z-offset for the sliced view and
sliceCount specifies the range.
Shader accesses using a Z coordinate of 0 will access the depth slice
corresponding to sliceOffset in the image, and in a shader, the
maximum in-bounds Z coordinate for the view is sliceCount - 1.
A sliced 3D view must only be used with a single mip level.
The slice coordinates are integer coordinates within the
subresourceRange.baseMipLevel used to create the image view.
The effective view depth is equal to extent.depth used to create the
image for this view adjusted by subresourceRange.baseMipLevel as
specified in Image Mip Level Sizing.
Shader access to this image view is only affected by
VkImageViewSlicedCreateInfoEXT if it uses a descriptor of type
VK_DESCRIPTOR_TYPE_STORAGE_IMAGE.
For access using any other descriptor type, the contents of
VkImageViewSlicedCreateInfoEXT are ignored; instead, sliceOffset
is treated as being equal to 0, and sliceCount is treated as being
equal to VK_REMAINING_3D_SLICES_EXT.
VK_REMAINING_3D_SLICES_EXT is a special constant value used for
VkImageViewSlicedCreateInfoEXT::sliceCount to indicate that all
remaining 3D slices in an image after the first slice offset specified
should be included in the view.
#define VK_REMAINING_3D_SLICES_EXT (~0U)The VkImageSubresourceRange structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceRange {
VkImageAspectFlags aspectMask;
uint32_t baseMipLevel;
uint32_t levelCount;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceRange;-
aspectMaskis a bitmask of VkImageAspectFlagBits specifying which aspect(s) of the image are included in the view. -
baseMipLevelis the first mipmap level accessible to the view. -
levelCountis the number of mipmap levels (starting frombaseMipLevel) accessible to the view. -
baseArrayLayeris the first array layer accessible to the view. -
layerCountis the number of array layers (starting frombaseArrayLayer) accessible to the view.
The number of mipmap levels and array layers must be a subset of the image
subresources in the image.
If an application wants to use all mip levels or layers in an image after
the baseMipLevel or baseArrayLayer, it can set levelCount
and layerCount to the special values VK_REMAINING_MIP_LEVELS and
VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip
levels or layers.
For cube and cube array image views, the layers of the image view starting
at baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z,
-Z.
For cube arrays, each set of six sequential layers is a single cube, so the
number of cube maps in a cube map array view is layerCount / 6, and
image array layer (baseArrayLayer + i) is face index
(i mod 6) of cube i / 6.
If the number of layers in the view, whether set explicitly in
layerCount or implied by VK_REMAINING_ARRAY_LAYERS, is not a
multiple of 6, the last cube map in the array must not be accessed.
aspectMask must be only VK_IMAGE_ASPECT_COLOR_BIT,
VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT if
format is a color, depth-only or stencil-only format,
respectively, except if format is a multi-planar format.
If using a depth/stencil format with both depth and stencil components,
aspectMask must include at least one of
VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT, and
can include both.
When the VkImageSubresourceRange structure is used to select a subset
of the slices of a 3D image’s mip level in order to create a 2D or 2D array
image view of a 3D image created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, baseArrayLayer and
layerCount specify the first slice index and the number of slices to
include in the created image view.
Such an image view can be used as a framebuffer attachment that refers only
to the specified range of slices of the selected mip level.
However, any layout transitions performed on such an attachment view during
a render pass instance still apply to the entire subresource referenced
which includes all the slices of the selected mip level.
When using an image view of a depth/stencil image to populate a descriptor
set (e.g. for sampling in the shader, or for use as an input attachment),
the aspectMask must only include one bit, which selects whether the
image view is used for depth reads (i.e. using a floating-point sampler or
input attachment in the shader) or stencil reads (i.e. using an unsigned
integer sampler or input attachment in the shader).
When an image view of a depth/stencil image is used as a depth/stencil
framebuffer attachment, the aspectMask is ignored and both depth and
stencil image subresources are used.
When creating a VkImageView, if sampler Y′CBCR conversion is enabled in the sampler, the aspectMask of a
subresourceRange used by the VkImageView must be
VK_IMAGE_ASPECT_COLOR_BIT.
When creating a VkImageView, if sampler Y′CBCR conversion is not
enabled in the sampler and the image format is multi-planar format, the image must have been created with
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the aspectMask of the
VkImageView’s subresourceRange must be
VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or
VK_IMAGE_ASPECT_PLANE_2_BIT.
Bits which can be set in an aspect mask to specify aspects of an image for purposes such as identifying a subresource, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageAspectFlagBits {
VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040,
// Provided by VK_VERSION_1_3
VK_IMAGE_ASPECT_NONE = 0,
// Provided by VK_EXT_image_drm_format_modifier
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x00000080,
// Provided by VK_EXT_image_drm_format_modifier
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x00000100,
// Provided by VK_EXT_image_drm_format_modifier
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x00000200,
// Provided by VK_EXT_image_drm_format_modifier
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x00000400,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_IMAGE_ASPECT_PLANE_0_BIT_KHR = VK_IMAGE_ASPECT_PLANE_0_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_IMAGE_ASPECT_PLANE_1_BIT_KHR = VK_IMAGE_ASPECT_PLANE_1_BIT,
// Provided by VK_KHR_sampler_ycbcr_conversion
VK_IMAGE_ASPECT_PLANE_2_BIT_KHR = VK_IMAGE_ASPECT_PLANE_2_BIT,
// Provided by VK_KHR_maintenance4
VK_IMAGE_ASPECT_NONE_KHR = VK_IMAGE_ASPECT_NONE,
} VkImageAspectFlagBits;-
VK_IMAGE_ASPECT_NONEspecifies no image aspect, or the image aspect is not applicable. -
VK_IMAGE_ASPECT_COLOR_BITspecifies the color aspect. -
VK_IMAGE_ASPECT_DEPTH_BITspecifies the depth aspect. -
VK_IMAGE_ASPECT_STENCIL_BITspecifies the stencil aspect. -
VK_IMAGE_ASPECT_METADATA_BITspecifies the metadata aspect used for sparse resource operations. -
VK_IMAGE_ASPECT_PLANE_0_BITspecifies plane 0 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_1_BITspecifies plane 1 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_2_BITspecifies plane 2 of a multi-planar image format. -
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXTspecifies memory plane 0. -
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXTspecifies memory plane 1. -
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXTspecifies memory plane 2. -
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXTspecifies memory plane 3.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageAspectFlags;VkImageAspectFlags is a bitmask type for setting a mask of zero or
more VkImageAspectFlagBits.
The VkComponentMapping structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkComponentMapping {
VkComponentSwizzle r;
VkComponentSwizzle g;
VkComponentSwizzle b;
VkComponentSwizzle a;
} VkComponentMapping;-
ris a VkComponentSwizzle specifying the component value placed in the R component of the output vector. -
gis a VkComponentSwizzle specifying the component value placed in the G component of the output vector. -
bis a VkComponentSwizzle specifying the component value placed in the B component of the output vector. -
ais a VkComponentSwizzle specifying the component value placed in the A component of the output vector.
Possible values of the members of VkComponentMapping, specifying the component values placed in each component of the output vector, are:
// Provided by VK_VERSION_1_0
typedef enum VkComponentSwizzle {
VK_COMPONENT_SWIZZLE_IDENTITY = 0,
VK_COMPONENT_SWIZZLE_ZERO = 1,
VK_COMPONENT_SWIZZLE_ONE = 2,
VK_COMPONENT_SWIZZLE_R = 3,
VK_COMPONENT_SWIZZLE_G = 4,
VK_COMPONENT_SWIZZLE_B = 5,
VK_COMPONENT_SWIZZLE_A = 6,
} VkComponentSwizzle;-
VK_COMPONENT_SWIZZLE_IDENTITYspecifies that the component is set to the identity swizzle. -
VK_COMPONENT_SWIZZLE_ZEROspecifies that the component is set to zero. -
VK_COMPONENT_SWIZZLE_ONEspecifies that the component is set to either 1 or 1.0, depending on whether the type of the image view format is integer or floating-point respectively, as determined by the Format Definition section for each VkFormat. -
VK_COMPONENT_SWIZZLE_Rspecifies that the component is set to the value of the R component of the image. -
VK_COMPONENT_SWIZZLE_Gspecifies that the component is set to the value of the G component of the image. -
VK_COMPONENT_SWIZZLE_Bspecifies that the component is set to the value of the B component of the image. -
VK_COMPONENT_SWIZZLE_Aspecifies that the component is set to the value of the A component of the image.
Setting the identity swizzle on a component is equivalent to setting the identity mapping on that component. That is:
| Component | Identity Mapping |
|---|---|
|
|
|
|
|
|
|
|
If the pNext chain includes a VkImageViewASTCDecodeModeEXT
structure, then that structure includes a parameter specifying the decode
mode for image views using ASTC compressed formats.
The VkImageViewASTCDecodeModeEXT structure is defined as:
// Provided by VK_EXT_astc_decode_mode
typedef struct VkImageViewASTCDecodeModeEXT {
VkStructureType sType;
const void* pNext;
VkFormat decodeMode;
} VkImageViewASTCDecodeModeEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
decodeModeis the intermediate format used to decode ASTC compressed formats.
If format uses sRGB encoding then the decodeMode has no effect.
If the pNext chain includes a
VkImageViewSampleWeightCreateInfoQCOM structure, then that structure
includes a parameter specifying the parameters for weight image views used
in weight image sampling.
The VkImageViewSampleWeightCreateInfoQCOM structure is defined as:
// Provided by VK_QCOM_image_processing
typedef struct VkImageViewSampleWeightCreateInfoQCOM {
VkStructureType sType;
const void* pNext;
VkOffset2D filterCenter;
VkExtent2D filterSize;
uint32_t numPhases;
} VkImageViewSampleWeightCreateInfoQCOM;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
filterCenteris a VkOffset2D describing the location of the weight filter origin. -
filterSizeis a VkExtent2D specifying weight filter dimensions. -
numPhasesis number of sub-pixel filter phases.
The filterCenter specifies the origin or center of the filter kernel,
as described in Weight Sampling Operation.
The numPhases describes the number of sub-pixel filter phases as
described in Weight Sampling Phases.
To destroy an image view, call:
// Provided by VK_VERSION_1_0
void vkDestroyImageView(
VkDevice device,
VkImageView imageView,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the image view. -
imageViewis the image view to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
To get the handle for an image view, call:
// Provided by VK_NVX_image_view_handle
uint32_t vkGetImageViewHandleNVX(
VkDevice device,
const VkImageViewHandleInfoNVX* pInfo);-
deviceis the logical device that owns the image view. -
pInfodescribes the image view to query and type of handle.
To get the 64-bit handle for an image view, call:
// Provided by VK_NVX_image_view_handle
uint64_t vkGetImageViewHandle64NVX(
VkDevice device,
const VkImageViewHandleInfoNVX* pInfo);-
deviceis the logical device that owns the image view. -
pInfodescribes the image view to query and type of handle.
The VkImageViewHandleInfoNVX structure is defined as:
// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewHandleInfoNVX {
VkStructureType sType;
const void* pNext;
VkImageView imageView;
VkDescriptorType descriptorType;
VkSampler sampler;
} VkImageViewHandleInfoNVX;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewis the image view to query. -
descriptorTypeis the type of descriptor for which to query a handle. -
sampleris the sampler to combine with the image view when generating the handle.
To get the device address for an image view, call:
// Provided by VK_NVX_image_view_handle
VkResult vkGetImageViewAddressNVX(
VkDevice device,
VkImageView imageView,
VkImageViewAddressPropertiesNVX* pProperties);-
deviceis the logical device that owns the image view. -
imageViewis a handle to the image view. -
pPropertiescontains the device address and size when the call returns.
The VkImageViewAddressPropertiesNVX structure is defined as:
// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewAddressPropertiesNVX {
VkStructureType sType;
void* pNext;
VkDeviceAddress deviceAddress;
VkDeviceSize size;
} VkImageViewAddressPropertiesNVX;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceAddressis the device address of the image view. -
sizeis the size in bytes of the image view device memory.
Image View Format Features
Valid uses of a VkImageView may depend on the image view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the value of VkFormatProperties3::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2extension is not supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the union of the value of VkFormatProperties::linearTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageViewCreateInfo::format, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BITif the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageReadWithoutFormatfeature is enabled. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageWriteWithoutFormatfeature is enabled.
-
-
If Vulkan 1.3 is supported or the
VK_KHR_format_feature_flags2extension is supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_OPTIMAL, but without an Android hardware buffer external format, or a QNX Screen buffer external format, then the image view’s set of format features is the value of VkFormatProperties::optimalTilingFeaturesor VkFormatProperties3::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties or vkGetPhysicalDeviceImageFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
If Vulkan 1.3 is not supported and the
VK_KHR_format_feature_flags2extension is not supported, and VkImageViewCreateInfo::imagewas created withVK_IMAGE_TILING_OPTIMAL, but without an Android hardware buffer external format, or a QNX Screen buffer external format, then the image view’s set of format features is the union of the value of VkFormatProperties::optimalTilingFeaturesfound by calling vkGetPhysicalDeviceFormatProperties on the sameformatas VkImageViewCreateInfo::format, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BITif the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageReadWithoutFormatis enabled. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BITif the format is one of the extended storage formats and theshaderStorageImageWriteWithoutFormatis enabled.
-
-
If VkImageViewCreateInfo::
imagewas created with an Android hardware buffer external format, then the image views’s set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeaturesfound by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the VkImageViewCreateInfo::imageis bound. -
If VkImageViewCreateInfo::
imagewas created with a QNX Screen buffer external format, then the image views’s set of format features is the value of VkScreenBufferFormatPropertiesQNX::formatFeaturesfound by calling vkGetScreenBufferPropertiesQNX on the QNX Screen buffer that was imported to the VkDeviceMemory to which the VkImageViewCreateInfo::imageis bound. -
If VkImageViewCreateInfo::
imagewas created with a chained VkBufferCollectionImageCreateInfoFUCHSIA, then the image view’s set of format features is the value of VkBufferCollectionPropertiesFUCHSIA::formatFeaturesfound by calling vkGetBufferCollectionPropertiesFUCHSIA on the buffer collection passed as VkBufferCollectionImageCreateInfoFUCHSIA::collectionwhen the image was created. -
If VkImageViewCreateInfo::
imagewas created withVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then:-
The image’s DRM format modifier is the value of VkImageDrmFormatModifierPropertiesEXT::
drmFormatModifierfound by calling vkGetImageDrmFormatModifierPropertiesEXT. -
Let VkDrmFormatModifierPropertiesListEXT::
pDrmFormatModifierPropertiesbe the array found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformatas VkImageViewCreateInfo::format. -
Let
VkDrmFormatModifierPropertiesEXT propbe the array element whosedrmFormatModifiermember is the value of the image’s DRM format modifier. -
Then the image view’s set of format features is
prop::drmFormatModifierTilingFeatures.
-
The VkImageViewMinLodCreateInfoEXT structure is defined as:
// Provided by VK_EXT_image_view_min_lod
typedef struct VkImageViewMinLodCreateInfoEXT {
VkStructureType sType;
const void* pNext;
float minLod;
} VkImageViewMinLodCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
minLodis the value to clamp the minimum LOD accessible by this VkImageView.
If the pNext chain includes a VkImageViewMinLodCreateInfoEXT
structure, then that structure includes a parameter specifying a value to
clamp the minimum LOD value during Image Level(s) Selection, Texel Gathering and
Integer Texel Coordinate Operations.
If the image view contains VkImageViewMinLodCreateInfoEXT and it is
used as part of a sampling operation:
minLodFloatimageView = minLod
otherwise:
minLodFloatimageView = 0.0
An integer variant of this parameter is also defined for sampling operations which access integer mipmap levels:
minLodIntegerimageView = ⌊minLodFloatimageView⌋
Acceleration Structures
Acceleration structures are opaque data structures that are built by the implementation to more efficiently perform spatial queries on the provided geometric data. For these extensions, an acceleration structure is either a top-level acceleration structure containing a set of bottom-level acceleration structures or a bottom-level acceleration structure containing either a set of axis-aligned bounding boxes for custom geometry or a set of triangles.
Each instance in the top-level acceleration structure contains a reference to a bottom-level acceleration structure as well as an instance transform plus information required to index into the shader bindings. The top-level acceleration structure is what is bound to the acceleration descriptor, for example to trace inside the shader in the ray tracing pipeline.
Acceleration structures for the VK_KHR_acceleration_structure
extension are represented by VkAccelerationStructureKHR handles:
// Provided by VK_KHR_acceleration_structure
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureKHR)To create an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCreateAccelerationStructureKHR(
VkDevice device,
const VkAccelerationStructureCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkAccelerationStructureKHR* pAccelerationStructure);-
deviceis the logical device that creates the acceleration structure object. -
pCreateInfois a pointer to a VkAccelerationStructureCreateInfoKHR structure containing parameters affecting creation of the acceleration structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pAccelerationStructureis a pointer to aVkAccelerationStructureKHRhandle in which the resulting acceleration structure object is returned.
Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of VkAccelerationStructureCreateInfoKHR.
The acceleration structure data is stored in the object referred to by
VkAccelerationStructureCreateInfoKHR::buffer.
Once memory has been bound to that buffer, it must be populated by
acceleration structure build or acceleration structure copy commands such as
vkCmdBuildAccelerationStructuresKHR,
vkBuildAccelerationStructuresKHR,
vkCmdCopyAccelerationStructureKHR, and
vkCopyAccelerationStructureKHR.
|
The expected usage for a trace capture/replay tool is that it will serialize
and later deserialize the acceleration structure data using acceleration
structure copy commands.
During capture the tool will use
vkCopyAccelerationStructureToMemoryKHR or
vkCmdCopyAccelerationStructureToMemoryKHR with a |
|
Memory does not need to be bound to the underlying buffer when vkCreateAccelerationStructureKHR is called. |
The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of ray traversal.
The VkAccelerationStructureCreateInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureCreateFlagsKHR createFlags;
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize size;
VkAccelerationStructureTypeKHR type;
VkDeviceAddress deviceAddress;
} VkAccelerationStructureCreateInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
createFlagsis a bitmask of VkAccelerationStructureCreateFlagBitsKHR specifying additional creation parameters of the acceleration structure. -
bufferis the buffer on which the acceleration structure will be stored. -
offsetis an offset in bytes from the base address of the buffer at which the acceleration structure will be stored, and must be a multiple of256. -
sizeis the size required for the acceleration structure. -
typeis a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure that will be created. -
deviceAddressis the device address requested for the acceleration structure, obtained from vkGetAccelerationStructureDeviceAddressKHR, if theaccelerationStructureCaptureReplayfeature is being used. IfdeviceAddressis zero, no specific address is requested.
Applications should avoid creating acceleration structures with
application-provided addresses and implementation-provided addresses in the
same process, to reduce the likelihood of
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors.
|
The expected usage for this is that a trace capture/replay tool will add the
Implementations are expected to separate such buffers in the GPU address
space so normal allocations will avoid using these addresses.
Applications and tools should avoid mixing application-provided and
implementation-provided addresses for buffers created with
|
Applications should create an acceleration structure with a specific
VkAccelerationStructureTypeKHR other than
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.
|
|
If the acceleration structure will be the target of a build operation, the required size for an acceleration structure can be queried with vkGetAccelerationStructureBuildSizesKHR. If the acceleration structure is going to be the target of a compacting copy, vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR can be used to obtain the compacted size required.
If the acceleration structure will be the target of a build operation with
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must include
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in createFlags
and include VkAccelerationStructureMotionInfoNV as an extension
structure in pNext with the number of instances as metadata for the
object.
The VkAccelerationStructureMotionInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMotionInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t maxInstances;
VkAccelerationStructureMotionInfoFlagsNV flags;
} VkAccelerationStructureMotionInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxInstancesis the maximum number of instances that may be used in the motion top-level acceleration structure. -
flagsis 0 and reserved for future use.
// Provided by VK_NV_ray_tracing_motion_blur
typedef VkFlags VkAccelerationStructureMotionInfoFlagsNV;VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting
a mask, but is currently reserved for future use.
To get the build sizes for an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
void vkGetAccelerationStructureBuildSizesKHR(
VkDevice device,
VkAccelerationStructureBuildTypeKHR buildType,
const VkAccelerationStructureBuildGeometryInfoKHR* pBuildInfo,
const uint32_t* pMaxPrimitiveCounts,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);-
deviceis the logical device that will be used for creating the acceleration structure. -
buildTypedefines whether host or device operations (or both) are being queried for. -
pBuildInfois a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure describing parameters of a build operation. -
pMaxPrimitiveCountsis a pointer to an array ofpBuildInfo->geometryCountuint32_tvalues defining the number of primitives built into each geometry. -
pSizeInfois a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and the sizes required for the scratch buffers, given the build parameters.
The srcAccelerationStructure, dstAccelerationStructure, and
mode members of pBuildInfo are ignored.
Any VkDeviceOrHostAddressKHR or VkDeviceOrHostAddressConstKHR
members of pBuildInfo are ignored by this command, except that the
hostAddress member of
VkAccelerationStructureGeometryTrianglesDataKHR::transformData
will be examined to check if it is NULL.
An acceleration structure created with the accelerationStructureSize
returned by this command supports any build or update with a
VkAccelerationStructureBuildGeometryInfoKHR structure and array of
VkAccelerationStructureBuildRangeInfoKHR structures subject to the
following properties:
-
The build command is a host build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
The build command is a device build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
For VkAccelerationStructureBuildGeometryInfoKHR:
-
Its
type, andflagsmembers are equal topBuildInfo->typeandpBuildInfo->flags, respectively. -
geometryCountis less than or equal topBuildInfo->geometryCount. -
For each element of either
pGeometriesorppGeometriesat a given index, itsgeometryTypemember is equal topBuildInfo->geometryType. -
For each element of either
pGeometriesorppGeometriesat a given index, itsflagsmember is equal to the corresponding member of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, thevertexFormatandindexTypemembers ofgeometry.trianglesare equal to the corresponding members of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, themaxVertexmember ofgeometry.trianglesis less than or equal to the corresponding member of the same element inpBuildInfo. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in thetransformDatamember ofgeometry.trianglesis notNULL, the correspondingtransformData.hostAddressparameter inpBuildInfois notNULL.
-
-
For each VkAccelerationStructureBuildRangeInfoKHR corresponding to the VkAccelerationStructureBuildGeometryInfoKHR:
-
Its
primitiveCountmember is less than or equal to the corresponding element ofpMaxPrimitiveCounts. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if thepNextchain contains VkAccelerationStructureTrianglesOpacityMicromapEXT the corresponding member ofpBuildInfoalso contains VkAccelerationStructureTrianglesOpacityMicromapEXT and with an equivalentmicromap. -
For each element of either
pGeometriesorppGeometriesat a given index, with ageometryTypemember equal toVK_GEOMETRY_TYPE_TRIANGLES_KHR, if thepNextchain contains VkAccelerationStructureTrianglesDisplacementMicromapNV the corresponding member ofpBuildInfoalso contains VkAccelerationStructureTrianglesDisplacementMicromapNV and with an equivalentmicromap.
-
Similarly, the updateScratchSize value will support any build command
specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR
mode under the above conditions, and the buildScratchSize value
will support any build command specifying the
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR mode under the
above conditions.
The VkAccelerationStructureBuildSizesInfoKHR structure describes the
required build sizes for an acceleration structure and scratch buffers and
is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildSizesInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceSize accelerationStructureSize;
VkDeviceSize updateScratchSize;
VkDeviceSize buildScratchSize;
} VkAccelerationStructureBuildSizesInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureSizeis the size in bytes required in a VkAccelerationStructureKHR for a build or update operation. -
updateScratchSizeis the size in bytes required in a scratch buffer for an update operation. -
buildScratchSizeis the size in bytes required in a scratch buffer for a build operation.
Acceleration structures for the VK_NV_ray_tracing extension are
represented by the similar VkAccelerationStructureNV handles:
// Provided by VK_NV_ray_tracing
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureNV)To create acceleration structures, call:
// Provided by VK_NV_ray_tracing
VkResult vkCreateAccelerationStructureNV(
VkDevice device,
const VkAccelerationStructureCreateInfoNV* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkAccelerationStructureNV* pAccelerationStructure);-
deviceis the logical device that creates the buffer object. -
pCreateInfois a pointer to a VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pAccelerationStructureis a pointer to a VkAccelerationStructureNV handle in which the resulting acceleration structure object is returned.
Similarly to other objects in Vulkan, the acceleration structure creation
merely creates an object with a specific “shape” as specified by the
information in VkAccelerationStructureInfoNV and compactedSize
in pCreateInfo.
Once memory has been bound to the acceleration structure using vkBindAccelerationStructureMemoryNV, that memory is populated by calls to vkCmdBuildAccelerationStructureNV and vkCmdCopyAccelerationStructureNV.
Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures.
The VkAccelerationStructureCreateInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkDeviceSize compactedSize;
VkAccelerationStructureInfoNV info;
} VkAccelerationStructureCreateInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
compactedSizeis the size from the result of vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy. -
infois the VkAccelerationStructureInfoNV structure specifying further parameters of the created acceleration structure.
The VkAccelerationStructureInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureInfoNV {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureTypeNV type;
VkBuildAccelerationStructureFlagsNV flags;
uint32_t instanceCount;
uint32_t geometryCount;
const VkGeometryNV* pGeometries;
} VkAccelerationStructureInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created. -
flagsis a bitmask of VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure. -
instanceCountspecifies the number of instances that will be in the new acceleration structure. -
geometryCountspecifies the number of geometries that will be in the new acceleration structure. -
pGeometriesis a pointer to an array ofgeometryCountVkGeometryNV structures containing the scene data being passed into the acceleration structure.
VkAccelerationStructureInfoNV contains information that is used both
for acceleration structure creation with
vkCreateAccelerationStructureNV and in combination with the actual
geometric data to build the acceleration structure with
vkCmdBuildAccelerationStructureNV.
Values which can be set in
VkAccelerationStructureCreateInfoKHR::type
or
VkAccelerationStructureInfoNV::type
specifying the type of acceleration structure, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureTypeKHR {
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR = 0,
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR = 1,
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR = 2,
// Provided by VK_NV_ray_tracing
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR,
// Provided by VK_NV_ray_tracing
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR,
} VkAccelerationStructureTypeKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAccelerationStructureTypeKHR VkAccelerationStructureTypeNV;-
VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHRis a top-level acceleration structure containing instance data referring to bottom-level acceleration structures. -
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHRis a bottom-level acceleration structure containing the AABBs or geometry to be intersected. -
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHRis an acceleration structure whose type is determined at build time used for special circumstances. In these cases, the acceleration structure type is not known at creation time, but must be specified at build time as either top or bottom.
Bits which can be set in
VkAccelerationStructureCreateInfoKHR::createFlags, specifying
additional creation parameters for acceleration structures, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCreateFlagBitsKHR {
VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = 0x00000001,
// Provided by VK_EXT_descriptor_buffer
VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000008,
// Provided by VK_NV_ray_tracing_motion_blur
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV = 0x00000004,
} VkAccelerationStructureCreateFlagBitsKHR;-
VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHRspecifies that the acceleration structure’s address can be saved and reused on a subsequent run. -
VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXTspecifies that the acceleration structure can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. -
VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NVspecifies that the acceleration structure will be used with motion information, see VkAccelerationStructureMotionInfoNV for more detail.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkAccelerationStructureCreateFlagsKHR;VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a
mask of zero or more VkAccelerationStructureCreateFlagBitsKHR.
Bits which can be set in
VkAccelerationStructureBuildGeometryInfoKHR::flags
or
VkAccelerationStructureInfoNV::flags
specifying additional parameters for acceleration structure builds, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureFlagBitsKHR {
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR = 0x00000001,
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR = 0x00000002,
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR = 0x00000004,
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR = 0x00000008,
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR = 0x00000010,
// Provided by VK_NV_ray_tracing_motion_blur
VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV = 0x00000020,
// Provided by VK_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT = 0x00000040,
// Provided by VK_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT = 0x00000080,
// Provided by VK_EXT_opacity_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT = 0x00000100,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV = 0x00000200,
#endif
// Provided by VK_KHR_ray_tracing_position_fetch
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR = 0x00000800,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR,
} VkBuildAccelerationStructureFlagBitsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkBuildAccelerationStructureFlagBitsKHR VkBuildAccelerationStructureFlagBitsNV;-
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHRspecifies that the specified acceleration structure can be updated with amodeofVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRin VkAccelerationStructureBuildGeometryInfoKHR or anupdateofVK_TRUEin vkCmdBuildAccelerationStructureNV . For sphere and LSS primitives, only positions and radii may be updated, the provided index buffers and flags must remain unchanged from the initial build. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHRspecifies that the specified acceleration structure can act as the source for a copy acceleration structure command withmodeofVK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHRto produce a compacted acceleration structure. -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHRspecifies that the given acceleration structure build should prioritize trace performance over build time. -
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHRspecifies that the given acceleration structure build should prioritize build time over trace performance. -
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHRspecifies that this acceleration structure should minimize the size of the scratch memory and the final result acceleration structure, potentially at the expense of build time or trace performance. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXTspecifies that the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXTspecifies that the data of the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXTspecifies that the specified acceleration structure may be referenced in an instance withVK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXTset. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHRspecifies that the specified acceleration structure can be used when fetching the vertex and radius positions of a hit LSS or sphere primitive, or vertex positions of a hit triangle. -
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NVspecifies that the displacement micromaps associated with the specified acceleration structure may change with an acceleration structure update.
|
|
|
|
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkBuildAccelerationStructureFlagsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkBuildAccelerationStructureFlagsKHR VkBuildAccelerationStructureFlagsNV;VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a
mask of zero or more VkBuildAccelerationStructureFlagBitsKHR.
The VkGeometryNV structure describes geometry in a bottom-level
acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryNV {
VkStructureType sType;
const void* pNext;
VkGeometryTypeKHR geometryType;
VkGeometryDataNV geometry;
VkGeometryFlagsKHR flags;
} VkGeometryNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
geometryTypespecifies the VkGeometryTypeKHR which this geometry refers to. -
geometrycontains the geometry data as described in VkGeometryDataNV. -
flagshas VkGeometryFlagBitsKHR describing options for this geometry.
Geometry types are specified by VkGeometryTypeKHR, which takes values:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryTypeKHR {
VK_GEOMETRY_TYPE_TRIANGLES_KHR = 0,
VK_GEOMETRY_TYPE_AABBS_KHR = 1,
VK_GEOMETRY_TYPE_INSTANCES_KHR = 2,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_GEOMETRY_TYPE_SPHERES_NV = 1000429004,
// Provided by VK_NV_ray_tracing_linear_swept_spheres
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV = 1000429005,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_TYPE_TRIANGLES_NV = VK_GEOMETRY_TYPE_TRIANGLES_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_TYPE_AABBS_NV = VK_GEOMETRY_TYPE_AABBS_KHR,
} VkGeometryTypeKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryTypeKHR VkGeometryTypeNV;-
VK_GEOMETRY_TYPE_TRIANGLES_KHRspecifies a geometry type consisting of triangles. -
VK_GEOMETRY_TYPE_AABBS_KHRspecifies a geometry type consisting of axis-aligned bounding boxes. -
VK_GEOMETRY_TYPE_INSTANCES_KHRspecifies a geometry type consisting of acceleration structure instances. -
VK_GEOMETRY_TYPE_SPHERES_NVspecifies a geometry type consisting of spheres. -
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NVspecifies a geometry type consisting of linear swept spheres.
Bits specifying additional parameters for geometries in acceleration structure builds, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryFlagBitsKHR {
VK_GEOMETRY_OPAQUE_BIT_KHR = 0x00000001,
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR = 0x00000002,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_OPAQUE_BIT_NV = VK_GEOMETRY_OPAQUE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV = VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR,
} VkGeometryFlagBitsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryFlagBitsKHR VkGeometryFlagBitsNV;-
VK_GEOMETRY_OPAQUE_BIT_KHRspecifies that this geometry does not invoke the any-hit shaders even if present in a hit group. -
VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHRspecifies that the implementation must only call the any-hit shader a single time for each primitive in this geometry. If this bit is absent an implementation may invoke the any-hit shader more than once for this geometry.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryFlagsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryFlagsKHR VkGeometryFlagsNV;VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or
more VkGeometryFlagBitsKHR.
The VkGeometryDataNV structure specifies geometry in a bottom-level
acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryDataNV {
VkGeometryTrianglesNV triangles;
VkGeometryAABBNV aabbs;
} VkGeometryDataNV;-
trianglescontains triangle data if VkGeometryNV::geometryTypeisVK_GEOMETRY_TYPE_TRIANGLES_NV. -
aabbscontains axis-aligned bounding box data if VkGeometryNV::geometryTypeisVK_GEOMETRY_TYPE_AABBS_NV.
The VkGeometryTrianglesNV structure specifies triangle geometry in a
bottom-level acceleration structure and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryTrianglesNV {
VkStructureType sType;
const void* pNext;
VkBuffer vertexData;
VkDeviceSize vertexOffset;
uint32_t vertexCount;
VkDeviceSize vertexStride;
VkFormat vertexFormat;
VkBuffer indexData;
VkDeviceSize indexOffset;
uint32_t indexCount;
VkIndexType indexType;
VkBuffer transformData;
VkDeviceSize transformOffset;
} VkGeometryTrianglesNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexDatais the buffer containing vertex data for this geometry. -
vertexOffsetis the offset in bytes withinvertexDatacontaining vertex data for this geometry. -
vertexCountis the number of valid vertices. -
vertexStrideis the stride in bytes between each vertex. -
vertexFormatis a VkFormat describing the format of each vertex element. -
indexDatais the buffer containing index data for this geometry. -
indexOffsetis the offset in bytes withinindexDatacontaining index data for this geometry. -
indexCountis the number of indices to include in this geometry. -
indexTypeis a VkIndexType describing the format of each index. -
transformDatais an optional buffer containing an VkTransformMatrixNV structure defining a transformation to be applied to this geometry. -
transformOffsetis the offset in bytes intransformDataof the transform information described above.
If indexType is VK_INDEX_TYPE_NONE_NV, then this structure
describes a set of triangles determined by vertexCount.
Otherwise, this structure describes a set of indexed triangles determined by
indexCount.
The VkGeometryAABBNV structure specifies axis-aligned bounding box
geometry in a bottom-level acceleration structure, and is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkGeometryAABBNV {
VkStructureType sType;
const void* pNext;
VkBuffer aabbData;
uint32_t numAABBs;
uint32_t stride;
VkDeviceSize offset;
} VkGeometryAABBNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
aabbDatais the buffer containing axis-aligned bounding box data. -
numAABBsis the number of AABBs in this geometry. -
strideis the stride in bytes between AABBs inaabbData. -
offsetis the offset in bytes of the first AABB inaabbData.
The AABB data in memory is six 32-bit floats consisting of the minimum x, y, and z values followed by the maximum x, y, and z values.
To destroy an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
void vkDestroyAccelerationStructureKHR(
VkDevice device,
VkAccelerationStructureKHR accelerationStructure,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the acceleration structure. -
accelerationStructureis the acceleration structure to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
To destroy an acceleration structure, call:
// Provided by VK_NV_ray_tracing
void vkDestroyAccelerationStructureNV(
VkDevice device,
VkAccelerationStructureNV accelerationStructure,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the buffer. -
accelerationStructureis the acceleration structure to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
An acceleration structure has memory requirements for the structure object itself, scratch space for the build, and scratch space for the update.
Scratch space is allocated as a VkBuffer, so for
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV
and
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV
the pMemoryRequirements->alignment and
pMemoryRequirements->memoryTypeBits values returned by this call must
be filled with zero, and should be ignored by the application.
To query the memory requirements, call:
// Provided by VK_NV_ray_tracing
void vkGetAccelerationStructureMemoryRequirementsNV(
VkDevice device,
const VkAccelerationStructureMemoryRequirementsInfoNV* pInfo,
VkMemoryRequirements2KHR* pMemoryRequirements);-
deviceis the logical device on which the acceleration structure was created. -
pInfois a pointer to a VkAccelerationStructureMemoryRequirementsInfoNV structure specifying the acceleration structure to get memory requirements for. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2KHR structure in which the requested acceleration structure memory requirements are returned.
The VkAccelerationStructureMemoryRequirementsInfoNV structure is
defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureMemoryRequirementsInfoNV {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureMemoryRequirementsTypeNV type;
VkAccelerationStructureNV accelerationStructure;
} VkAccelerationStructureMemoryRequirementsInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeselects the type of memory requirement being queried.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NVreturns the memory requirements for the object itself.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NVreturns the memory requirements for the scratch memory when doing a build.VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NVreturns the memory requirements for the scratch memory when doing an update. -
accelerationStructureis the acceleration structure to be queried for memory requirements.
Possible values of type in
VkAccelerationStructureMemoryRequirementsInfoNV are:,
// Provided by VK_NV_ray_tracing
typedef enum VkAccelerationStructureMemoryRequirementsTypeNV {
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV = 0,
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV = 1,
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV = 2,
} VkAccelerationStructureMemoryRequirementsTypeNV;-
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NVrequests the memory requirement for theVkAccelerationStructureNVbacking store. -
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NVrequests the memory requirement for scratch space during the initial build. -
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NVrequests the memory requirement for scratch space during an update.
Possible values of buildType in
vkGetAccelerationStructureBuildSizesKHR are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureBuildTypeKHR {
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR = 0,
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR = 1,
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR = 2,
} VkAccelerationStructureBuildTypeKHR;-
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHRrequests the memory requirement for operations performed by the host. -
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHRrequests the memory requirement for operations performed by the device. -
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHRrequests the memory requirement for operations performed by either the host, or the device.
To attach memory to one or more acceleration structures at a time, call:
// Provided by VK_NV_ray_tracing
VkResult vkBindAccelerationStructureMemoryNV(
VkDevice device,
uint32_t bindInfoCount,
const VkBindAccelerationStructureMemoryInfoNV* pBindInfos);-
deviceis the logical device that owns the acceleration structures and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindAccelerationStructureMemoryInfoNV structures describing acceleration structures and memory to bind.
The VkBindAccelerationStructureMemoryInfoNV structure is defined as:
// Provided by VK_NV_ray_tracing
typedef struct VkBindAccelerationStructureMemoryInfoNV {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureNV accelerationStructure;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
} VkBindAccelerationStructureMemoryInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructureis the acceleration structure to be attached to memory. -
memoryis aVkDeviceMemoryobject describing the device memory to attach. -
memoryOffsetis the start offset of the region of memory that is to be bound to the acceleration structure. The number of bytes returned in the VkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified acceleration structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices.
To allow constructing geometry instances with device code if desired, we need to be able to query an opaque handle for an acceleration structure. This handle is a value of 8 bytes. To get this handle, call:
// Provided by VK_NV_ray_tracing
VkResult vkGetAccelerationStructureHandleNV(
VkDevice device,
VkAccelerationStructureNV accelerationStructure,
size_t dataSize,
void* pData);-
deviceis the logical device that owns the acceleration structures. -
accelerationStructureis the acceleration structure. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to an application-allocated buffer where the results will be written.
To query the 64-bit device address for an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkDeviceAddress vkGetAccelerationStructureDeviceAddressKHR(
VkDevice device,
const VkAccelerationStructureDeviceAddressInfoKHR* pInfo);-
deviceis the logical device that the acceleration structure was created on. -
pInfois a pointer to a VkAccelerationStructureDeviceAddressInfoKHR structure specifying the acceleration structure to retrieve an address for.
The 64-bit return value is an address of the acceleration structure, which can be used for device and shader operations that involve acceleration structures, such as ray traversal and acceleration structure building.
If the acceleration structure was created with a non-zero value of
VkAccelerationStructureCreateInfoKHR::deviceAddress, the return
value will be the same address.
If the acceleration structure was created with a type of
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must
be consistent with the relative offset to other acceleration structures with
type VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with
the same VkBuffer.
That is, the difference in returned addresses between the two must be the
same as the difference in offsets provided at acceleration structure
creation.
The returned address must be aligned to 256 bytes.
|
The acceleration structure device address may be different from the buffer
device address corresponding to the acceleration structure’s start offset in
its storage buffer for acceleration structure types other than
|
The VkAccelerationStructureDeviceAddressInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureDeviceAddressInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR accelerationStructure;
} VkAccelerationStructureDeviceAddressInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
accelerationStructurespecifies the acceleration structure whose address is being queried.
Micromaps
Micromaps are opaque data structures that are built by the implementation to encode sub-triangle data to be included in an acceleration structure.
Micromaps are represented by VkMicromapEXT handles:
// Provided by VK_EXT_opacity_micromap
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkMicromapEXT)To create a micromap, call:
// Provided by VK_EXT_opacity_micromap
VkResult vkCreateMicromapEXT(
VkDevice device,
const VkMicromapCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkMicromapEXT* pMicromap);-
deviceis the logical device that creates the acceleration structure object. -
pCreateInfois a pointer to a VkMicromapCreateInfoEXT structure containing parameters affecting creation of the micromap. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter. -
pMicromapis a pointer to a VkMicromapEXT handle in which the resulting micromap object is returned.
Similar to other objects in Vulkan, the micromap creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into a micromap is determined by the parameters of VkMicromapCreateInfoEXT.
The micromap data is stored in the object referred to by
VkMicromapCreateInfoEXT::buffer.
Once memory has been bound to that buffer, it must be populated by micromap
build or micromap copy commands such as vkCmdBuildMicromapsEXT,
vkBuildMicromapsEXT, vkCmdCopyMicromapEXT, and
vkCopyMicromapEXT.
|
The expected usage for a trace capture/replay tool is that it will serialize
and later deserialize the micromap data using micromap copy commands.
During capture the tool will use vkCopyMicromapToMemoryEXT or
vkCmdCopyMicromapToMemoryEXT with a |
The input buffers passed to micromap build commands will be referenced by the implementation for the duration of the command. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure.
The VkMicromapCreateInfoEXT structure is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkMicromapCreateFlagsEXT createFlags;
VkBuffer buffer;
VkDeviceSize offset;
VkDeviceSize size;
VkMicromapTypeEXT type;
VkDeviceAddress deviceAddress;
} VkMicromapCreateInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
createFlagsis a bitmask of VkMicromapCreateFlagBitsEXT specifying additional creation parameters of the micromap. -
bufferis the buffer on which the micromap will be stored. -
offsetis an offset in bytes from the base address of the buffer at which the micromap will be stored, and must be a multiple of256. -
sizeis the size required for the micromap. -
typeis a VkMicromapTypeEXT value specifying the type of micromap that will be created. -
deviceAddressis the device address requested for the micromap if themicromapCaptureReplayfeature is being used.
If deviceAddress is zero, no specific address is requested.
If deviceAddress is not zero, deviceAddress must be an address
retrieved from an identically created micromap on the same implementation.
The micromap must also be placed on an identically created buffer and
at the same offset.
Applications should avoid creating micromaps with application-provided
addresses and implementation-provided addresses in the same process, to
reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
errors.
|
The expected usage for this is that a trace capture/replay tool will add the
Implementations are expected to separate such buffers in the GPU address
space so normal allocations will avoid using these addresses.
Applications and tools should avoid mixing application-provided and
implementation-provided addresses for buffers created with
|
If the micromap will be the target of a build operation, the required size for a micromap can be queried with vkGetMicromapBuildSizesEXT.
To get the build sizes for a micromap, call:
// Provided by VK_EXT_opacity_micromap
void vkGetMicromapBuildSizesEXT(
VkDevice device,
VkAccelerationStructureBuildTypeKHR buildType,
const VkMicromapBuildInfoEXT* pBuildInfo,
VkMicromapBuildSizesInfoEXT* pSizeInfo);-
deviceis the logical device that will be used for creating the micromap. -
buildTypedefines whether host or device operations (or both) are being queried for. -
pBuildInfois a pointer to a VkMicromapBuildInfoEXT structure describing parameters of a build operation. -
pSizeInfois a pointer to a VkMicromapBuildSizesInfoEXT structure which returns the size required for a micromap and the sizes required for the scratch buffers, given the build parameters.
The dstMicromap and mode members of pBuildInfo are
ignored.
Any VkDeviceOrHostAddressKHR members of pBuildInfo are ignored
by this command.
A micromap created with the micromapSize returned by this command
supports any build with a VkMicromapBuildInfoEXT structure subject to
the following properties:
-
The build command is a host build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
The build command is a device build command, and
buildTypeisVK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHRorVK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR -
-
Its
type, andflagsmembers are equal topBuildInfo->typeandpBuildInfo->flags, respectively. -
The sum of usage information in either
pUsageCountsorppUsageCountsis equal to the sum of usage information in eitherpBuildInfo->pUsageCountsorpBuildInfo->ppUsageCounts.
-
Similarly, the buildScratchSize value will support any build command
specifying the VK_BUILD_MICROMAP_MODE_BUILD_EXT mode under the
above conditions.
The VkMicromapBuildSizesInfoEXT structure describes the required build
sizes for a micromap and scratch buffers and is defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildSizesInfoEXT {
VkStructureType sType;
const void* pNext;
VkDeviceSize micromapSize;
VkDeviceSize buildScratchSize;
VkBool32 discardable;
} VkMicromapBuildSizesInfoEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
micromapSizeis the size in bytes required in a VkMicromapEXT for a build or update operation. -
buildScratchSizeis the size in bytes required in a scratch buffer for a build operation. -
discardableindicates whether or not the micromap object may be destroyed after an acceleration structure build or update. A false value means that acceleration structures built with this micromap may contain references to the data contained therein, and the application must not destroy the micromap until ray traversal has concluded. A true value means that the information in the micromap will be copied by value into the acceleration structure, and the micromap may be destroyed after the acceleration structure build concludes.
Values which can be set in VkMicromapCreateInfoEXT::type
specifying the type of micromap, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapTypeEXT {
VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT = 0,
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_NV_displacement_micromap
VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV = 1000397000,
#endif
} VkMicromapTypeEXT;-
VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXTis a micromap containing data to control the opacity of a triangle. -
VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NVis a micromap containing data to control the displacement of subtriangles within a triangle.
Bits which can be set in VkMicromapCreateInfoEXT::createFlags,
specifying additional creation parameters for micromaps, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapCreateFlagBitsEXT {
VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = 0x00000001,
} VkMicromapCreateFlagBitsEXT;-
VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXTspecifies that the micromap’s address can be saved and reused on a subsequent run.
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkMicromapCreateFlagsEXT;VkMicromapCreateFlagsEXT is a bitmask type for setting a mask of zero
or more VkMicromapCreateFlagBitsEXT.
Bits which can be set in VkMicromapBuildInfoEXT::flags
specifying additional parameters for micromap builds, are:
// Provided by VK_EXT_opacity_micromap
typedef enum VkBuildMicromapFlagBitsEXT {
VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXT = 0x00000001,
VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXT = 0x00000002,
VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT = 0x00000004,
} VkBuildMicromapFlagBitsEXT;-
VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXTspecifies that the given micromap build should prioritize trace performance over build time. -
VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXTspecifies that the given micromap build should prioritize build time over trace performance.
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkBuildMicromapFlagsEXT;VkBuildMicromapFlagsEXT is a bitmask type for setting a mask of zero
or more VkBuildMicromapFlagBitsEXT.
To destroy a micromap, call:
// Provided by VK_EXT_opacity_micromap
void vkDestroyMicromapEXT(
VkDevice device,
VkMicromapEXT micromap,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that destroys the micromap. -
micromapis the micromap to destroy. -
pAllocatorcontrols host memory allocation as described in the Memory Allocation chapter.
Resource Memory Association
Resources are initially created as virtual allocations with no backing memory. Device memory is allocated separately (see Device Memory) and then associated with the resource. This association is done differently for sparse and non-sparse resources.
Resources created with any of the sparse creation flags are considered sparse resources. Resources created without these flags are non-sparse. The details on resource memory association for sparse resources is described in Sparse Resources.
Non-sparse resources must be bound completely and contiguously to a single
VkDeviceMemory object before the resource is passed as a parameter to
any of the following operations:
-
creating image or buffer views
-
updating descriptor sets
-
recording commands in a command buffer
Once bound, the memory binding is immutable for the lifetime of the resource.
In a logical device representing more than one physical device, buffer and image resources exist on all physical devices but can be bound to memory differently on each. Each such replicated resource is an instance of the resource. For sparse resources, each instance can be bound to memory arbitrarily differently. For non-sparse resources, each instance can either be bound to the local or a peer instance of the memory, or for images can be bound to rectangular regions from the local and/or peer instances. When a resource is used in a descriptor set, each physical device interprets the descriptor according to its own instance’s binding to memory.
|
There are no new copy commands to transfer data between physical devices. Instead, an application can create a resource with a peer mapping and use it as the source or destination of a transfer command executed by a single physical device to copy the data from one physical device to another. |
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_0
void vkGetBufferMemoryRequirements(
VkDevice device,
VkBuffer buffer,
VkMemoryRequirements* pMemoryRequirements);-
deviceis the logical device that owns the buffer. -
bufferis the buffer to query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for an image resource which is not
created with the VK_IMAGE_CREATE_DISJOINT_BIT flag set, call:
// Provided by VK_VERSION_1_0
void vkGetImageMemoryRequirements(
VkDevice device,
VkImage image,
VkMemoryRequirements* pMemoryRequirements);-
deviceis the logical device that owns the image. -
imageis the image to query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements structure in which the memory requirements of the image object are returned.
The VkMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkMemoryRequirements {
VkDeviceSize size;
VkDeviceSize alignment;
uint32_t memoryTypeBits;
} VkMemoryRequirements;-
sizeis the size, in bytes, of the memory allocation required for the resource. -
alignmentis the alignment, in bytes, of the offset within the allocation required for the resource. -
memoryTypeBitsis a bitmask and contains one bit set for every supported memory type for the resource. Bitiis set if and only if the memory typeiin theVkPhysicalDeviceMemoryPropertiesstructure for the physical device is supported for the resource.
The precise size of images that will be bound to external Android hardware
buffer memory is unknown until the memory has been imported or allocated, so
applications must not call vkGetImageMemoryRequirements or
vkGetImageMemoryRequirements2 with such a VkImage before it has
been bound to memory.
For this reason, applications also must not call
vkGetDeviceImageMemoryRequirements with a VkImageCreateInfo
describing an external Android hardware buffer.
When importing Android hardware buffer memory, the allocationSize can
be determined by calling vkGetAndroidHardwareBufferPropertiesANDROID.
When allocating new memory for a VkImage that can be exported to an
Android hardware buffer, the memory’s allocationSize must be zero;
the actual size will be determined by the dedicated image’s parameters.
After the memory has been allocated, the amount of space allocated from the
memory’s heap can be obtained by getting the image’s memory requirements or
by calling vkGetAndroidHardwareBufferPropertiesANDROID with the
Android hardware buffer exported from the memory.
When allocating new memory for a VkBuffer that can be exported to an Android hardware buffer an application may still call vkGetBufferMemoryRequirements or vkGetBufferMemoryRequirements2 with VkBuffer before it has been bound to memory.
The value of size has no meaning and should be ignored if the
resource being queried was created with any of the following external memory
handle types:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT
The implementation guarantees certain properties about the memory requirements returned by vkGetBufferMemoryRequirements2, vkGetImageMemoryRequirements2, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:
-
The
memoryTypeBitsmember always contains at least one bit set. -
If
bufferis aVkBuffernot created with theVK_BUFFER_CREATE_SPARSE_BINDING_BITorVK_BUFFER_CREATE_PROTECTED_BITbits set, or ifimageis a linear image that was not created with theVK_IMAGE_CREATE_PROTECTED_BITbit set, then thememoryTypeBitsmember always contains at least one bit set corresponding to aVkMemoryTypewith apropertyFlagsthat has both theVK_MEMORY_PROPERTY_HOST_VISIBLE_BITbit and theVK_MEMORY_PROPERTY_HOST_COHERENT_BITbit set. In other words, mappable coherent memory can always be attached to these objects. -
If
bufferwas created with VkExternalMemoryBufferCreateInfo::handleTypesset to0orimagewas created with VkExternalMemoryImageCreateInfo::handleTypesset to0, thememoryTypeBitsmember always contains at least one bit set corresponding to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_DEVICE_LOCAL_BITbit set. -
The
memoryTypeBitsmember is identical for allVkBufferobjects created with the same value for theflagsandusagemembers in the VkBufferCreateInfo structure and thehandleTypesmember of the VkExternalMemoryBufferCreateInfo structure passed to vkCreateBuffer. Further, ifusage1andusage2of type VkBufferUsageFlags are such that the bits set inusage2are a subset of the bits set inusage1, and they have the sameflagsand VkExternalMemoryBufferCreateInfo::handleTypes, then the bits set inmemoryTypeBitsreturned forusage1must be a subset of the bits set inmemoryTypeBitsreturned forusage2, for all values offlags. -
The
alignmentmember is a power of two. -
The
alignmentmember is identical for allVkBufferobjects created with the same combination of values for theusageandflagsmembers in the VkBufferCreateInfo structure passed to vkCreateBuffer. -
If the
maintenance4feature is enabled, then thealignmentmember is identical for allVkImageobjects created with the same combination of values for theflags,imageType,format,extent,mipLevels,arrayLayers,samples,tilingandusagemembers in the VkImageCreateInfo structure passed to vkCreateImage. -
The
alignmentmember satisfies the buffer descriptor offset alignment requirements associated with theVkBuffer’susage:-
If
usageincludedVK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BITorVK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minTexelBufferOffsetAlignment. -
If
usageincludedVK_BUFFER_USAGE_UNIFORM_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minUniformBufferOffsetAlignment. -
If
usageincludedVK_BUFFER_USAGE_STORAGE_BUFFER_BIT,alignmentmust be an integer multiple ofVkPhysicalDeviceLimits::minStorageBufferOffsetAlignment.
-
-
For images created with a color format, the
memoryTypeBitsmember is identical for allVkImageobjects created with the same combination of values for thetilingmember, theVK_IMAGE_CREATE_SPARSE_BINDING_BITbit andVK_IMAGE_CREATE_PROTECTED_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember, theVK_IMAGE_USAGE_HOST_TRANSFER_BITbit of theusagemember if the VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirementsproperty isVK_FALSE,handleTypesmember of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITof theusagemember in the VkImageCreateInfo structure passed to vkCreateImage. -
For images created with a depth/stencil format, the
memoryTypeBitsmember is identical for allVkImageobjects created with the same combination of values for theformatmember, thetilingmember, theVK_IMAGE_CREATE_SPARSE_BINDING_BITbit andVK_IMAGE_CREATE_PROTECTED_BITbit of theflagsmember, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BITbit of theflagsmember, theVK_IMAGE_USAGE_HOST_TRANSFER_BITbit of theusagemember if the VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirementsproperty isVK_FALSE,handleTypesmember of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITof theusagemember in the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkImage, thememoryTypeBitsmember must not refer to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITbit set if theimagedid not haveVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BITbit set in theusagemember of the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkBuffer, thememoryTypeBitsmember must not refer to aVkMemoryTypewith apropertyFlagsthat has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BITbit set.The implication of this requirement is that lazily allocated memory is disallowed for buffers in all cases.
-
The
sizemember is identical for allVkBufferobjects created with the same combination of creation parameters specified in VkBufferCreateInfo and itspNextchain. -
The
sizemember is identical for allVkImageobjects created with the same combination of creation parameters specified in VkImageCreateInfo and itspNextchain.This, however, does not imply that they interpret the contents of the bound memory identically with each other. That additional guarantee, however, can be explicitly requested using
VK_IMAGE_CREATE_ALIAS_BIT. -
If the
maintenance4feature is enabled, these additional guarantees apply:-
For a
VkBuffer, thesizememory requirement is never greater than that of anotherVkBuffercreated with a greater or equalsizespecified in VkBufferCreateInfo, all other creation parameters being identical. -
For a
VkBuffer, thesizememory requirement is never greater than the result of aligning VkBufferCreateInfo::sizewith thealignmentmemory requirement. -
For a VkImage, the
sizememory requirement is never greater than that of another VkImage created with a greater or equal value in each ofextent.width,extent.height, andextent.depth; all other creation parameters being identical. -
The memory requirements returned by vkGetDeviceBufferMemoryRequirements are identical to those that would be returned by vkGetBufferMemoryRequirements2 if it were called with a
VkBuffercreated with the same VkBufferCreateInfo values. -
The memory requirements returned by vkGetDeviceImageMemoryRequirements are identical to those that would be returned by vkGetImageMemoryRequirements2 if it were called with a
VkImagecreated with the same VkImageCreateInfo values.
-
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_1
void vkGetBufferMemoryRequirements2(
VkDevice device,
const VkBufferMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);or the equivalent command
// Provided by VK_KHR_get_memory_requirements2
void vkGetBufferMemoryRequirements2KHR(
VkDevice device,
const VkBufferMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);-
deviceis the logical device that owns the buffer. -
pInfois a pointer to a VkBufferMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for a buffer resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceBufferMemoryRequirements(
VkDevice device,
const VkDeviceBufferMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);or the equivalent command
// Provided by VK_KHR_maintenance4
void vkGetDeviceBufferMemoryRequirementsKHR(
VkDevice device,
const VkDeviceBufferMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);-
deviceis the logical device intended to own the buffer. -
pInfois a pointer to a VkDeviceBufferMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
The VkBufferMemoryRequirementsInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBufferMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkBufferMemoryRequirementsInfo2;or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkBufferMemoryRequirementsInfo2 VkBufferMemoryRequirementsInfo2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis the buffer to query.
The VkDeviceBufferMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceBufferMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkBufferCreateInfo* pCreateInfo;
} VkDeviceBufferMemoryRequirements;or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkDeviceBufferMemoryRequirements VkDeviceBufferMemoryRequirementsKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer to query.
To determine the memory requirements for an image resource, call:
// Provided by VK_VERSION_1_1
void vkGetImageMemoryRequirements2(
VkDevice device,
const VkImageMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);or the equivalent command
// Provided by VK_KHR_get_memory_requirements2
void vkGetImageMemoryRequirements2KHR(
VkDevice device,
const VkImageMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);-
deviceis the logical device that owns the image. -
pInfois a pointer to a VkImageMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
To determine the memory requirements for an image resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceImageMemoryRequirements(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);or the equivalent command
// Provided by VK_KHR_maintenance4
void vkGetDeviceImageMemoryRequirementsKHR(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);-
deviceis the logical device intended to own the image. -
pInfois a pointer to a VkDeviceImageMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirementsis a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
The VkImageMemoryRequirementsInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkImage image;
} VkImageMemoryRequirementsInfo2;or the equivalent
// Provided by VK_KHR_get_memory_requirements2
typedef VkImageMemoryRequirementsInfo2 VkImageMemoryRequirementsInfo2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis the image to query.
The VkDeviceImageMemoryRequirements structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceImageMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkImageCreateInfo* pCreateInfo;
VkImageAspectFlagBits planeAspect;
} VkDeviceImageMemoryRequirements;or the equivalent
// Provided by VK_KHR_maintenance4
typedef VkDeviceImageMemoryRequirements VkDeviceImageMemoryRequirementsKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pCreateInfois a pointer to a VkImageCreateInfo structure containing parameters affecting creation of the image to query. -
planeAspectis a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query. This parameter is ignored unlesspCreateInfo->tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, orpCreateInfo->flagshasVK_IMAGE_CREATE_DISJOINT_BITset.
To determine the memory requirements for a plane of a disjoint image, add a
VkImagePlaneMemoryRequirementsInfo structure to the pNext chain
of the VkImageMemoryRequirementsInfo2 structure.
The VkImagePlaneMemoryRequirementsInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImagePlaneMemoryRequirementsInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkImagePlaneMemoryRequirementsInfo;or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkImagePlaneMemoryRequirementsInfo VkImagePlaneMemoryRequirementsInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planeAspectis a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query.
The VkMemoryRequirements2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryRequirements2 {
VkStructureType sType;
void* pNext;
VkMemoryRequirements memoryRequirements;
} VkMemoryRequirements2;or the equivalent
// Provided by VK_KHR_get_memory_requirements2, VK_NV_ray_tracing with VK_KHR_get_memory_requirements2 or VK_VERSION_1_1
typedef VkMemoryRequirements2 VkMemoryRequirements2KHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
memoryRequirementsis a VkMemoryRequirements structure describing the memory requirements of the resource.
The VkMemoryDedicatedRequirements structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedRequirements {
VkStructureType sType;
void* pNext;
VkBool32 prefersDedicatedAllocation;
VkBool32 requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;or the equivalent
// Provided by VK_KHR_dedicated_allocation
typedef VkMemoryDedicatedRequirements VkMemoryDedicatedRequirementsKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
prefersDedicatedAllocationspecifies that the implementation would prefer a dedicated allocation for this resource. The application is still free to suballocate the resource but it may get better performance if a dedicated allocation is used. -
requiresDedicatedAllocationspecifies that a dedicated allocation is required for this resource.
To determine the dedicated allocation requirements of a buffer or image
resource, add a VkMemoryDedicatedRequirements structure to the
pNext chain of the VkMemoryRequirements2 structure passed as the
pMemoryRequirements parameter of vkGetBufferMemoryRequirements2
or vkGetImageMemoryRequirements2, respectively.
Constraints on the values returned for buffer resources are:
-
requiresDedicatedAllocationmay beVK_TRUEif thepNextchain of VkBufferCreateInfo for the call tovkCreateBufferused to create the buffer being queried included a VkExternalMemoryBufferCreateInfo structure, and any of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypesrequires dedicated allocation, as reported by vkGetPhysicalDeviceExternalBufferProperties inVkExternalBufferProperties::externalMemoryProperties.externalMemoryFeatures. Otherwise,requiresDedicatedAllocationwill beVK_FALSE. -
When the implementation sets
requiresDedicatedAllocationtoVK_TRUE, it must also setprefersDedicatedAllocationtoVK_TRUE. -
If
VK_BUFFER_CREATE_SPARSE_BINDING_BITwas set in VkBufferCreateInfo::flagswhenbufferwas created, then bothprefersDedicatedAllocationandrequiresDedicatedAllocationwill beVK_FALSE.
Constraints on the values returned for image resources are:
-
requiresDedicatedAllocationmay beVK_TRUEif thepNextchain of VkImageCreateInfo for the call to vkCreateImage used to create the image being queried included a VkExternalMemoryImageCreateInfo structure, and any of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypesrequires dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 inVkExternalImageFormatProperties::externalMemoryProperties.externalMemoryFeatures. -
requiresDedicatedAllocationmay beVK_TRUEif the image’s tiling isVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. -
requiresDedicatedAllocationwill otherwise beVK_FALSE -
If
VK_IMAGE_CREATE_SPARSE_BINDING_BITwas set in VkImageCreateInfo::flagswhenimagewas created, then bothprefersDedicatedAllocationandrequiresDedicatedAllocationwill beVK_FALSE.
To attach memory to a buffer object, call:
// Provided by VK_VERSION_1_0
VkResult vkBindBufferMemory(
VkDevice device,
VkBuffer buffer,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);-
deviceis the logical device that owns the buffer and memory. -
bufferis the buffer to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified buffer.
vkBindBufferMemory is equivalent to passing the same parameters
through VkBindBufferMemoryInfo to vkBindBufferMemory2.
To attach memory to buffer objects for one or more buffers at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindBufferMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);or the equivalent command
// Provided by VK_KHR_bind_memory2
VkResult vkBindBufferMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);-
deviceis the logical device that owns the buffers and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array ofbindInfoCountVkBindBufferMemoryInfo structures describing buffers and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
If the maintenance6 feature is enabled,
this command must attempt to perform all of the memory binding operations
described by pBindInfos, and must not early exit on the first
failure.
If any of the memory binding operations described by pBindInfos fail,
the VkResult returned by this command must be the return value of any
one of the memory binding operations which did not return VK_SUCCESS.
|
If the Applications should destroy these buffers. |
VkBindBufferMemoryInfo contains members corresponding to the
parameters of vkBindBufferMemory.
The VkBindBufferMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryInfo {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindBufferMemoryInfo;or the equivalent
// Provided by VK_KHR_bind_memory2
typedef VkBindBufferMemoryInfo VkBindBufferMemoryInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
bufferis the buffer to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified buffer.
The VkBindBufferMemoryDeviceGroupInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
} VkBindBufferMemoryDeviceGroupInfo;or the equivalent
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
typedef VkBindBufferMemoryDeviceGroupInfo VkBindBufferMemoryDeviceGroupInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices.
If the pNext chain of VkBindBufferMemoryInfo includes a
VkBindBufferMemoryDeviceGroupInfo structure, then that structure
determines how memory is bound to buffers across multiple devices in a
device group.
If deviceIndexCount is greater than zero, then on device index i
the buffer is attached to the instance of memory on the physical
device with device index pDeviceIndices[i].
If deviceIndexCount is zero and memory comes from a memory heap
with the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of memory.
If deviceIndexCount is zero and memory comes from a memory heap
without the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as
if pDeviceIndices contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
The VkBindMemoryStatus structure is defined as:
// Provided by VK_VERSION_1_4
typedef struct VkBindMemoryStatus {
VkStructureType sType;
const void* pNext;
VkResult* pResult;
} VkBindMemoryStatus;or the equivalent
// Provided by VK_KHR_maintenance6
typedef VkBindMemoryStatus VkBindMemoryStatusKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pResultis a pointer to aVkResultvalue.
If the pNext chain of VkBindBufferMemoryInfo or
VkBindImageMemoryInfo includes a VkBindMemoryStatus structure,
then the VkBindMemoryStatus::pResult will be populated with a
value describing the result of the corresponding memory binding operation.
To attach memory to a VkImage object created without the
VK_IMAGE_CREATE_DISJOINT_BIT set, call:
// Provided by VK_VERSION_1_0
VkResult vkBindImageMemory(
VkDevice device,
VkImage image,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);-
deviceis the logical device that owns the image and memory. -
imageis the image. -
memoryis the VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the image. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified image.
vkBindImageMemory is equivalent to passing the same parameters through
VkBindImageMemoryInfo to vkBindImageMemory2.
To attach memory to image objects for one or more images at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindImageMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);or the equivalent command
// Provided by VK_KHR_bind_memory2
VkResult vkBindImageMemory2KHR(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);-
deviceis the logical device that owns the images and memory. -
bindInfoCountis the number of elements inpBindInfos. -
pBindInfosis a pointer to an array of VkBindImageMemoryInfo structures, describing images and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
If the maintenance6 feature is enabled,
this command must attempt to perform all of the memory binding operations
described by pBindInfos, and must not early exit on the first
failure.
If any of the memory binding operations described by pBindInfos fail,
the VkResult returned by this command must be the return value of any
one of the memory binding operations which did not return VK_SUCCESS.
|
If the Applications should destroy these images. |
VkBindImageMemoryInfo contains members corresponding to the parameters
of vkBindImageMemory.
The VkBindImageMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImage image;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindImageMemoryInfo;or the equivalent
// Provided by VK_KHR_bind_memory2
typedef VkBindImageMemoryInfo VkBindImageMemoryInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageis the image to be attached to memory. -
memoryis a VkDeviceMemory object describing the device memory to attach. -
memoryOffsetis the start offset of the region ofmemorywhich is to be bound to the image. The number of bytes returned in theVkMemoryRequirements::sizemember inmemory, starting frommemoryOffsetbytes, will be bound to the specified image.
The VkBindImageMemoryDeviceGroupInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
uint32_t splitInstanceBindRegionCount;
const VkRect2D* pSplitInstanceBindRegions;
} VkBindImageMemoryDeviceGroupInfo;or the equivalent
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
typedef VkBindImageMemoryDeviceGroupInfo VkBindImageMemoryDeviceGroupInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
deviceIndexCountis the number of elements inpDeviceIndices. -
pDeviceIndicesis a pointer to an array of device indices. -
splitInstanceBindRegionCountis the number of elements inpSplitInstanceBindRegions. -
pSplitInstanceBindRegionsis a pointer to an array of VkRect2D structures describing which regions of the image are attached to each instance of memory.
If the pNext chain of VkBindImageMemoryInfo includes a
VkBindImageMemoryDeviceGroupInfo structure, then that structure
determines how memory is bound to images across multiple devices in a device
group.
If deviceIndexCount is greater than zero, then on device index i
image is attached to the instance of the memory on the physical device
with device index pDeviceIndices[i].
Let N be the number of physical devices in the logical device.
If splitInstanceBindRegionCount is greater than zero, then
pSplitInstanceBindRegions is a pointer to an array of N2
rectangles, where the image region specified by the rectangle at element
i*N+j in resource instance i is bound to the memory instance
j.
The blocks of the memory that are bound to each sparse image block region
use an offset in memory, relative to memoryOffset, computed as if the
whole image was being bound to a contiguous range of memory.
In other words, horizontally adjacent image blocks use consecutive blocks of
memory, vertically adjacent image blocks are separated by the number of
bytes per block multiplied by the width in blocks of image, and the
block at (0,0) corresponds to memory starting at memoryOffset.
If splitInstanceBindRegionCount and deviceIndexCount are zero
and the memory comes from a memory heap with the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of the memory.
If splitInstanceBindRegionCount and deviceIndexCount are zero
and the memory comes from a memory heap without the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
pDeviceIndices contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
If the pNext chain of VkBindImageMemoryInfo includes a
VkBindImageMemorySwapchainInfoKHR structure, then that structure
includes a swapchain handle and image index indicating that the image will
be bound to memory from that swapchain.
The VkBindImageMemorySwapchainInfoKHR structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkBindImageMemorySwapchainInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint32_t imageIndex;
} VkBindImageMemorySwapchainInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
swapchainis VK_NULL_HANDLE or a swapchain handle. -
imageIndexis an image index withinswapchain.
If swapchain is not NULL, the swapchain and imageIndex
are used to determine the memory that the image is bound to, instead of
memory and memoryOffset.
Memory can be bound to a swapchain and use the pDeviceIndices or
pSplitInstanceBindRegions members of
VkBindImageMemoryDeviceGroupInfo.
In order to bind planes of a disjoint image, add a
VkBindImagePlaneMemoryInfo structure to the pNext chain of
VkBindImageMemoryInfo.
The VkBindImagePlaneMemoryInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImagePlaneMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkBindImagePlaneMemoryInfo;or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkBindImagePlaneMemoryInfo VkBindImagePlaneMemoryInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
planeAspectis aVkImageAspectFlagBitsvalue specifying the aspect of the disjoint image plane to bind.
The implementation-dependent limit bufferImageGranularity specifies a page-like granularity at which
linear and non-linear resources must be placed in adjacent memory locations
to avoid aliasing.
Two resources which do not satisfy this granularity requirement are said to
alias.
bufferImageGranularity is specified in bytes, and must be a power of
two.
Implementations which do not impose a granularity restriction may report a
bufferImageGranularity value of one.
|
Despite its name, |
Given resourceA at the lower memory offset and resourceB at the higher
memory offset in the same VkDeviceMemory object, where one resource is
linear and the other is non-linear (as defined in the
Glossary), and the following:
resourceA.end = resourceA.memoryOffset + resourceA.size - 1
resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1)
resourceB.start = resourceB.memoryOffset
resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1)The following property must hold:
resourceA.endPage < resourceB.startPageThat is, the end of the first resource (A) and the beginning of the second
resource (B) must be on separate “pages” of size
bufferImageGranularity.
bufferImageGranularity may be different than the physical page size
of the memory heap.
This restriction is only needed when a linear resource and a non-linear
resource are adjacent in memory and will be used simultaneously.
The memory ranges of adjacent resources can be closer than
bufferImageGranularity, provided they meet the alignment
requirement for the objects in question.
Sparse block size in bytes and sparse image and buffer memory alignments
must all be multiples of the bufferImageGranularity.
Therefore, memory bound to sparse resources naturally satisfies the
bufferImageGranularity.
Resource Sharing Mode
Buffer and image objects are created with a sharing mode controlling how they can be accessed from queues. The supported sharing modes are:
// Provided by VK_VERSION_1_0
typedef enum VkSharingMode {
VK_SHARING_MODE_EXCLUSIVE = 0,
VK_SHARING_MODE_CONCURRENT = 1,
} VkSharingMode;-
VK_SHARING_MODE_EXCLUSIVEspecifies that access to any range or image subresource of the object will be exclusive to a single queue family at a time. -
VK_SHARING_MODE_CONCURRENTspecifies that concurrent access to any range or image subresource of the object from multiple queue families is supported.
|
|
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_EXCLUSIVE must only be accessed by queues in the
queue family that has ownership of the resource.
Upon creation, such resources are not owned by any queue family; ownership
is implicitly acquired upon first use within a queue.
Once a resource using VK_SHARING_MODE_EXCLUSIVE is owned by some queue
family, the application must perform a
queue family ownership transfer to make
the memory contents of a range or image subresource accessible to a
different queue family.
|
Images still require a layout transition from
|
A queue family can take ownership of an image subresource or buffer range
of a resource created with VK_SHARING_MODE_EXCLUSIVE, without an
ownership transfer, in the same way as for a resource that was just created;
however, taking ownership in this way has the effect that the contents of
the image subresource or buffer range are undefined.
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_CONCURRENT must only be accessed by queues from the
queue families specified through the queueFamilyIndexCount and
pQueueFamilyIndices members of the corresponding create info
structures.
External Resource Sharing
Resources should only be accessed in the Vulkan instance that has exclusive
ownership of their underlying memory.
Only one Vulkan instance has exclusive ownership of a resource’s underlying
memory at a given time, regardless of whether the resource was created using
VK_SHARING_MODE_EXCLUSIVE or VK_SHARING_MODE_CONCURRENT.
Applications can transfer ownership of a resource’s underlying memory only
if the memory has been imported from or exported to another instance or
external API using external memory handles.
The semantics for transferring ownership outside of the instance are similar
to those used for transferring ownership of VK_SHARING_MODE_EXCLUSIVE
resources between queues, and is also accomplished using
VkBufferMemoryBarrier or VkImageMemoryBarrier operations.
To make the contents of the underlying memory accessible in the destination
instance or API, applications must
-
Release exclusive ownership from the source instance or API.
-
Ensure the release operation has completed using semaphores or fences.
-
Acquire exclusive ownership in the destination instance or API
Unlike queue family ownership transfers, the destination instance or API is
not specified explicitly when releasing ownership, nor is the source
instance or API specified when acquiring ownership.
Instead, the image or memory barrier’s dstQueueFamilyIndex or
srcQueueFamilyIndex parameters are set to the reserved queue family
index VK_QUEUE_FAMILY_EXTERNAL
or VK_QUEUE_FAMILY_FOREIGN_EXT
to represent the external destination or source respectively.
Binding a resource to a memory object shared between multiple Vulkan instances or other APIs does not change the ownership of the underlying memory. The first entity to access the resource implicitly acquires ownership. An entity can also implicitly take ownership from another entity in the same way without an explicit ownership transfer. However, taking ownership in this way has the effect that the contents of the underlying memory are undefined.
Accessing a resource backed by memory that is owned by a particular instance
or API has the same semantics as accessing a VK_SHARING_MODE_EXCLUSIVE
resource, with one exception: Implementations must ensure layout
transitions performed on one member of a set of identical subresources of
identical images that alias the same range of an underlying memory object
affect the layout of all the subresources in the set.
As a corollary, writes to any image subresources in such a set must not
make the contents of memory used by other subresources in the set
undefined.
An application can define the content of a subresource of one image by
performing device writes to an identical subresource of another image
provided both images are bound to the same region of external memory.
Applications may also add resources to such a set after the content of the
existing set members has been defined without making the content undefined
by creating a new image with the initial layout
VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of
external memory as the existing images.
|
Because layout transitions apply to all identical images aliasing the same region of external memory, the actual layout of the memory backing a new image as well as an existing image with defined content will not be undefined. Such an image is not usable until it acquires ownership of its memory from the existing owner. Therefore, the layout specified as part of this transition will be the true initial layout of the image. The undefined layout specified when creating it is a placeholder to simplify valid usage requirements. |
Memory Aliasing
A range of a VkDeviceMemory allocation is aliased if it is bound to
multiple resources simultaneously, as described below, via
vkBindImageMemory, vkBindBufferMemory,
vkBindAccelerationStructureMemoryNV,
via sparse memory bindings,
or by binding the memory to resources in multiple Vulkan instances or
external APIs using external memory handle export and import mechanisms.
Consider two resources, resourceA and resourceB, bound respectively to
memory rangeA and rangeB.
Let paddedRangeA and paddedRangeB be, respectively, rangeA and
rangeB aligned to bufferImageGranularity.
If the resources are both linear or both non-linear (as defined in the
Glossary), then the resources alias the
memory in the intersection of rangeA and rangeB.
If one resource is linear and the other is non-linear, then the resources
alias the memory in the intersection of paddedRangeA and paddedRangeB.
Applications can alias memory, but use of multiple aliases is subject to several constraints.
|
Memory aliasing can be useful to reduce the total device memory footprint of an application, if some large resources are used for disjoint periods of time. |
When a non-linear,
non-VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased
range, all image subresources of the image overlap the range.
When a linear image is bound to an aliased range, the image subresources
that (according to the image’s advertised layout) include bytes from the
aliased range overlap the range.
When a VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image
blocks bound to an aliased range, only image subresources including those
sparse image blocks overlap the range, and when the memory bound to the
image’s mip tail overlaps an aliased range all image subresources in the mip
tail overlap the range.
Buffers, and linear image subresources in either the
VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL
layouts, are host-accessible subresources.
That is, the host has a well-defined addressing scheme to interpret the
contents, and thus the layout of the data in memory can be consistently
interpreted across aliases if each of those aliases is a host-accessible
subresource.
Non-linear images, and linear image subresources in other layouts, are not
host-accessible.
If two aliases are both host-accessible, then they interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
If two aliases are both images that were created with identical creation
parameters, both were created with the VK_IMAGE_CREATE_ALIAS_BIT flag
set, and both are bound identically to memory
except for VkBindImageMemoryDeviceGroupInfo::pDeviceIndices and
VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions,
then they interpret the contents of the memory in consistent ways, and data
written to one alias can be read by the other alias.
Additionally, if an individual plane of a multi-planar image and a single-plane image alias the same memory, then they also interpret the contents of the memory in consistent ways under the same conditions, but with the following modifications:
-
Both must have been created with the
VK_IMAGE_CREATE_DISJOINT_BITflag. -
The single-plane image must have a VkFormat that is equivalent to that of the multi-planar image’s individual plane.
-
The single-plane image and the individual plane of the multi-planar image must be bound identically to memory except for VkBindImageMemoryDeviceGroupInfo::
pDeviceIndicesand VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions. -
The
widthandheightof the single-plane image are derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the aliased plane. -
If either image’s
tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must be linear. -
All other creation parameters must be identical
Aliases created by binding the same memory to resources in multiple Vulkan instances or external APIs using external memory handle export and import mechanisms interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
Otherwise, the aliases interpret the contents of the memory differently, and writes via one alias make the contents of memory partially or completely undefined to the other alias. If the first alias is a host-accessible subresource, then the bytes affected are those written by the memory operations according to its addressing scheme. If the first alias is not host-accessible, then the bytes affected are those overlapped by the image subresources that were written. If the second alias is a host-accessible subresource, the affected bytes become undefined. If the second alias is not host-accessible, all sparse image blocks (for sparse partially-resident images) or all image subresources (for non-sparse image and fully resident sparse images) that overlap the affected bytes become undefined.
If any image subresources are made undefined due to writes to an alias,
then each of those image subresources must have its layout transitioned
from VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or
from VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by
the host.
If any sparse blocks of a sparse image have been made undefined, then only
the image subresources containing them must be transitioned.
Use of an overlapping range by two aliases must be separated by a memory dependency using the appropriate access types if at least one of those uses performs writes, whether the aliases interpret memory consistently or not. If buffer or image memory barriers are used, the scope of the barrier must contain the entire range and/or set of image subresources that overlap.
If two aliasing image views are used in the same framebuffer, then the
render pass must declare the attachments using the
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, and
follow the other rules listed in that section.
|
Memory recycled via an application suballocator (i.e. without freeing and reallocating the memory objects) is not substantially different from memory aliasing. However, a suballocator usually waits on a fence before recycling a region of memory, and signaling a fence involves sufficient implicit dependencies to satisfy all the above requirements. |
Resource Memory Overlap
Applications can safely access resources concurrently via separate device and host operations as long as the accessed memory locations are guaranteed to not overlap, as defined in Memory Location, and the operation, resource, and access are otherwise independently valid.
Some operations have alignment requirements or access ambiguous
memory locations, so the semantics of a
particular operation should be considered when determining the overlap.
Such requirements will be described alongside the operation.
Operations between host and device when using non-coherent memory are
aligned to nonCoherentAtomSize, as
defined by vkFlushMappedMemoryRanges and
vkInvalidateMappedMemoryRanges.
|
The intent is that buffers (or linear images) can be accessed concurrently, even when they share cache lines, but otherwise do not access the same memory range. The concept of a device cache line size is not exposed in the memory model. |
Buffer Collections
Fuchsia’s FIDL-based Sysmem service interoperates with Vulkan via the
VK_FUCHSIA_buffer_collection extension.
A buffer collection is a set of one or more buffers which were allocated together as a group and which all have the same properties. These properties describe the buffers' internal representation, such as its dimensions and memory layout. This ensures that all of the buffers can be used interchangeably by tasks that require swapping among multiple buffers, such as double-buffered graphics rendering.
On Fuchsia, the Sysmem service uses buffer collections as a core construct in its design.
Buffer collections are represented by VkBufferCollectionFUCHSIA
handles:
// Provided by VK_FUCHSIA_buffer_collection
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferCollectionFUCHSIA)Definitions
-
FIDL - Fuchsia Interface Definition Language. The declarative language used to define FIDL interprocess communication interfaces on Fuchsia. FIDL files use the
fidlextension. FIDL is also used to refer to the services defined by interfaces declared in the FIDL language -
Sysmem - The FIDL service that facilitates optimal buffer sharing and reuse on Fuchsia
-
client - Any participant of the buffer collection e.g. the Vulkan application
-
token - A
zx_handle_tZircon channel object that allows participation in the buffer collection
Platform Initialization for Buffer Collections
To initialize a buffer collection on Fuchsia:
-
Connect to the Sysmem service to initialize a Sysmem allocator
-
Create an initial buffer collection token using the Sysmem allocator
-
Duplicate the token for each participant beyond the initiator
-
See the Sysmem Overview and fuchsia.sysmem FIDL documentation on fuchsia.dev for more detailed information
Create the Buffer Collection
To create a VkBufferCollectionFUCHSIA for Vulkan to participate in the buffer collection:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkCreateBufferCollectionFUCHSIA(
VkDevice device,
const VkBufferCollectionCreateInfoFUCHSIA* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBufferCollectionFUCHSIA* pCollection);-
deviceis the logical device that creates theVkBufferCollectionFUCHSIA -
pCreateInfois a pointer to a VkBufferCollectionCreateInfoFUCHSIA structure containing parameters affecting creation of the buffer collection -
pAllocatoris a pointer to a VkAllocationCallbacks structure controlling host memory allocation as described in the Memory Allocation chapter -
pBufferCollectionis a pointer to a VkBufferCollectionFUCHSIA handle in which the resulting buffer collection object is returned
The VkBufferCollectionCreateInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
zx_handle_t collectionToken;
} VkBufferCollectionCreateInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
collectionTokenis azx_handle_tcontaining the Sysmem client’s buffer collection token
Set the Constraints
Set Image-Based Buffer Collection Constraints
Setting the constraints on the buffer collection initiates the format negotiation and allocation of the buffer collection. To set the constraints on a VkImage buffer collection, call:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionImageConstraintsFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkImageConstraintsInfoFUCHSIA* pImageConstraintsInfo);-
deviceis the logical device -
collectionis the VkBufferCollectionFUCHSIA handle -
pImageConstraintsInfois a pointer to a VkImageConstraintsInfoFUCHSIA structure
vkSetBufferCollectionImageConstraintsFUCHSIA may fail if
pImageConstraintsInfo->formatConstraintsCount is larger than the
implementation-defined limit.
If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will
return VK_ERROR_INITIALIZATION_FAILED.
vkSetBufferCollectionImageConstraintsFUCHSIA may fail if the
implementation does not support any of the formats described by the
pImageConstraintsInfo structure.
If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will
return VK_ERROR_FORMAT_NOT_SUPPORTED.
The VkImageConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t formatConstraintsCount;
const VkImageFormatConstraintsInfoFUCHSIA* pFormatConstraints;
VkBufferCollectionConstraintsInfoFUCHSIA bufferCollectionConstraints;
VkImageConstraintsInfoFlagsFUCHSIA flags;
} VkImageConstraintsInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
formatConstraintsCountis the number of elements inpFormatConstraints. -
pFormatConstraintsis a pointer to an array of VkImageFormatConstraintsInfoFUCHSIA structures of sizeformatConstraintsCountthat is used to further constrain buffer collection format selection for image-based buffer collections. -
bufferCollectionConstraintsis a VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply parameters for the negotiation and allocation for buffer-based buffer collections. -
flagsis a VkImageConstraintsInfoFlagBitsFUCHSIA value specifying hints about the type of memory Sysmem should allocate for the buffer collection.
// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageConstraintsInfoFlagsFUCHSIA;VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a
mask of zero or more VkImageConstraintsInfoFlagBitsFUCHSIA bits.
Bits which can be set in
VkImageConstraintsInfoFlagBitsFUCHSIA::flags include:
// Provided by VK_FUCHSIA_buffer_collection
typedef enum VkImageConstraintsInfoFlagBitsFUCHSIA {
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA = 0x00000001,
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA = 0x00000002,
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA = 0x00000004,
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA = 0x00000008,
VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA = 0x00000010,
} VkImageConstraintsInfoFlagBitsFUCHSIA;General hints about the type of memory that should be allocated by Sysmem based on the expected usage of the images in the buffer collection include:
-
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA -
VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA
For protected memory:
-
VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIAspecifies that protected memory is optional for the buffer collection.
Note that if all participants in the buffer collection (Vulkan or otherwise) specify that protected memory is optional, Sysmem will not allocate protected memory.
The VkImageFormatConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageFormatConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkImageCreateInfo imageCreateInfo;
VkFormatFeatureFlags requiredFormatFeatures;
VkImageFormatConstraintsFlagsFUCHSIA flags;
uint64_t sysmemPixelFormat;
uint32_t colorSpaceCount;
const VkSysmemColorSpaceFUCHSIA* pColorSpaces;
} VkImageFormatConstraintsInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
imageCreateInfois the VkImageCreateInfo used to create a VkImage that is to use memory from the VkBufferCollectionFUCHSIA -
requiredFormatFeaturesis a bitmask ofVkFormatFeatureFlagBitsspecifying required features of the buffers in the buffer collection -
flagsis reserved for future use -
sysmemPixelFormatis aPixelFormatTypevalue from thefuchsia.sysmem/image_formats.fidlFIDL interface -
colorSpaceCountthe element count ofpColorSpaces -
pColorSpacesis a pointer to an array of VkSysmemColorSpaceFUCHSIA structs of sizecolorSpaceCount
// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageFormatConstraintsFlagsFUCHSIA;VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a
mask, but is currently reserved for future use.
The VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t minBufferCount;
uint32_t maxBufferCount;
uint32_t minBufferCountForCamping;
uint32_t minBufferCountForDedicatedSlack;
uint32_t minBufferCountForSharedSlack;
} VkBufferCollectionConstraintsInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
minBufferCountis the minimum number of buffers available in the collection -
maxBufferCountis the maximum number of buffers allowed in the collection -
minBufferCountForCampingis the per-participant minimum buffers for camping -
minBufferCountForDedicatedSlackis the per-participant minimum buffers for dedicated slack -
minBufferCountForSharedSlackis the per-participant minimum buffers for shared slack
Sysmem uses all buffer count parameters in combination to determine the
number of buffers it will allocate.
Sysmem defines buffer count constraints in
fuchsia.sysmem/constraints.fidl.
Camping as referred to by minBufferCountForCamping, is the number of
buffers that should be available for the participant that are not for
transient use.
This number of buffers is required for the participant to logically operate.
Slack as referred to by minBufferCountForDedicatedSlack and
minBufferCountForSharedSlack, refers to the number of buffers desired
by participants for optimal performance.
minBufferCountForDedicatedSlack refers to the current participant.
minBufferCountForSharedSlack refers to buffer slack for all
participants in the collection.
The VkSysmemColorSpaceFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkSysmemColorSpaceFUCHSIA {
VkStructureType sType;
const void* pNext;
uint32_t colorSpace;
} VkSysmemColorSpaceFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
colorSpacevalue of the SysmemColorSpaceType
Set Buffer-Based Buffer Collection Constraints
To set the constraints on a VkBuffer buffer collection, call:
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionBufferConstraintsFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkBufferConstraintsInfoFUCHSIA* pBufferConstraintsInfo);-
deviceis the logical device -
collectionis the VkBufferCollectionFUCHSIA handle -
pBufferConstraintsInfois a pointer to a VkBufferConstraintsInfoFUCHSIA structure
vkSetBufferCollectionBufferConstraintsFUCHSIA may fail if the
implementation does not support the constraints specified in the
bufferCollectionConstraints structure.
If that occurs, vkSetBufferCollectionBufferConstraintsFUCHSIA will
return VK_ERROR_FORMAT_NOT_SUPPORTED.
The VkBufferConstraintsInfoFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferConstraintsInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCreateInfo createInfo;
VkFormatFeatureFlags requiredFormatFeatures;
VkBufferCollectionConstraintsInfoFUCHSIA bufferCollectionConstraints;
} VkBufferConstraintsInfoFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
pBufferCreateInfoa pointer to a VkBufferCreateInfo struct describing the buffer attributes for the buffer collection -
requiredFormatFeaturesbitmask ofVkFormatFeatureFlagBitsrequired features of the buffers in the buffer collection -
bufferCollectionConstraintsis used to supply parameters for the negotiation and allocation of the buffer collection
Retrieve Buffer Collection Properties
After constraints have been set on the buffer collection by calling
vkSetBufferCollectionImageConstraintsFUCHSIA or
vkSetBufferCollectionBufferConstraintsFUCHSIA, call
vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and
finalized properties of the buffer collection.
The call to vkGetBufferCollectionPropertiesFUCHSIA is synchronous.
It waits for the Sysmem format negotiation and buffer collection allocation
to complete before returning.
// Provided by VK_FUCHSIA_buffer_collection
VkResult vkGetBufferCollectionPropertiesFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
VkBufferCollectionPropertiesFUCHSIA* pProperties);-
deviceis the logical device handle -
collectionis the VkBufferCollectionFUCHSIA handle -
pPropertiesis a pointer to the retrieved VkBufferCollectionPropertiesFUCHSIA struct
For image-based buffer collections, upon calling
vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element
of the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos
established by the preceding call to
vkSetBufferCollectionImageConstraintsFUCHSIA.
The index of the element chosen is stored in and can be retrieved from
VkBufferCollectionPropertiesFUCHSIA::createInfoIndex.
For buffer-based buffer collections, a single VkBufferCreateInfo is
specified as VkBufferConstraintsInfoFUCHSIA::createInfo.
VkBufferCollectionPropertiesFUCHSIA::createInfoIndex will
therefore always be zero.
vkGetBufferCollectionPropertiesFUCHSIA may fail if Sysmem is unable
to resolve the constraints of all of the participants in the buffer
collection.
If that occurs, vkGetBufferCollectionPropertiesFUCHSIA will return
VK_ERROR_INITIALIZATION_FAILED.
The VkBufferCollectionPropertiesFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionPropertiesFUCHSIA {
VkStructureType sType;
void* pNext;
uint32_t memoryTypeBits;
uint32_t bufferCount;
uint32_t createInfoIndex;
uint64_t sysmemPixelFormat;
VkFormatFeatureFlags formatFeatures;
VkSysmemColorSpaceFUCHSIA sysmemColorSpaceIndex;
VkComponentMapping samplerYcbcrConversionComponents;
VkSamplerYcbcrModelConversion suggestedYcbcrModel;
VkSamplerYcbcrRange suggestedYcbcrRange;
VkChromaLocation suggestedXChromaOffset;
VkChromaLocation suggestedYChromaOffset;
} VkBufferCollectionPropertiesFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
memoryTypeBitsis a bitmask containing one bit set for every memory type which the buffer collection can be imported as buffer collection -
bufferCountis the number of buffers in the collection -
createInfoIndexas described in Sysmem chosen create infos -
sysmemPixelFormatis the SysmemPixelFormatTypeas defined infuchsia.sysmem/image_formats.fidl -
formatFeaturesis a bitmask of VkFormatFeatureFlagBits shared by the buffer collection -
sysmemColorSpaceIndexis a VkSysmemColorSpaceFUCHSIA struct specifying the color space -
samplerYcbcrConversionComponentsis a VkComponentMapping structure specifying the component mapping -
suggestedYcbcrModelis a VkSamplerYcbcrModelConversion value specifying the suggested Y′CBCR model -
suggestedYcbcrRangeis a VkSamplerYcbcrRange value specifying the suggested Y′CBCR range -
suggestedXChromaOffsetis a VkChromaLocation value specifying the suggested X chroma offset -
suggestedYChromaOffsetis a VkChromaLocation value specifying the suggested Y chroma offset
sysmemColorSpace is only set for image-based buffer collections where
the constraints were specified using VkImageConstraintsInfoFUCHSIA in
a call to vkSetBufferCollectionImageConstraintsFUCHSIA.
For image-based buffer collections, createInfoIndex will identify both
the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos element and
the VkImageConstraintsInfoFUCHSIA::pFormatConstraints element
chosen by Sysmem when vkSetBufferCollectionImageConstraintsFUCHSIA was
called.
The value of sysmemColorSpaceIndex will be an index to one of the
color spaces provided in the
VkImageFormatConstraintsInfoFUCHSIA::pColorSpaces array.
The implementation must have formatFeatures with all bits set that
were set in
VkImageFormatConstraintsInfoFUCHSIA::requiredFormatFeatures, by
the call to vkSetBufferCollectionImageConstraintsFUCHSIA, at
createInfoIndex (other bits could be set as well).
Memory Allocation
To import memory from a buffer collection into a VkImage or a
VkBuffer, chain a VkImportMemoryBufferCollectionFUCHSIA
structure to the pNext member of the VkMemoryAllocateInfo in the
call to vkAllocateMemory.
The VkImportMemoryBufferCollectionFUCHSIA structure is defined as:
// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImportMemoryBufferCollectionFUCHSIA {
VkStructureType sType;
const void* pNext;
VkBufferCollectionFUCHSIA collection;
uint32_t index;
} VkImportMemoryBufferCollectionFUCHSIA;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure -
collectionis the VkBufferCollectionFUCHSIA handle -
indexthe index of the buffer to import fromcollection
To release a VkBufferCollectionFUCHSIA:
// Provided by VK_FUCHSIA_buffer_collection
void vkDestroyBufferCollectionFUCHSIA(
VkDevice device,
VkBufferCollectionFUCHSIA collection,
const VkAllocationCallbacks* pAllocator);-
deviceis the logical device that creates theVkBufferCollectionFUCHSIA -
collectionis the VkBufferCollectionFUCHSIA handle -
pAllocatoris a pointer to a VkAllocationCallbacks structure controlling host memory allocation as described in the Memory Allocation chapter