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 via certain commands, or by directly specifying them as parameters to certain commands.
Buffers are represented by VkBuffer
handles:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)
To create buffers, call:
VkResult vkCreateBuffer( VkDevice device, const VkBufferCreateInfo* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkBuffer* pBuffer);
device
is the logical device that creates the buffer object.
pCreateInfo
is a pointer to an instance of the
VkBufferCreateInfo
structure containing parameters affecting
creation of the buffer.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.
pBuffer
points to a VkBuffer
handle in which the resulting
buffer object is returned.
The VkBufferCreateInfo
structure is defined as:
typedef struct VkBufferCreateInfo { VkStructureType sType; const void* pNext; VkBufferCreateFlags flags; VkDeviceSize size; VkBufferUsageFlags usage; VkSharingMode sharingMode; uint32_t queueFamilyIndexCount; const uint32_t* pQueueFamilyIndices; } VkBufferCreateInfo;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
flags
is a bitmask describing additional parameters of the
buffer. See VkBufferCreateFlagBits
below for a description of the
supported bits.
size
is the size in bytes of the buffer to be created.
usage
is a bitmask describing the allowed usages of the buffer.
See VkBufferUsageFlagBits
below for a description of the supported
bits.
sharingMode
is the sharing mode of the buffer when it will be
accessed by multiple queue families, see VkSharingMode
in the
Resource Sharing section below for supported
values.
queueFamilyIndexCount
is the number of entries in the
pQueueFamilyIndices
array.
pQueueFamilyIndices
is a list of queue families that will
access this buffer (ignored if sharingMode
is not
VK_SHARING_MODE_CONCURRENT
).
Bits which can be set in usage
are:
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, } VkBufferUsageFlagBits;
VK_BUFFER_USAGE_TRANSFER_SRC_BIT
indicates that the buffer can be
used as the source of a transfer command (see the definition of
VK_PIPELINE_STAGE_TRANSFER_BIT
).
VK_BUFFER_USAGE_TRANSFER_DST_BIT
indicates that the buffer
can be used as the destination of a transfer command.
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
indicates that the buffer
can be used to create a VkBufferView
suitable for occupying a
VkDescriptorSet
slot of type
VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
.
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
indicates that the buffer
can be used to create a VkBufferView
suitable for occupying a
VkDescriptorSet
slot of type
VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
.
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT
indicates that the buffer can
be used in a VkDescriptorBufferInfo
suitable for occupying a
VkDescriptorSet
slot either of type
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER
or
VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
.
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT
indicates that the buffer can
be used in a VkDescriptorBufferInfo
suitable for occupying a
VkDescriptorSet
slot either of type
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER
or
VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
.
VK_BUFFER_USAGE_INDEX_BUFFER_BIT
indicates that the buffer is
suitable for passing as the buffer
parameter to
vkCmdBindIndexBuffer
.
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT
indicates that the buffer is
suitable for passing as an element of the pBuffers
array to
vkCmdBindVertexBuffers
.
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
indicates that the buffer is
suitable for passing as the buffer
parameter to
vkCmdDrawIndirect
, vkCmdDrawIndexedIndirect
, or
vkCmdDispatchIndirect
.
Any combination of bits can be specified for usage
, but at least one
of the bits must be set in order to create a valid buffer.
Bits which can be set in flags
are:
typedef enum VkBufferCreateFlagBits { VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001, VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002, VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004, } VkBufferCreateFlagBits;
These bits have the following meanings:
VK_BUFFER_CREATE_SPARSE_BINDING_BIT
indicates that the buffer will
be backed using sparse memory binding.
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
indicates that the buffer
can be partially backed using sparse memory binding. Buffers
created with this flag must also be created with the
VK_BUFFER_CREATE_SPARSE_BINDING_BIT
flag.
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
indicates 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 the VK_BUFFER_CREATE_SPARSE_BINDING_BIT
flag.
See Sparse Resource Features and Physical Device Features for details of the sparse memory features supported on a device.
To destroy a buffer, call:
void vkDestroyBuffer( VkDevice device, VkBuffer buffer, const VkAllocationCallbacks* pAllocator);
device
is the logical device that destroys the buffer.
buffer
is the buffer to destroy.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.