status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-25 20:45:12 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/chapters/VK_NVX_device_generated_commands/objecttable.txt
Jon Leech 194a7f4d0d Change log for September 8, 2019 Vulkan 1.1.122 spec update: 
* Update release number to 122.

Internal Issues:

  * Add style guide language on not using standalone `+` signs (internal
    issue 736); not using leading whitespace for markup (internal issue
    747); and on keeping descriptions of a single API in a contiguous block
    of markup (internal issue 949), and apply them to the specification.
  * Add a glossary definition of "`constant integral expression`", pointing
    to the SPIR-V "`constant instruction`" definition (internal issue 1225).
  * Many minor edits to improve writing style consistency and capture
    additional style guidelines (internal issue 1553).
  * Clarify that <<fragops-depth-write, depth writes are not performed>> if
    there is no depth framebuffer attachment (internal issue 1771).
  * Allow implementations to use rectangular line style of interpolation for
    <<primsrast-lines-bresenham, wide Bresenham lines>>, though replicating
    attributes is still preferred. Clarify that code:FragCoord is not
    replicated (internal issue 1772).
  * Resolve a contradiction in valid usage statements for
    slink:VkImageCreateInfo and slink:VkImageStencilUsageCreateInfoEXT
    (internal issue 1773).
  * Add style guide discussion of markup for indented equations, and use
    markup workaround for asciidoctor 2 compatibility (internal issue 1793).
  * Deprecate the `<<VK_EXT_validation_flags>>` extension in `vk.xml` and
    the extension appendix (internal issue 1801).
  * Add a new checker script `scripts/xml_consistency.py`. This is not
    currently run as part of internal CI (internal merge request 3285).
  * Correct "`an`" -> "`a`" prepositions where needed (internal merge
    request 3334).
  * Clarify that the <<features-uniformBufferStandardLayout,
    pname:uniformBufferStandardLayout>> feature is only required when the
    extension defining it is supported (internal merge request 3341).
  * Bring scripts into closer sync with OpenXR, mainly through conversion of
    comments to docstrings where appropriate, and add gen-scripts-docs.sh
    (internal merge request 3324).
  * Correct pname:maxDrawMeshTasksCount to 2^16^-1 in the <<limits-required,
    Required Limits>> table (internal merge requests 3361).

New Extensions

  * `<<VK_IMG_format_pvrtc>>` (public issue 512).
2019-09-08 20:41:02 -07:00

381 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 a 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 is a pointer 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 a pointer to an array of
elink:VkObjectEntryTypeNVX values providing the entry type of a given
configuration.
* pname:pObjectEntryCounts is a pointer to an array of counts of how many
objects can be registered in the table.
* pname:pObjectEntryUsageFlags is a pointer to 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 structure 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