== 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 ftext: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 ftext: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='enums']
--
include::../../api/flags/VkObjectEntryUsageFlagsNVX.txt[]

sname:VkObjectEntryUsageFlagsNVX is a bitmask type for setting a mask of
zero or more slink: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
ftext: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 slink: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 slink: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 slink: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 slink: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[]
--
