General API discussions

[abenedik]

I am starting this discussion so that the author and the users of the library can discuss about the API of the library - discuss the changes and share our views about different possible implementations.

Here are my thoughts:

In v1.2.170.1 the dependency on the Vortice.Mathematics was removed and a few basic types (VkOffset2D, VkOffset3D, VkExtent2D, VkExtent3D, VkRect2D, VkViewport) were added to support the types from Vulkan library.

In my opinion this is a good API change because removing dependency makes the library more general purpose and does not force the user in using dependent libraries (though Vortice.Mathematics is a great library). I think that libraries should strive to have as few dependencies as possible - of course, the "cost" of this should be considered. In this case the cost of adding a few rarely used types is worth this in my opinion.

In 1.2.170.2 the VkBool32 type was replaced by uint.

Here, except "simplifying" the library by removing a type, I do not find any other good reason for this change (but I may be missing something). On the other hand, removing the VkBool32 removes the option for implicit casting from bool to uint type that was possible before.

For example:

bool isDepthEnabled;

//pipelineRasterizationStateCreateInfo.depthClampEnable = isDepthEnabled; // before isDepthEnabled as bool was casted to VkBool32

pipelineRasterizationStateCreateInfo.depthClampEnable = isDepthEnabled ? (uint)1 : (uint)0; // new code 

or:

// pipelineRasterizationStateCreateInfo.depthClampEnable = true; // this worked fine
// pipelineRasterizationStateCreateInfo.depthClampEnable = VkBool32.True; // in my opinion this was more clear then:
pipelineRasterizationStateCreateInfo.depthClampEnable = (uint)1; 

Another example:

vkGetPhysicalDeviceSurfaceSupportKHR(_physicalDevice, i, _surface, out VkBool32 isSupported);
// if (isSupported)  // old code
if (isSupported != 0) // new code

Therefore I think that having VkBool32 was a better option that allowed having nicer code.

When I first started using Vulkan.Vortice I did not like that fields in Vk structs were written in camelCase. But I quickly saw that the reason for that was probably that the API is very low level and directly matches the Vulkan fields that use pointers many times (those fields start with small p prefix).

I prefer this direct approach and find it better than trying to provide some .Net wrapper around pointers used in Vulkan structs (as other Vulkan wrappers do).

Therefore I would vote for the current camelCase naming. Except maybe, the general purpose structs like VkRect2D I would use PascalCase and write Width and Height instead of width and height (but this is then different from the rest of the library). So this would be hard for me to decide. But this is a very good point for having such discussions.

To conclude, I would first like to thank the author very much for having this great wrapper library. It is also awesome that the library is immediately updated after Vulkan SDK changes.

But I think that it would be good if some other bigger and breaking API changes that are not related to Vulkan SDK are discussed with the community. Therefore I am asking the author and other users of the library to share their toughs and recommendations.

[amerkoleci]

Hi,
Thanks for bringing this, I will try to answer and give my feedback:

1. Yes, I would love to use Vortice.Mathematics but this way I don't force user to use my own math.
2. I agree, indeed release 1.3.0 now has VkBool32 back to handle this scenario.
3. We can use net standard type name if we want, and maybe use int instead of uint, long instead of ulong and even use where possible types from System.Numerics.Vector and System.Drawing (Size, Point, Rectangle).
4. Use int instead of uint in methods like: vkEnumerateInstanceLayerProperties etc

Thanks for your kind words,
Amer

[arakis]

Generally, i like the Api as it is. But i'm not a long term user. So here are my first thoughts:

• I would prefer PascalCasing everywhere, except where it makes no sense like pName and sType. So, i see the problem and the reasons, why camelCase would be the better choice.
• I would also prefer int/long instead of uint/ulong. Are there any cases, where the last bit is used by Vulkan?
• Regarding the Math structs: I would prefer to keep the generator as generic as possible, to setup own struct types for Vector2, Vector3 and so on.