KhronosGroup / KhronosGroup/Vulkan-Docs
Ignored pointers/handles are bad for generated code
- 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
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