KhronosGroup / KhronosGroup/Vulkan-Docs

Document better which functions/values are not invariant

Open
#2,198 2 comments 3 reactions 1 assignee View on GitHub

@linyaa-kiwi is already working on this.

Since Aug 30, 2023.

Resolving Inside Khronos System Integration
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.