KhronosGroup / KhronosGroup/Vulkan-Docs

vkCreate* runtime errors and non-VK_NULL_HANDLE result pointers

Open
#956 0 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

At some point, the spec language on run time errors changed from:

> If a command returns a run time error, it will leave any result pointers unmodified, unless other behavior is explicitly defined in the specification.

To:

> If a command returns a run time error, unless otherwise specified any output parameters will have undefined contents, except that if the output parameter is a structure with sType and pNext fields, those fields will be unmodified. Any structures chained from pNext will also have undefined contents, except that sType and pNext will be unmodified.

This would seem to imply that, in the case of a run time error, implementations of vkCreate* are now permitted to overwrite the result pointer with a value other than VK_NULL_HANDLE, even though no valid object was created (at least I assume that no valid object is created if a failure VkResult is returned; I was not able to find any explicit statement of this but it is strongly implied).

There is this paragraph:

> The reserved values VK_NULL_HANDLE and NULL can be used in place of valid non-dispatchable handles and dispatchable handles, respectively, when explicitly called out in the Specification. Any command that creates an object successfully must not return these values.

But this refers to the converse case and would not prevent **un**successful creation from returning a **non-** VK_NULL_HANDLE.

As far as I can tell, only vkCreate*Pipelines has any language preventing this:

> When an application attempts to create many pipelines in a single command, it is possible that some subset may fail creation. In that case, the corresponding entries in the pPipelines output array will be filled with VK_NULL_HANDLE values. If any pipeline fails creation (for example, due to out of memory errors), the vkCreate*Pipelines commands will return an error code. The implementation will attempt to create all pipelines, and only return VK_NULL_HANDLE values for those that actually failed.

Is this intentional? Am I missing something? It would be a bit annoying for applications to have to reset the result pointer themselves to ensure that later vkDestroy* calls on that pointer are valid.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the quoted runtime-error language and the vkCreate*Pipelines exception in the Vulkan specification. Determine whether unsuccessful vkCreate* commands must leave result handles as VK_NULL_HANDLE, then clarify the specification consistently for the affected commands.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.