KhronosGroup / KhronosGroup/Vulkan-Docs

Ignored pointers/handles are bad for generated code

Open
#1,741 2 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

Examples of, in my opinion, unnecessarily complex Valid Usage statements:

```
VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750
If the pipeline is being created with pre-rasterization shader state, and the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pViewportState must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure
```
```
VUID-VkWriteDescriptorSet-descriptorType-02994
If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of pTexelBufferView must be either a valid VkBufferView handle or VK_NULL_HANDLE
```

These imply that the pointer can be garbage if the condition is not met. That causes a ton of complexity in drivers, layers, or other tools which handle application provided vulkan input. Generating code that serializes or copies vulkan structs now needs a lot of manual attention to make sure all valid input is safely handled.

It would be easier if the spec required applications to set the pointer to `NULL` if the condition is false. That would be easy to validate in the validation layers, and it's trivial to check in generated code before trying to deference the pointer.

Obviously the current API can't be changed, but it would be great if the list of structs that must be manually handled doesn't grow in the future.

To be 100% clear, instead of the examples above I would prefer:
```
VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750
If the pipeline is being created with pre-rasterization shader state, and the rasterizerDiscardEnable member of pRasterizationState is VK_FALSE, pViewportState must be a valid pointer to a valid VkPipelineViewportStateCreateInfo structure, otherwise pViewportState must be NULL
```
```
VUID-VkWriteDescriptorSet-descriptorType-02994
If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of pTexelBufferView must be either a valid VkBufferView handle or VK_NULL_HANDLE, otherwise pTexelBufferView must be NULL
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the cited VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750 and VUID-VkWriteDescriptorSet-descriptorType-02994 statements, then examine how Vulkan-Docs expresses conditional pointer and handle requirements. Determine whether a consistent future-specification policy is feasible; done means an agreed wording or policy for preventing unspecified pointers and handles outside their active conditions.

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
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.