Clarify documentation of `VKCapabilitiesInstance` and `VKCapabilitiesDevice`

Description

It is not clear from the description of the VKCapabilitiesInstance and VKCapabilitiesDevice classes if they list available or enabled capabilities.

It is also unclear if instances of these classes always carry the same meaning; available or enabled. If they do not, the documentation for DispatchableHandleInstance::getCapabilities() and DispatchableHandleDevice::getCapabilities() should be changed instead, possibly their subclasses as well, if they also differ.

I was wondering if there was a built-in way of telling which version of Vulkan, and which extensions, were enabled, without keeping track of this myself. Looking at VkPhysicalDevice::getCapabilities(), I figured this might provide an overview of enabled extensions, however, because physical devices are only queried, not created, this seems to not make sense, as no extensions are enabled for them. However, then why does VkDevice have the same method? Surely, these capabilities might tell which extensions and API version are enabled? So do they return the same instance? No. The instances are actually of different classes. So that means that VKCapabilitiesDevice is for enabled capabilities, while VKCapabilitiesInstance is for available capabilities. But then again, VkInstance is created, not queried, and that also returns a VKCapabilitiesInstance instance. So maybe they all state enabled capabilities, then? But if that’s case, does LWJGL create different VkPhysicalDevices for each VkDevice. This is very confusing. So apparently, reading into the source code, VKCapabilitiesDevice does list enabled capabilities. And VkPhysicalDevice just saves a reference to the VkInstance’s capabilities. And I did not check the implementation for any subclasses of DispatchableHandleDevice other than VkDevice.

[Spasi]

Hey @ws909,

I’ve added the word “enabled” to the javadoc. Unlike OpenGL, the user is responsible for enabling any Vulkan extension they want to use explicitly. This is by design in Vulkan and LWJGL respects that design. You can discover available extensions with the functions vkEnumerateInstanceExtensionProperties and vkEnumerateDeviceExtensionProperties (for instance and device extensions respectively). See the HelloVulkan demo for sample usage.

Objects like VkPhysicalDevice and VkQueue carry the corresponding capabilities object of their parent, because they are what Vulkan calls “dispatchable handles”. Since there is no thread-local state in Vulkan, like the current context in OpenGL, Vulkan functions require another mechanism for dispatching, which is these dispatchable handles, usually the first parameter of a Vulkan function. LWJGL has also wrapped such handles (i.e. opaque pointers) in simple classes and uses their capabilities objects to call the correct function addresses. Also note that, similarly to how different OpenGL contexts may have different addresses for the same OpenGL function, different Vulkan instances/devices may also have different addresses for the same Vulkan function. This is done for efficiency (e.g. calling directly into the device driver, instead of going through an indirection layer first).

[Spasi]

@Spasi What I mean by relying on them, is if they should be considered internal components of LWJGL. An engine written in C++, for instance, would need to either write these classes itself, or use another way to keep track of which extensions are enabled. Were they written with the purpose to be used by LWJGL clients, or only as a helper for LWJGL itself? It’s just unclear what the intentions for these classes are, concerning users of LWJGL.

Well, both. It’s both an essential part of the LWJGL implementation and something useful to the user, something they would have implemented manually otherwise. In any case, it’s public API and by default this means it’s not an internal component.

More generally, all public classes/methods/fields in LWJGL bindings are part of the official API. Implementation details are hidden away in private & package-private components.

The only public components that are documented to be internal and subject to change, all live under the LWJGL core and the org.lwjgl.system package. Some utilities in there are used internally by bindings and could not be encapsulated properly in a Java 8 code base. In LWJGL 4, any such utilities will probably be hidden away using the functionality provided by Java Modules.