== Binding Object Table

// refBegin VkObjectTableNVX Opaque handle to an object table

The device-side bindings are registered inside a table:

include::../../api/handles/VkObjectTableNVX.txt[]

// refEnd VkObjectTableNVX

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

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 sname:VkObjectTableNVX handle in which
    the resulting object table is returned.

include::../../validity/protos/vkCreateObjectTableNVX.txt[]

// refBegin VkObjectTableCreateInfoNVX Structure specifying the parameters of a newly created object table

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
    providing the entry type of a given configuration.
  * pname:pObjectEntryCounts is an array of counts how many objects can be
    registered in the table.
  * pname:pObjectEntryUsageFlags is an array of bitmasks describing the
    binding usage of the entry.
    See elink:VkObjectEntryUsageFlagBitsNVX below for a description of the
    supported bits.
  * 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.

// refBegin VkObjectEntryTypeNVX Enum specifying object table entry type

Types which can: be set in pname:pObjectEntryTypes are:

include::../../api/enums/VkObjectEntryTypeNVX.txt[]

 * ename:VK_OBJECT_ENTRY_DESCRIPTOR_SET_NVX indicates a
   sname:VkDescriptorSet resource entry that is registered via
   sname:VkObjectTableDescriptorSetEntryNVX.
 * ename:VK_OBJECT_ENTRY_PIPELINE_NVX indicates a sname:VkPipeline resource
   entry that is registered via sname:VkObjectTablePipelineEntryNVX.
 * ename:VK_OBJECT_ENTRY_INDEX_BUFFER_NVX indicates a sname:VkBuffer
   resource entry that is registered via
   sname:VkObjectTableIndexBufferEntryNVX.
 * ename:VK_OBJECT_ENTRY_VERTEX_BUFFER_NVX indicates a sname:VkBuffer
   resource entry that is registered via
   sname:VkObjectTableVertexBufferEntryNVX.
 * ename:VK_OBJECT_ENTRY_PUSH_CONSTANT_NVX indicates the resource entry is
   registered via sname:VkObjectTablePushConstantEntryNVX.

// refBegin VkObjectEntryUsageFlagBitsNVX Bitmask specifying allowed usage of an object entry

Bits which can: be set in pname:pObjectEntryUsageFlags are:

include::../../api/enums/VkObjectEntryUsageFlagBitsNVX.txt[]

  * ename:VK_OBJECT_ENTRY_USAGE_GRAPHICS_BIT_NVX indicates that the resource
    is bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS
  * ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX indicates that the resource
    is bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE

.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[]

// refBegin vkDestroyObjectTableNVX Destroy a object table

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

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[]

Common to all resource entries are:

include::../../api/structs/VkObjectTableEntryNVX.txt[]

  * pname:type defines the entry type
  * pname:flags defines which sname: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[]

include::../../api/structs/VkObjectTablePipelineEntryNVX.txt[]

  * pname:pipeline specifies the sname:VkPipeline that this resource entry
    references.

.Valid Usage
****
  * [[VUID-VkObjectTablePipelineEntryNVX-type-01368]]
    pname:type must: be ename:VK_OBJECT_ENTRY_PIPELINE_NVX
****

include::../../validity/structs/VkObjectTablePipelineEntryNVX.txt[]

include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[]

  * pname:layout specifies the sname:VkPipelineLayout that the
    pname:descriptorSet is used with.
  * pname:descriptorSet specifies the sname:VkDescriptorSet that can be
    bound with this entry.

.Valid Usage
****
  * [[VUID-VkObjectTableDescriptorSetEntryNVX-type-01369]]
    pname:type must: be ename:VK_OBJECT_ENTRY_DESCRIPTOR_SET_NVX
****

include::../../validity/structs/VkObjectTableDescriptorSetEntryNVX.txt[]

include::../../api/structs/VkObjectTableVertexBufferEntryNVX.txt[]

  * pname:buffer specifies the sname:VkBuffer that can be bound as vertex
    bufer

.Valid Usage
****
  * [[VUID-VkObjectTableVertexBufferEntryNVX-type-01370]]
    pname:type must: be ename:VK_OBJECT_ENTRY_VERTEX_BUFFER_NVX
****

include::../../validity/structs/VkObjectTableVertexBufferEntryNVX.txt[]

include::../../api/structs/VkObjectTableIndexBufferEntryNVX.txt[]

  * pname:buffer specifies the sname:VkBuffer that can be bound as index
    buffer
  * pname:indexType specifies the sname:VkIndexType used with this index
    buffer

.Valid Usage
****
  * [[VUID-VkObjectTableIndexBufferEntryNVX-type-01371]]
    pname:type must: be ename:VK_OBJECT_ENTRY_INDEX_BUFFER_NVX
****

include::../../validity/structs/VkObjectTableIndexBufferEntryNVX.txt[]

include::../../api/structs/VkObjectTablePushConstantEntryNVX.txt[]

  * pname:layout specifies the sname:VkPipelineLayout that pushconstants
    using this pname:objectIndex are used with.
  * pname:descriptorSet stageFlags the sname:VkShaderStageFlags that
    pushconstants using this pname:objectIndex are used with.

.Valid Usage
****
  * [[VUID-VkObjectTablePushConstantEntryNVX-type-01372]]
    pname:type must: be ename:VK_OBJECT_ENTRY_PUSH_CONSTANT_NVX
****

include::../../validity/structs/VkObjectTablePushConstantEntryNVX.txt[]

Using 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 sname: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[]
