KhronosGroup / KhronosGroup/Vulkan-Docs
Unnecessarily confusing Image\Buffer support
- Dominant language
- JavaScript
- Stars
- 3.3k
- Forks
- 549
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 2
Description
I find Image\Buffer support described in the spec to be unnecessarily confusing, and sometimes ambiguous. Especially to newish reader.
Some summary definition of how the system should work should be explicitly specified. I think it should have its own (sub)chapter that is linked to from the relevant parts of spec and from VUs.
i.e. the scope of the Mandatory Support. And that you do not even need to query if you fit in that support (current wording feels bit insufficient and wishy-washy). And notably I find it confusing that stuff limiting it for LINEAR images is specified at `vkCreateImage`.
Then some hierarchy should be established. The `vkGetPhysicalDeviceFormatProperties` should not contradict the Mandatory Support. And `vkGetPhysicalDeviceImageFormatProperties` should contradict neither (my driver actually violates this).
It should be more clearly stated what the relation to swapchain images is. i.e. if there is any relation of output of queries to swapchain (`vkGetPhysicalDeviceSurfaceCapabilitiesKHR` and `vkGetPhysicalDeviceSurfaceFormatsKHR`) vs the above general Image queries. Notably it is confusing at the point of `vkCreateImageView` created from swapchain image, where the `vkGetPhysicalDeviceFormatProperties` comes into play again.
Furthermore some sanity restrictions seems missing. E.g. like depth formats should not be able to report non-depth features (and vice versa). The depth format table should probably not even have those flags as columns (or should be red-crossed out). Also #672.
_Some_ of this info is there but I find it confusing, ambiguous, and\or fragmented. It feels it needs bit of a wholistic rewrite; not sure if localized changes can fix this. I understand nobody has time for this, so I at least symbolically make this Issue...
Contributor guide
Research direction
Start by reviewing the Image\Buffer portions of the specification, the linked VUs, and the sections for vkCreateImage, vkGetPhysicalDeviceFormatProperties, vkGetPhysicalDeviceImageFormatProperties, vkCreateImageView, and the swapchain queries. Compare the Mandatory Support, format-property queries, swapchain behavior, and depth-format table, including the concerns in #672. Done would mean a consistent, clearly linked explanation with resolved contradictions and explicit sanity restrictions.
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