2016-07-10 18:13:41 -07:00
|
|
|
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
|
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
|
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
|
|
2016-02-16 01:53:44 -08:00
|
|
|
vkAllocateDescriptorSets(3)
|
|
|
|
|
===========================
|
|
|
|
|
|
|
|
|
|
Name
|
|
|
|
|
----
|
|
|
|
|
vkAllocateDescriptorSets - Allocate one or more descriptor sets.
|
|
|
|
|
|
|
|
|
|
C Specification
|
|
|
|
|
---------------
|
|
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
// refBegin vkAllocateDescriptorSets Allocate one or more descriptor sets.
|
|
|
|
|
|
|
|
|
|
To allocate descriptor sets from a descriptor pool, call:
|
|
|
|
|
|
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 03:15:48 -07:00
|
|
|
include::../api/protos/vkAllocateDescriptorSets.txt[]
|
2016-02-16 01:53:44 -08:00
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
|
2016-02-16 01:53:44 -08:00
|
|
|
Parameters
|
|
|
|
|
----------
|
|
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
* pname:device is the logical device that owns the descriptor pool.
|
|
|
|
|
* pname:pAllocateInfo is a pointer to an instance of the
|
|
|
|
|
slink:VkDescriptorSetAllocateInfo structure describing parameters of the
|
|
|
|
|
allocation.
|
|
|
|
|
* pname:pDescriptorSets is a pointer to an array of sname:VkDescriptorSet
|
|
|
|
|
handles in which the resulting descriptor set objects are returned. The
|
|
|
|
|
array must: be at least the length specified by the
|
|
|
|
|
pname:descriptorSetCount member of pname:pAllocateInfo.
|
2016-02-16 01:53:44 -08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Description
|
|
|
|
|
-----------
|
|
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
The allocated descriptor sets are returned in pname:pDescriptorSets.
|
2016-02-16 01:53:44 -08:00
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
When a descriptor set is allocated, the initial state is largely
|
|
|
|
|
uninitialized and all descriptors are undefined. However,
|
|
|
|
|
the descriptor set can: be bound
|
|
|
|
|
in a command buffer without causing errors or exceptions. All entries that
|
|
|
|
|
are statically used by a pipeline in a drawing or dispatching command must:
|
|
|
|
|
have been populated before the descriptor set is bound for use by that command.
|
|
|
|
|
Entries that are not statically used by a pipeline can: have uninitialized
|
|
|
|
|
descriptors or descriptors of resources that have been destroyed, and executing
|
|
|
|
|
a draw or dispatch with such a descriptor set bound does not cause undefined
|
|
|
|
|
behavior. This means applications need not populate unused entries with dummy
|
|
|
|
|
descriptors.
|
2016-02-16 01:53:44 -08:00
|
|
|
|
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 03:15:48 -07:00
|
|
|
If an allocation fails due to fragmentation, an indeterminate error is
|
Change log for August 5, 2016 Vulkan 1.0.23 spec update:
* Bump API patch number and header version number to 23 for this update.
Github Issues:
* Add explicit valid value attributes to pname:sType members in vk.xml
(public issue 34).
* Clarify usage of flink:vkGetInstanceProcAddr and
flink:vkGetDeviceProcAddr (public issue 225).
* Fix a copy-and-paste error in the description of
pname:pSwapchainImageCount saying that it was the count of ``format
pairs'' instead of ``swapchain images'' (public issue 292).
* flink:vkCmdExecuteCommandBuffers requires all command buffers to be
allocated from command pools created for the same queue family (public
issue 296).
* Remove bogus +optional+ attribute for
flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml
(public issue 301).
* Clean up the <<resources-image-views-compatibility,image and image view
compatibility table>> reference and contents. Use full enumerant names.
Refer to pname:layerCount in the ``view parameters'' column instead of
pname:arrayLayers. Require N >= 1 for the cube array subview row, not
just arrayLayers >= 6 N (public issue 304).
* Modify description of <<resources-memory-aliasing,memory aliasing>> to
be consistent with the description of
<<resources-bufferimagegranularity,buffer image granularity>> (public
issue 307).
Internal Issues:
* Describe remaining +vk_platform.h+ macros in the <<boilerplate,API
Boilerplate>> appendix (internal issue 6).
* Clarify
<<features-features-robustBufferAccess,pname:robustBufferAccess>>
feature behavior; what memory can be accessed, how bounds checking is
performed, and allowing for vectorization (internal issue 332).
* Document markup for automatic extraction of reference pages from the
spec sources in the style guide (internal issue 395).
* Allow flink:vkCreateDisplayModeKHR to return
ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode
parameters that the specified display does not support (internal issue
411).
* Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and
more clearly remove the subroutine keyword alongside it (internal issue
421).
* Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets
not contained in the layout (internal issue 427).
Other Commits:
* Change the order in which members of sname:VkAttachmentDescription and
sname:VkPipelineInputAssemblyStateCreateInfo are described to match
their order in the structures.
2016-08-05 05:11:02 -07:00
|
|
|
returned with an unspecified error code. Any returned error other than
|
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 03:15:48 -07:00
|
|
|
ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning:
|
|
|
|
|
applications should: assume that the allocation failed due to fragmentation,
|
|
|
|
|
and create a new descriptor pool.
|
|
|
|
|
|
|
|
|
|
[NOTE]
|
|
|
|
|
.Note
|
|
|
|
|
====
|
|
|
|
|
Applications should check for a negative return value when allocating new
|
|
|
|
|
descriptor sets, assume that any error effectively means
|
|
|
|
|
ename:VK_ERROR_FRAGMENTED_POOL, and try to create a new descriptor pool.
|
|
|
|
|
If ename:VK_ERROR_FRAGMENTED_POOL is the actual return value, it adds
|
|
|
|
|
certainty to that decision.
|
|
|
|
|
|
|
|
|
|
The reason for this is that ename:VK_ERROR_FRAGMENTED_POOL was only added in
|
|
|
|
|
a later revision of the 1.0 specification, and so drivers may: return other
|
|
|
|
|
errors if they were written against earlier revisions.
|
|
|
|
|
To ensure full compatibility with earlier patch revisions, these other
|
|
|
|
|
errors are allowed.
|
|
|
|
|
====
|
|
|
|
|
|
2016-02-16 01:53:44 -08:00
|
|
|
include::../validity/protos/vkAllocateDescriptorSets.txt[]
|
|
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
|
2016-02-16 01:53:44 -08:00
|
|
|
See Also
|
|
|
|
|
--------
|
|
|
|
|
|
2016-07-10 18:13:41 -07:00
|
|
|
slink:VkDescriptorSet, slink:VkDescriptorSetAllocateInfo, slink:VkDevice
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Document Notes
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
For more information, see the Vulkan Specification at URL
|
|
|
|
|
|
|
|
|
|
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkAllocateDescriptorSets
|
|
|
|
|
|
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
|
|
|
Fixes and changes should be made to the Specification,not directly.
|
2016-02-16 01:53:44 -08:00
|
|
|
|
|
|
|
|
include::footer.txt[]
|
2016-07-10 18:13:41 -07:00
|
|
|
|