KhronosGroup / KhronosGroup/Vulkan-Docs

Document effects of vkFreeDescriptorSets and vkResetDescriptorPool failure, if any.

Open
#2,317 17 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
3.3k
Forks
549
Avg merge
5d 5h
Merged PRs (30d)
2

Description

The documentation for [vkFreeDescriptorSets](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkFreeDescriptorSets.html) and [vkResetDescriptorPool](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkResetDescriptorPool.html) indicates return values of `VK_SUCCESS` on success, but it makes no mention of other possible return values and, more importantly, makes no mention of the state of the pool and descriptor sets after failure. Do all descriptor sets remain valid after failure? Might some be freed and others not? Could the pool itself end up in an inconsistent state after a failed reset, with e.g. some descriptor sets becoming invalid but not being returned to the pool? As it stands the documentation provides no guidance on what programs should expect after these calls have failed.

A related issue, #1070, mentions other return values which have now been removed. In the responses to that issue one contributor stated that including those other values "was probably an oversight, and if we can establish that all implementations only return successfully, we'll probably add a restriction to the allowed return value and a Note explaining the discrepancy." The return values have been removed without noting any restriction on the return value (beyond, perhaps, an implicit one by omission).

The standard needs to address this.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the linked vkFreeDescriptorSets and vkResetDescriptorPool reference pages and the related issue #1070. Done means the specification clearly documents possible return values and the descriptor-pool and descriptor-set state after failure.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.