377 lines
14 KiB
Plaintext
377 lines
14 KiB
Plaintext
== Binding Object Table
|
|
|
|
[open,refpage='VkObjectTableNVX',desc='Opaque handle to an object table',type='handles']
|
|
--
|
|
|
|
The device-side bindings are registered inside a table:
|
|
|
|
include::../../api/handles/VkObjectTableNVX.txt[]
|
|
|
|
--
|
|
|
|
This is required as the CPU-side object pointers, for example when binding a
|
|
sname:VkPipeline or sname:VkDescriptorSet, cannot be used by the device.
|
|
The combination of sname:VkObjectTableNVX and code:uint32_t table indices
|
|
stored inside a sname:VkBuffer serve that purpose during device command
|
|
generation.
|
|
|
|
At creation time the table is defined with a fixed amount of registration
|
|
slots for the individual resource types.
|
|
A detailed resource binding can then later be registered via
|
|
flink:vkRegisterObjectsNVX at any code:uint32_t index below the allocated
|
|
maximum.
|
|
|
|
|
|
=== Table Creation
|
|
|
|
[open,refpage='vkCreateObjectTableNVX',desc='Create an object table',type='protos']
|
|
--
|
|
|
|
To create object tables, call:
|
|
|
|
include::../../api/protos/vkCreateObjectTableNVX.txt[]
|
|
|
|
* pname:device is the logical device that creates the object table.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname:VkObjectTableCreateInfoNVX structure containing parameters
|
|
affecting creation of the table.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pObjectTable points to a slink:VkObjectTableNVX handle in which
|
|
the resulting object table is returned.
|
|
|
|
include::../../validity/protos/vkCreateObjectTableNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTableCreateInfoNVX',desc='Structure specifying the parameters of a newly created object table',type='structs']
|
|
--
|
|
|
|
The sname:VkObjectTableCreateInfoNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkObjectTableCreateInfoNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:objectCount is the number of entry configurations that the object
|
|
table supports.
|
|
* pname:pObjectEntryTypes is an array of elink:VkObjectEntryTypeNVX values
|
|
providing the entry type of a given configuration.
|
|
* pname:pObjectEntryCounts is an array of counts of how many objects can
|
|
be registered in the table.
|
|
* pname:pObjectEntryUsageFlags is an array of bitmasks of
|
|
elink:VkObjectEntryUsageFlagBitsNVX specifying the binding usage of the
|
|
entry.
|
|
* pname:maxUniformBuffersPerDescriptor is the maximum number of
|
|
ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or
|
|
ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC used by any single
|
|
registered sname:VkDescriptorSet in this table.
|
|
* pname:maxStorageBuffersPerDescriptor is the maximum number of
|
|
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or
|
|
ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC used by any single
|
|
registered sname:VkDescriptorSet in this table.
|
|
* pname:maxStorageImagesPerDescriptor is the maximum number of
|
|
ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE or
|
|
ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER used by any single
|
|
registered sname:VkDescriptorSet in this table.
|
|
* pname:maxSampledImagesPerDescriptor is the maximum number of
|
|
ename:VK_DESCRIPTOR_TYPE_SAMPLER,
|
|
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
|
|
ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or
|
|
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT used by any single registered
|
|
sname:VkDescriptorSet in this table.
|
|
* pname:maxPipelineLayouts is the maximum number of unique
|
|
sname:VkPipelineLayout used by any registered sname:VkDescriptorSet or
|
|
sname:VkPipeline in this table.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTableCreateInfoNVX-computeBindingPointSupport-01355]]
|
|
If the
|
|
sname:VkDeviceGeneratedCommandsFeaturesNVX::pname:computeBindingPointSupport
|
|
feature is not enabled, pname:pObjectEntryUsageFlags must: not contain
|
|
ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX
|
|
* [[VUID-VkObjectTableCreateInfoNVX-pObjectEntryCounts-01356]]
|
|
Any value within pname:pObjectEntryCounts must: not exceed
|
|
sname:VkDeviceGeneratedCommandsLimitsNVX::pname:maxObjectEntryCounts
|
|
* [[VUID-VkObjectTableCreateInfoNVX-maxUniformBuffersPerDescriptor-01357]]
|
|
pname:maxUniformBuffersPerDescriptor must: be within the limits
|
|
supported by the device.
|
|
* [[VUID-VkObjectTableCreateInfoNVX-maxStorageBuffersPerDescriptor-01358]]
|
|
pname:maxStorageBuffersPerDescriptor must: be within the limits
|
|
supported by the device.
|
|
* [[VUID-VkObjectTableCreateInfoNVX-maxStorageImagesPerDescriptor-01359]]
|
|
pname:maxStorageImagesPerDescriptor must: be within the limits supported
|
|
by the device.
|
|
* [[VUID-VkObjectTableCreateInfoNVX-maxSampledImagesPerDescriptor-01360]]
|
|
pname:maxSampledImagesPerDescriptor must: be within the limits supported
|
|
by the device.
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTableCreateInfoNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectEntryTypeNVX',desc='Enum specifying object table entry type',type='enums']
|
|
--
|
|
|
|
Possible values of elements of the
|
|
slink:VkObjectTableCreateInfoNVX::pname:pObjectEntryTypes array, specifying
|
|
the entry type of a configuration, are:
|
|
|
|
include::../../api/enums/VkObjectEntryTypeNVX.txt[]
|
|
|
|
* ename:VK_OBJECT_ENTRY_TYPE_DESCRIPTOR_SET_NVX specifies a
|
|
sname:VkDescriptorSet resource entry that is registered via
|
|
sname:VkObjectTableDescriptorSetEntryNVX.
|
|
* ename:VK_OBJECT_ENTRY_TYPE_PIPELINE_NVX specifies a sname:VkPipeline
|
|
resource entry that is registered via
|
|
sname:VkObjectTablePipelineEntryNVX.
|
|
* ename:VK_OBJECT_ENTRY_TYPE_INDEX_BUFFER_NVX specifies a sname:VkBuffer
|
|
resource entry that is registered via
|
|
sname:VkObjectTableIndexBufferEntryNVX.
|
|
* ename:VK_OBJECT_ENTRY_TYPE_VERTEX_BUFFER_NVX specifies a sname:VkBuffer
|
|
resource entry that is registered via
|
|
sname:VkObjectTableVertexBufferEntryNVX.
|
|
* ename:VK_OBJECT_ENTRY_TYPE_PUSH_CONSTANT_NVX specifies the resource
|
|
entry is registered via sname:VkObjectTablePushConstantEntryNVX.
|
|
|
|
--
|
|
|
|
[open,refpage='VkObjectEntryUsageFlagBitsNVX',desc='Bitmask specifying allowed usage of an object entry',type='enums']
|
|
--
|
|
|
|
Bits which can: be set in elements of the
|
|
slink:VkObjectTableCreateInfoNVX::pname:pObjectEntryUsageFlags array,
|
|
specifying binding usage of an entry, are:
|
|
|
|
include::../../api/enums/VkObjectEntryUsageFlagBitsNVX.txt[]
|
|
|
|
* ename:VK_OBJECT_ENTRY_USAGE_GRAPHICS_BIT_NVX specifies that the resource
|
|
is bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS
|
|
* ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX specifies that the resource
|
|
is bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE
|
|
|
|
--
|
|
|
|
[open,refpage='VkObjectEntryUsageFlagsNVX',desc='Bitmask of VkObjectEntryUsageFlagBitsNVX',type='flags']
|
|
--
|
|
include::../../api/flags/VkObjectEntryUsageFlagsNVX.txt[]
|
|
|
|
tname:VkObjectEntryUsageFlagsNVX is a bitmask type for setting a mask of
|
|
zero or more elink:VkObjectEntryUsageFlagBitsNVX.
|
|
--
|
|
|
|
[open,refpage='vkDestroyObjectTableNVX',desc='Destroy an object table',type='protos']
|
|
--
|
|
|
|
To destroy an object table, call:
|
|
|
|
include::../../api/protos/vkDestroyObjectTableNVX.txt[]
|
|
|
|
* pname:device is the logical device that destroys the table.
|
|
* pname:objectTable is the table to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyObjectTableNVX-objectTable-01361]]
|
|
All submitted commands that refer to pname:objectTable must: have
|
|
completed execution.
|
|
* [[VUID-vkDestroyObjectTableNVX-objectTable-01362]]
|
|
If sname:VkAllocationCallbacks were provided when pname:objectTable was
|
|
created, a compatible set of callbacks must: be provided here.
|
|
* [[VUID-vkDestroyObjectTableNVX-objectTable-01363]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:objectTable
|
|
was created, pname:pAllocator must: be `NULL`.
|
|
****
|
|
|
|
include::../../validity/protos/vkDestroyObjectTableNVX.txt[]
|
|
--
|
|
|
|
|
|
=== Registering Objects
|
|
|
|
[open,refpage='vkRegisterObjectsNVX',desc='Register resource bindings in an object table',type='protos']
|
|
--
|
|
|
|
Resource bindings of Vulkan objects are registered at an arbitrary
|
|
code:uint32_t index within an object table.
|
|
As long as the object table references such objects, they must: not be
|
|
deleted.
|
|
|
|
include::../../api/protos/vkRegisterObjectsNVX.txt[]
|
|
|
|
* pname:device is the logical device that creates the object table.
|
|
* pname:objectTable is the table for which the resources are registered.
|
|
* pname:objectCount is the number of resources to register.
|
|
* pname:ppObjectTableEntries provides an array for detailed binding
|
|
informations, each array element is a pointer to a struct of type
|
|
sname:VkObjectTablePipelineEntryNVX,
|
|
sname:VkObjectTableDescriptorSetEntryNVX,
|
|
sname:VkObjectTableVertexBufferEntryNVX,
|
|
sname:VkObjectTableIndexBufferEntryNVX or
|
|
sname:VkObjectTablePushConstantEntryNVX (see below for details).
|
|
* pname:pObjectIndices are the indices at which each resource is
|
|
registered.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkRegisterObjectsNVX-pObjectTableEntry-01364]]
|
|
The contents of pname:pObjectTableEntry must: yield plausible bindings
|
|
supported by the device.
|
|
* [[VUID-vkRegisterObjectsNVX-pObjectIndices-01365]]
|
|
At any pname:pObjectIndices there must: not be a registered resource
|
|
already.
|
|
* [[VUID-vkRegisterObjectsNVX-pObjectIndices-01366]]
|
|
Any value inside pname:pObjectIndices must: be below the appropriate
|
|
sname:VkObjectTableCreateInfoNVX::pname:pObjectEntryCounts limits
|
|
provided at pname:objectTable creation time.
|
|
****
|
|
|
|
include::../../validity/protos/vkRegisterObjectsNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTableEntryNVX',desc='Common parameters of an object table resource entry',type='structs']
|
|
--
|
|
Common to all resource entries are:
|
|
|
|
include::../../api/structs/VkObjectTableEntryNVX.txt[]
|
|
|
|
* pname:type defines the entry type
|
|
* pname:flags defines which elink:VkPipelineBindPoint the resource can be
|
|
used with.
|
|
Some entry types allow only a single flag to be set.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTableEntryNVX-computeBindingPointSupport-01367]]
|
|
If the
|
|
sname:VkDeviceGeneratedCommandsFeaturesNVX::pname:computeBindingPointSupport
|
|
feature is not enabled, pname:flags must: not contain
|
|
ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTableEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTablePipelineEntryNVX',desc='Parameters of an object table pipeline entry',type='structs']
|
|
--
|
|
include::../../api/structs/VkObjectTablePipelineEntryNVX.txt[]
|
|
|
|
* pname:pipeline specifies the slink:VkPipeline that this resource entry
|
|
references.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTablePipelineEntryNVX-type-01368]]
|
|
pname:type must: be ename:VK_OBJECT_ENTRY_TYPE_PIPELINE_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTablePipelineEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTableDescriptorSetEntryNVX',desc='Parameters of an object table descriptor set entry',type='structs']
|
|
--
|
|
include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[]
|
|
|
|
* pname:pipelineLayout specifies the slink:VkPipelineLayout that the
|
|
pname:descriptorSet is used with.
|
|
* pname:descriptorSet specifies the slink:VkDescriptorSet that can be
|
|
bound with this entry.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTableDescriptorSetEntryNVX-type-01369]]
|
|
pname:type must: be ename:VK_OBJECT_ENTRY_TYPE_DESCRIPTOR_SET_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTableDescriptorSetEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTableVertexBufferEntryNVX',desc='Parameters of an object table vertex buffer entry',type='structs']
|
|
--
|
|
|
|
include::../../api/structs/VkObjectTableVertexBufferEntryNVX.txt[]
|
|
|
|
* pname:buffer specifies the slink:VkBuffer that can be bound as vertex
|
|
bufer
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTableVertexBufferEntryNVX-type-01370]]
|
|
pname:type must: be ename:VK_OBJECT_ENTRY_TYPE_VERTEX_BUFFER_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTableVertexBufferEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTableIndexBufferEntryNVX',desc='Parameters of an object table index buffer entry',type='structs']
|
|
--
|
|
|
|
include::../../api/structs/VkObjectTableIndexBufferEntryNVX.txt[]
|
|
|
|
* pname:buffer specifies the slink:VkBuffer that can be bound as index
|
|
buffer
|
|
* pname:indexType specifies the elink:VkIndexType used with this index
|
|
buffer
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTableIndexBufferEntryNVX-type-01371]]
|
|
pname:type must: be ename:VK_OBJECT_ENTRY_TYPE_INDEX_BUFFER_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTableIndexBufferEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkObjectTablePushConstantEntryNVX',desc='Parameters of an object table push constant entry',type='structs']
|
|
--
|
|
|
|
include::../../api/structs/VkObjectTablePushConstantEntryNVX.txt[]
|
|
|
|
* pname:pipelineLayout specifies the slink:VkPipelineLayout that the
|
|
pushconstants are used with
|
|
* pname:stageFlags specifies the tlink:VkShaderStageFlags that the
|
|
pushconstants are used with
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkObjectTablePushConstantEntryNVX-type-01372]]
|
|
pname:type must: be ename:VK_OBJECT_ENTRY_TYPE_PUSH_CONSTANT_NVX
|
|
****
|
|
|
|
include::../../validity/structs/VkObjectTablePushConstantEntryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='vkUnregisterObjectsNVX',desc='Unregister resource bindings in an object table',type='protos']
|
|
--
|
|
|
|
Use the following command to unregister resources from an object table:
|
|
|
|
include::../../api/protos/vkUnregisterObjectsNVX.txt[]
|
|
|
|
* pname:device is the logical device that creates the object table.
|
|
* pname:objectTable is the table from which the resources are
|
|
unregistered.
|
|
* pname:objectCount is the number of resources being removed from the
|
|
object table.
|
|
* pname:pObjectEntryType provides an array of elink:VkObjectEntryTypeNVX
|
|
for the resources being removed.
|
|
* pname:pObjectIndices provides the array of object indices to be removed.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkUnregisterObjectsNVX-pObjectIndices-01373]]
|
|
At any pname:pObjectIndices there must: be a registered resource
|
|
already.
|
|
* [[VUID-vkUnregisterObjectsNVX-pObjectEntryTypes-01374]]
|
|
The pname:pObjectEntryTypes of the resource at pname:pObjectIndices
|
|
must: match.
|
|
* [[VUID-vkUnregisterObjectsNVX-None-01375]]
|
|
All operations on the device using the registered resource must: have
|
|
been completed.
|
|
****
|
|
|
|
include::../../validity/protos/vkUnregisterObjectsNVX.txt[]
|
|
--
|