KhronosGroup / KhronosGroup/Vulkan-Docs
Document better which functions/values are not invariant
@linyaa-kiwi is already working on this.
Since Aug 30, 2023.
- Dominant language
- JavaScript
- Stars
- 3.3k
- Forks
- 549
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 2
Description
https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap3.html#fundamentals-commandsyntax-results-lifetime states that vkGet* and vkEnumerate* functions are invariant by default, and will return the same information if called again. If otherwise, this should be specified in the documentation of that command. For example, the documentation of vkGetPhysicalDevicePresentRectanglesKHR says this.
In practice, however, this doesn't seem to be documented nearly as much as it ought to be, even for relatively obvious cases:
- vkGetPhysicalDeviceSurfaceCapabilities(2)KHR returns the current, minimum and maximum extent, which are very well known to change over time.
- The properties of each display returned by vkGetPhysicalDeviceDisplayPropertiesKHR may be invariant, but the selection of available displays seems like it could change, by plugging or unplugging something.
- vkGetPhysicalDeviceDisplayPlanePropertiesKHR returns the current display and stack index of a display plane, which by the naming alone seem like they can also change. I'm not sure what a display plane really represents, but maybe the selection of available planes can also change.
- It is conceivable that the output of vkGetPhysicalDeviceSurfaceFormatsKHR could change too, if the display is switched to another mode with a different colour depth by the user.
- vkEnumeratePhysicalDevices could return different devices if, for example, a driver were removed or added in the system in the intervening time.
There are surely other cases of this, that I haven't listed here.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.