status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-26 04:55:12 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/chapters/VK_NVX_device_generated_commands/objecttable.txt
Jon Leech 0e3ceb7574 Change log for July 28, 2019 Vulkan 1.1.117 spec update: 
* Update release number to 117.

Github Issues:

  * Add ename:VK_STENCIL_FACE_FRONT_AND_BACK for naming consistency, and
    alias the old ename:VK_STENCIL_FRONT_AND_BACK for backwards
    compatibility (public issue 991).
  * Fix minor issues with valid usage statements for
    flink:vkCreateFramebuffer, slink:VkFramebufferCreateInfo, and
    slink:VkRenderPassBeginInfo when the `<<VK_KHR_imageless_framebuffer>>`
    extension is enabled (public issue 998).
  * Clarify the subpass dependency requirement in the
    <<renderpass-layout-transitions>> section to eliminate the need for a
    subpass dependency for either the same or different layouts as long as
    they're both read-only (relates to
    https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues/948).

Internal Issues:

  * Document that <<extendingvulkan-compatibility-promotion, backwards
    compatibility aliases are not promoted>> as part of promoting an
    extension (internal issue 1677).
  * Update VK_ANDROID_native_buffer extension to spec version 8 (internal
    issue 1753).
  * Add missing section to the <<VK_KHR_shader_controls_v4_incompatibility,
    VK_KHR_shader_float_controls>> extension appendix describing
    the reason for the breaking API change in version 4 of the extension,
    and correct the version to 4 in `vk.xml` (internal merge request
    3275).
  * Add valid usage statements to slink:VkAccelerationStructureInfoNV
    requiring the ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag for
    buffers used in acceleration structure building.

New Extensions:

  * `<<VK_EXT_line_rasterization>>`
  * `<<VK_EXT_texture_compression_astc_hdr>>`
  * `<<VK_EXT_index_type_uint8>>`
2019-07-28 21:22:36 -07:00

380 lines
14 KiB
Plaintext
Raw Blame History

== 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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/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::{generated}/validity/structs/VkObjectTableEntryNVX.txt[]
--
[open,refpage='VkObjectTablePipelineEntryNVX',desc='Parameters of an object table pipeline entry',type='structs']
--
include::{generated}/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::{generated}/validity/structs/VkObjectTablePipelineEntryNVX.txt[]
--
[open,refpage='VkObjectTableDescriptorSetEntryNVX',desc='Parameters of an object table descriptor set entry',type='structs']
--
include::{generated}/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::{generated}/validity/structs/VkObjectTableDescriptorSetEntryNVX.txt[]
--
[open,refpage='VkObjectTableVertexBufferEntryNVX',desc='Parameters of an object table vertex buffer entry',type='structs']
--
include::{generated}/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::{generated}/validity/structs/VkObjectTableVertexBufferEntryNVX.txt[]
--
[open,refpage='VkObjectTableIndexBufferEntryNVX',desc='Parameters of an object table index buffer entry',type='structs']
--
include::{generated}/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
* [[VUID-VkObjectTableIndexBufferEntryNVX-indexType-02783]]
pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, or
ename:VK_INDEX_TYPE_UINT32
****
include::{generated}/validity/structs/VkObjectTableIndexBufferEntryNVX.txt[]
--
[open,refpage='VkObjectTablePushConstantEntryNVX',desc='Parameters of an object table push constant entry',type='structs']
--
include::{generated}/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::{generated}/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::{generated}/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::{generated}/validity/protos/vkUnregisterObjectsNVX.txt[]
--
Reference in New Issue View Git Blame Copy Permalink