Document/explain differences between ash::Device and ash::vk::Device

[hoj-senna]

Ash features two different Device types (ash::Device and ash::vk::Device), and it is difficult for newcomers (or, at least, was difficult for me) to recognize and understand the difference.

The docs of both link to

https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VkDevice.html

although there is a difference.

I assume that the parallel existence of both is deliberate, but I would suggest to include an explanation in the docs why there are two Device types and which to use when.

Alternatives/additions I can think of:

• merge the two (disadvantage: this would turn the small handle type vk::Device into a larger thing)
• Rename ash::Device, e.g. to ash::DeviceLoader. (Disadvantage: breaking change affecting almost everyone, advantage: this would be similar to erupt)
• ignore (disadvantage: confusion for people like me)

(Similar comments apply to Instance.)

[cheako]

ash::DeviceProc sounds good, the old name can be set as depreciated for compatibility. To be clear, vk::Device is a number(usize?). ash::Device is a dispatchable object that holds a vk::Device where ash::Device::handle(&self) is used to access that value.

[Ralith]

I find I reference ash::Device often, so the current concise name is nice. No harm in improving the docs, though.

[cheako]

It shouldn't be a big deal, the deprecated note can easily reference the new name. The docs should contain a link and you can update any bookmarks. The thing is that ash::Device is not a Vulkan Device in any sense and the OP is correct, this is confusing.

[MarijnS95]

ash::Device is a Vulkan device handle with all its associated function pointers, that doesn't count as "not a Vulkan Device in any sense" in my book.

Improving the documentation is welcome, but I won't force this breaking (and IMO rather senseless) name change on all the many users of our crate.

[MarijnS95]

merge the two (disadvantage: this would turn the small handle type vk::Device into a larger thing)

This is not possible, we still have the lower-level FFI function signatures that leverage the vk::Device type. Can't suddenly clone/copy/move the entire function-pointer-struct in there.

[hoj-senna]

Thank you for your explanation and comments.

I see the point that the current name is concise and convenient and even more that a name change would affect every user of the crate without extremely important reason.

Also, it being the same as vk::Device fits well with the fact that functions like, e.g., vkBindBufferMemory(VkDevice,...) from the Vulkan spec are accessed as ash::Device::bind_buffer_memory(&self,...) in ash.

My concerns would be addressed with just the documentation change.

"This is a dispatchable object, whose main purpose is to provide access to Vulkan's functions.

It is not identical to Vulkan's device object (see [vk::Device][vk::Device]). The latter, however, can be accessed via the [handle()][Self::handle()] method.
In this sense, ash::Device is a Vulkan device handle together with all its associated function pointers.

All functions from the Vulkan API (except those from extensions) which have a VkDevice as their first argument, have become methods of ash::Device.
Their VkDevice argument is always passed implicitly.

Also, all vkCmd* functions are accessed as methods of ash::Device.

{remove current link to VkDevice}"
(Is this accurate and suitable?
If so, can I just put it into ash/src/device.rs or is there something special to observe in relation to automatic generation?)

—
(Probably pointless, since the consensus among the collaborators seems to be not to change the name, but still:

If there is a new name, however, I would prefer DeviceLoader over DeviceProc (the explanation "loads ... functions" in ash's README.md suggests as much, it corresponds to the variable names in README's example for extension loading, and then the terminology between ash and erupt would agree, which I'd consider a good thing), unless there are compelling reasons against this name.

In DeviceProc, I do not understand "Proc" (neither what exactly it abbreviates nor why it makes sense).
But I see the origin in Vulkan's vkGetDeviceProcAddr.)

[cheako]

deprecated is not breaking... last I checked.

[MarijnS95]

Deprecating is however done with the intention of removing it at some point, perhaps in the next breaking release cycle over.

Alternatively we're forcing users to disable the deprecation lint globally (entirely undesired) or add lots of localized exemptions which is pretty much the same as forcing the rename change on them.

[cheako]

I think you are missing two important options. Don't upgrade ash and start using the new name.