Tracking Issue for Bindings Generation & Improvements

[Perksey]

Comments

We truly invite everyone to send us reports of any place where our bindings are not ideal. This issue will serve as a list of things we should fix in 3.0.

The following summary comments have been formulated from your feedback, and these comments can be consulted for further information on the specific tasks:

• Tracking Issue for Bindings Generation & Improvements #887 (comment)

This is a living document! Please do not hesitate to point out any other potential improvements - we may add them to this list. If you would like to work on a task, please contact @Perksey in Discord for a brain dump if it's unclear what is required of a task.

Priority 0 (required for the first 3.0 preview)

• OpenGL generates both GLEnum and the stronger group enums. Functions taking enums as parameters are declared as a "duck type" Constant<uint, GLEnum> or Constant<uint, GLEnum, BufferUsage>, meaning that you can pass in a uint, GLEnum, or BufferUsage using implicit casts thereby not requiring an explosion in overloads.
• All functions are now stored in the GL class directly. GL can be used in a static way or as an instance of IGL. The static mechanism essentially just forwards to a thread-local IGL instance, but this won't be true for every binding.
• Automatically detect pointers to opaque structures and encapsulate these as handle structures e.g. VkInstanceT* or Ptr<VkInstanceT>/Ref<VkInstanceT> becomes VkInstance which contains a void* - make sure this is generic and can work with any binding.
  • Vulkan, WebGPU, and SDL depend on this.
  • Handle suffix has been added to generated structs
• Fixed buffer structs should be extracted and have a sensible name
• Anonymous structs should be extracted and have a sensible name

Priority 1 (required for the first 3.0 preview that contains a binding dependent on the task)

• Automatically detect pointers to structs containing a vtable pointer void** and encapsulate these as handle structures for them e.g. ID3D11Device* becomes D3D11Device containing a void***.
  • Required for any binding containing COM APIs.
  • Generic methods will take a type implementing IComVtbl as they do today (a TSelf generic parameter may be required for codegen in terms of these interfaces) i.e. CreateFactory<T>() -> T where T : IComVtbl/IComVtbl<T> and get a DXGIFactory2 out. These should be generated as they are in 2.X i.e. where IID_PPV_ARGS would be used in C/C++.
  • Handle types can implicitly case to their base types i.e. DXGIFactory2 will implicitly cast to DXGIFactory1 for example, to address a comment raised in this thread about polymorphism.
• Per [3.0] OpenGL Codegen #2020: Note that we need to make changes with/in ClangSharp to allow us to get the canonical type details e.g. HWND is actually HWND__* but the attribute only shows us HWND. This is to ensure that CreateBasicSymbolConstraints and co works correctly.
  • Required for any binding containing COM APIs.
• Implement Vulkan-style vtables i.e. using vkLoad*ProcAddr functions correctly using handles captured from vkCreateInstance/vkCreateDevice a la 2.X.
  • Required for Vulkan or OpenXR.
  • Ideally make it less complicated than 2.X and just throw (with a helpful message!) if the user tries to use multiple instance/device combos with one object, rather than maintaining a dictionary of vtables.

Priority 2 (required in any 3.0 preview)

• Support OpenGL handle generation as if they were opaque pointer types.
• Document the Silk.NET DSL i.e. the duck types, nullptr, AsRef, etc... Have a comprehensive documentation page describing all of our esoteric types and how to read function signatures defined in terms of them.
• Enforce extensions and versions using the SupportedApiProfile by using an analyser similar to SupportedOSPlatform. The analyser would encourage you to either annotate your function with its own attribute (such that the requirement bubbles up throughout the program) or to check that requirement a la GL.IsExtensionPresent("GL_KHR_debug") or GL.IsVersionAtLeast(4, 3).
• Introduce Pfn structures for function pointers that marshal invocations of the delegate being marshalled to DSL structures i.e. so users can use Ptr<sbyte> whereas we lower it to sbyte* implicitly. This is like 2.X but better.
• SAL attribute parsing into SymbolConstraints. Might be better done in ClangSharp itself and copying code from win32metadata code where possible.
• Per [3.0] OpenGL Codegen #2020: Note for a future PR: add [Flags] back
• We're not using in/out/ref as it currently stands for simplicity and keeping the overload count down, but we need to provide ample documentation and utilities for equivalent functionality

Priority 3 (preview 5/initial release)

• Introduce an analyser that directs the user to the most efficient usage model for each binding i.e. instance IGL for OpenGL, static Sdl for SDL, etc...
  • Add an attribute to indicate this based on the "static default" vtable
• Generate actual interfaces for COM interface structs i.e. ID3D11Device becomes D3D11Device representing the actual void*** handle (this shall implement IComVtbl), and ID3D11Device is generated as an actual interface to allow C# types to implement COM types.
  • Ideally not using ComWrappers, consult @Perksey for a brain dump
  • Ideally the user experience is just "implicit cast to the handle type, SilkMarshal will handle the rest".
  • Implement a demo for the How to create a D2D effect with Silk? #1951 use case
• Caps9.VertexShaderVersion doesn't seem to be as simple as just a uint (it seems to be similar to a Version32[?]) Should we provide utilities for this?
• Provide Throw/Assert/Expect extension methods on result-like types.
• Investigate the other miscellaneous improvements outlined in Tracking Issue for Bindings Generation & Improvements #887 (comment)

Priority 4 (initial release or following initial release)

• Add a Roslyn code completion provider that recurses into each T of a duck type such as Constant.
• Add a ReSharper/Rider plugin that implements the same code completion behaviour.

Priority 5 (stretch goal, likely future release)

• Introducing Object-suffixed classes to enable C# classes to mirror OOP-style C functions. e.g. instead of NamedBufferData, you could do BufferObject.BufferData.
  • The consensus on the maintainers team is that this doesn't add much to the bindings, but it does help make the library feel more at home with the rest of your C# code. Vulkan is probably going to be the primary use case for this.
• Overload functions like vkEnumerate, DXGI's EnumAdapter etc to return enumerables.

[SupinePandora43]

VkInstance and VkDevice handling behind the scenes in Vk.

Extensions.
It's kinda... complicated? There's some generic stuff, KhrSurface vs SurfaceKHR etc

[HurricanKai]

VkInstance and VkDevice handling behind the scenes in Vk.

This will be removed in favor of handle groups, but is a pain point in 2.x

There's some generic stuff, KhrSurface vs SurfaceKHR etc

This is reasonable feedback, but it's unclear what we can do here, this is effectively upstream khronos naming

[roeyskoe]

Currently on OpenGL there are several inconsistencies with what enum you can use with what function.
For example gl.TexImage2D does not accept GLEnum for all of its enum parameters.

I do agree that it may not be a great idea if you generate overloads for every single relevant enum there is with all of the combinations, but I think that being able to use GLenum everywhere would be nice, since it contains every native value (or atleast it should) and the other OpenGL relevant enums are just a subsets of it.

[desiwko]

There are several instances of methods that have ridiculous amounts of overloads due to the sheer number of parameters and combinations of ptr/ref/span permutations also in combination with for example the GLEnum vs. enum types. TexImage2D for example has 48 different combinations. I've seen certain methods with upwards of 100 overload options. It may be beneficial to limit overloads by a common type - e.g. either all by ptr, all by ref or all by span if possible.

This would also solve something I wouldn't mind seeing - which would be allowing the entire api to be usable inside a safe context if so desired. Currently certain methods are completely unavailable outside of unsafe - and arguably there may be certain ones that would be extremely difficult to craft into a safe context. (I'm looking at you, Vulkan!) (e.g all ref/out or span params)

[HurricanKai]

I do agree that it may not be a great idea if you generate overloads for every single relevant enum there is with all of the combinations, but I think that being able to use GLenum everywhere would be nice, since it contains every native value (or atleast it should) and the other OpenGL relevant enums are just a subsets of it.

Would it not be preferable to just eliminate GLEnum and strongly type the correct enum everywhere?

[HurricanKai]

This would also solve something I wouldn't mind seeing - which would be allowing the entire api to be usable inside a safe context if so desired. Currently certain methods are completely unavailable outside of unsafe - and arguably there may be certain ones that would be extremely difficult to craft into a safe context. (I'm looking at you, Vulkan!) (e.g all ref/out or span params)

There has been some discussion about the number of overloads in regard to 3.0 (-> we want to further improve overloads with better overloads)
I actually kind of like your idea, we could look to just generate one or a handful of safe methods + the pure native signature. If we do a really good job with safety I think most users would not miss the partially safe overloads. Seems like a thing to think about for sure!

[Perksey]

Would it not be preferable to just eliminate GLEnum and strongly type the correct enum everywhere?

For OpenGL specifically, I would not be happy doing this unless someone from our team audited the entire OpenGL specification and ensured that the groups are correct and sane, and committed to reviewing all changes thereafter to ensure that remains the case. The strong typing situation has been a mess ever since the demise of Silicon Graphics, as they stopped being properly maintained at that point. Everything thereafter is best effort.

[desiwko]

Would it not be preferable to just eliminate GLEnum and strongly type the correct enum everywhere?

For OpenGL specifically, I would not be happy doing this unless someone from our team audited the entire OpenGL specification and ensured that the groups are correct and sane, and committed to reviewing all changes thereafter to ensure that remains the case. The strong typing situation has been a mess ever since the demise of Silicon Graphics, as they stopped being properly maintained at that point. Everything thereafter is best effort.

I haven't looked at the spec in a really, really long time, but aren't new enums occasionally added specifically for EXT and ARB extensions? I think in cases like that you may want to still use the raw enums instead of encapsulating potentially constantly changing enum definitions. I know I'd personally like the option to use enums for those just-in-case moments.

[SupinePandora43]

Replace void* with nuint in Gl.VertexAttribPointer

[Beyley]

TODO

We truly invite everyone to send us reports of any place where our bindings are not ideal. This issue will serve as a list of things we should fix in 3.0.

the ENTIRETY of dx11

[SupinePandora43]

separation of dsa and non dsa?
Eg

interface BaseGL {
    void UseProgram(uint id);
}
interface DSA {
    void NamedBufferData(uint id, ...);
}
interface DSALess {
    void BufferData(...);
}

[Perksey]

the ENTIRETY of dx11

That’s not helpful feedback :P what’s not ideal about them?

[Beyley]

the ENTIRETY of dx11

That’s not helpful feedback :P what’s not ideal about them?

mostly the UUID shenanigans, see Vortice

ID3D11Texture2D backBuffer = this._swapChain.GetBuffer<ID3D11Texture2D>(0);

vs Silk.NET

ComPtr<ID3D11Texture2D> backBuffer;
_swapChain.Get().GetBuffer(0, SilkMarshal.GuidPtrOf<ID3D11Texture2D>(), ref backBuffer.Handle); //i dont know if this actually compiles, but i yoinked it from a line you posted in discord perskey so im going to assume it does

while its usable, its quite less sharpie and a bit harder to read

[Eeveelution]

i think this little code example of me once trying to use silk.net d3d11 illustrates how to me, unusable they are:

void* factoryOut = null;
//you need to get GUIDs for alot of stuff
Guid dxgiGuid = typeof(IDXGIFactory2).GUID;

dxgi.CreateDXGIFactory2(0, ref dxgiGuid, ref factoryOut);
//you need to cast this to be correct aswell..
this._iDxgiFactory = (IDXGIFactory2*) factoryOut;

//then this, this is just horrifying to me, and is the only way i knew how to get a swapchain going
//Gotta get the pointer to a IUnknown pointer for the device because thats what CreateSwapChainForHwnd wants
fixed (IUnknown* device = &this._device) {
    this._iDxgiFactory->CreateSwapChainForHwnd(device, window.Native.Win32.Value.Hwnd, ref swapChainDesc, ref fullscreenDesc, null, ref this._swapChain);
}

not a huge fan of having to get alot of GUIDs just to be able to create something like a texture or factory, and the pointer shenanigans just make it really unpleasant to use, yes ComPtr exists but it doesn't eliminate almost any of that, its just as if i were writing c++ but with c#, it just doesnt work

[HurricanKai]

Yeah the DX stuff certainly needs fixing - I think that work is inline with function groups.
Additionally we should look at overloads for methods that take a single GUID* like GetBuffer above, maybe creating a generic parameter, and replacing the GUID* with a call to SilkMarshal.GuidPtrOf<T>() 🤔

[Eeveelution]

While yes, you can do that, it still feels weird, especially the

fixed (IUnknown* device = &this._device)

I can live with the UUIDs but thats just ridiculous, and I think alot of the API has that, which is why currently I'm using vortice instead of silk for my d3d11 needs

[HurricanKai]

Not an DX expert, but I don't see how we can do anything about that? That's just what it looks like when you store IUnknown in a field and need a pointer to it later.
We can of course create ref overloads, which makes this much nicer, but retrieving the IUnknown from a GC managed location will always require some form of pinning

[Eeveelution]

I mean, I don't know how Vortice does it, but it has to be possible somehow if they've done it right? although I don't know if they regenerate their bindings often, which Silk does, which might hinder smth like this, the thing I'm looking for is making the API more natural, something like vortice, and taking a pointer to a pointer and casting that to a IUnknown pointer then using that is far from natural

[desiwko]

Technically if we're talking native C code, it IS natural to do that with COM. Nothing wrong with it from the purist standpoint, but you are right in that it's not exactly intuitive to use even in C++ anymore. I haven't played with it at all, but how did XNA wrap Direct3D? There may be some hints there that could be leveraged to making a more sane managed interface to D3D.

…

On Thu, Apr 28, 2022, 5:52 AM Furball ***@***.***> wrote: I mean, I don't know how Vortice does it, but it has to be possible somehow if they've done it right? although I don't know if they regenerate their bindings often, which Silk does, which might hinder smth like this, the thing I'm looking for is making the API more natural, something like vortice, and taking a pointer to a pointer and casting that to a IUnknown pointer then using that is far from natural — Reply to this email directly, view it on GitHub <#887 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFMMZU2TJUVDFBWDESJRK4DVHJUWPANCNFSM5TUFZQ2A> . You are receiving this because you commented.Message ID: <dotnet/Silk. ***@***.***>

[HurricanKai]

I entirely agree that we can improve things here, using ref for cases like this seems like a good idea. I just mean that the fixed statement specifically is just an artifact of using pointers with managed fields.

[Beyley]

SDL bidings tend to not match up the Enums with their respective functions very well, only doing it sometimes spirattically

[Beyley]

glDebugMessageInsert has no string overload

[Beyley]

the DebugUtilsMessageSeverityFlagsEXT enum is named very redundantly, with fields like DebugUtilsMessageSeverityFlagsEXT.DebugUtilsMessageSeverityVerboseBitExt and DebugUtilsMessageSeverityFlagsEXT.DebugUtilsMessageSeverityInfoBitExt
same with other EXT ones like DebugUtilsMessageTypeFlagsEXT

[Perksey]

@Beyley this is fixed in #948 and by extension 2.16

[Beyley]

@Beyley this is fixed in #948 and by extension 2.16

o

[Khitiara]

OpenAL is missing span overloads in many, many places. BufferData, SourceQueue/UnqueueBuffers in particular are sore spots

[Perksey]

Our OpenAL bindings are completely handwritten in 2.X (and haven't really been updated since the first or second preview of 1.0!) so for 2.X - contributions welcome :), but imo in 3.0 we'd be stupid not to have OpenAL autogenerated as well given our C/C++ toolchain will be a lot more mature.

[Beyley]

D3D9 PresentParameters.Windowed should be a bool, not an int

[Perksey]

It should probably be a Bool32 given that bool is a managed type but I agree otherwise

[Beyley]

D3D9 Swapeffect enum should be called SwapEffect

[Beyley]

D3D9 Theres no enums generated for the ptexturecaps stuff

[Beyley]

Theres no overloads on a lot of things for normal return types, requiring you to have to pass in a pointer to a struct instead

Also a lot of structs have a redundant 9 suffix that should be stripped out

[Beyley]

SilkMarshal.PtrToString should have an overload for byte* (or is there a reason there isnt)

[Beyley]

D3D9 missing devicecaps enum

[Beyley]

Caps9.VertexShaderVersion doesnt seem to be as simple as just a uint (it seems to be similar to a Version32[?])

[Beyley]

D3D9 Missing ClearFlags enum

[HurricanKai]

Theres no overloads on a lot of things for normal return types, requiring you to have to pass in a pointer to a struct instead

Pretty sure this is a symptom of 2.x having no access to SAL stuff. Talked to @Perksey about this few days ago, and looks like we can make this happen for 3.0

[Beyley]

D3D11 seems to be missing the DXGI_USAGE enum, well, its not an enum, but it should be in our bindings, maybe there should be a way to define a prefix as being treated as an enum?

[Beyley]

D3Dcolorvalue is named wrong, should likely just be ColorValue

[Beyley]

MapFlag.DONotWait is also named wrong, should be MapFlag.DoNotWait

[Beyley]

CL.EnqueueNdrangeKernel should be named EnqueueNDRangeKernel

[nike4613]

The GLFW bindings are missing GetWindowContentScale, despite having GetMonitorContentScale. (Unfortunately GetMonitorContentScale cannot be used instead, because some platforms don't seem to return a Monitor.)

GLFW bindings are also missing several members of the CursorShape enum, notably: RESIZE_ALL, RESIZE_NESW, and RESIZE_NWSE. (Interestingly, the GLFW online documentation doesn't define these, but ImGui's GLFW backend references them.) Looking more into that, those seem to me new in GLFW 3.4...

[RealityProgrammer]

1. Silk.NET.Direct3D12.DescriptorRangeFlags.DataStaticWhileSetATExecute should not capitalize the T in AT
2. Silk.NET.Direct3D12.RootParameterType's shorten name of the enum is not sufficient enough (enum members still have the Type prefix) A slight problem: 32-bit constants enum, if shorten then the enum name will start with a number, which is not valid.
3. Rework on ref and out modifier based on SAL annotation (eg: it should be ID3D12ShaderReflection.GetResourceBindingDesc(uint, out ShaderInputBindDesc) instead of ref)
4. Some API should NOT accept a Span overload (eg: QueryInterface)
5. Update Assimp's new post-process flags.
6. Utilize some enumerate instead of generating backing type if possible (eg: BufferDesc.CpuAccessFlags being uint instead of Silk.NET.Direct3D11.CpuAccessFlags)

[sgf]

Silk.NET.Direct2D.Enum.LawnGreen to D3Dcolorvalue

I'm not good at using c++, or even this smart pointer thing. Even though a lot of people say smart pointers are great.
I don't understand when I should use ComPtr and when I shouldn't use it, whether it should be used in the parameters of the function, or whether it should not be used. Is it possible to define two ComPtr fields in two types to save the same T object? . Questions like this. In short, I feel that I seem to be stuck in the complexity of C++. The joy of writing C# is gone. And the C# code looks even worse than the C++ code.

For this I now have to switch to SharpDx.

[Perksey]

Thanks for all the feedback, please do keep it coming! We are actively looking into 3.0 now.

[sgf]

Regarding GLFW, I am not opposed to using it, but I think it should be port(port to pure csharp) instead of binding(wrapper).

[DeadMG]

The main one for me is to respect the inheritance chain in bindings. Currently you can't write methods that take a ComPtr, and then pass in a ComPtr, and there's a similar issue around generic functions where the generic constraints won't work. For some interfaces it's not that big a deal, but there's a couple like IUnknown where it would be a lot more convenient. There doesn't seem to be any way to implement a generic TryQueryInterface.

There's also quite a few cases where the function seems like it should be simplified, although I'm not totally sure how obvious it is from a code generation perspective. This seems largely to relate to parameters by reference which generates three overloads for pointer, ref, and Span, when they should be generated as being taken by value or returned by value, e.g. ID3D12Device's CreateCommandQueue (input) or IDXGIAdapter's GetDesc() 1/2/3 (output). There's also a few like CreateSwapChainForHwnd where I would have expected at least one overload that returns ComPtr as this is the main output of the function (instead it has 90 overloads).

As an extra case, IDXDGIFactory's EnumAdapters could maybe use an extension that simply returns IEnumerable of the given T.

Lastly, for the NativeWindow's Win32 property, kindly add a comment in the doc about the HDC. From what I can see, DCs are meant to be used transiently and loaded with GetDC on demand, so I'm not really sure of the semantics. Am I meant to use CS_OWNDC, is the property re-invoked whenever a new DC is needed, or something else? It doesn't seem to fit with the WinAPI design to request that the caller provide an HDC when you're already asking for an HWND and can get your own HDC from that whenever you want.

There also eem to be a few missing constants, like DXGI_MWA_NO_ALT_ENTER, DXGI_SWAP_CHAIN_FLAG_ALLOW_TEARING, and DXGI_USAGE_RENDER_TARGET_OUTPUT.

[Perksey]

Hi all. I wanted to share my current thoughts on all of the above, and what 3.0 bindings currently look like.

See the current prototype 3.0 bindings in action!

Khronos-specific

Groups (implemented today in #2020)

DONE: OpenGL still generates both GLEnum and the stronger group enums. Functions taking enums as parameters are declared as a "duck type" Constant<uint, GLEnum> or Constant<uint, GLEnum, BufferUsage>, meaning that you can pass in a uint, GLEnum, or BufferUsage using implicit casts thereby not requiring an explosion in overloads. The JIT is able to inline the invocation of the method and the cast, so the codegen is equivalent to just passing in the true type directly.

This was the only way we have found so far to prevent alienating certain portions of our userbase by being opinionated in one direction and/or not preferring correctness, without exploding the API surface of Silk.NET like we've seen happen in 2.X.

TODO: The IDE experience isn't great for this sort of duck typing thing at the moment, I believe we can rectify it using a Rider/ReSharper extension and/or Roslyn code completion providers. We intend to have a comprehensive documentation page describing all of our esoteric types and how to read function signatures defined in terms of them.

An additional improvement we have made is trimming extension vendors from multi-vendor and/or promoted enums e.g. BufferUsageARB is now BufferUsage.

For the avoidance of doubt, fully unsafe overloads are available that do not have any transformations as described in this comment.

Extensions (implemented today in #2020)

We are moving away from having separate extension projects and extension classes in 3.0 as it currently stands. This thread has proven that it has caused some confusion, and we no longer believe it is necessary for the correctness we would like to achieve. This also aligns us with more traditional bindings libraries.

DONE: Essentially, all functions are now stored in the GL class directly. GL can be used in a static way or as an instance of IGL. The static mechanism essentially just forwards to a thread-local IGL instance, but this won't be true for every binding. We would like to introduce an analyser that directs the user to the most efficient mechanism for each binding.

Here's an example of this:

    [SupportedApiProfile(
        "glcore",
        ["GL_KHR_debug", "GL_VERSION_4_3", "GL_VERSION_4_4", "GL_VERSION_4_5", "GL_VERSION_4_6"],
        MinVersion = "4.3"
    )]
    [SupportedApiProfile(
        "gl",
        ["GL_KHR_debug", "GL_VERSION_4_3", "GL_VERSION_4_4", "GL_VERSION_4_5", "GL_VERSION_4_6"],
        MinVersion = "4.3"
    )]
    [NativeFunction("opengl", EntryPoint = "glDebugMessageCallback")]
    [MethodImpl(MethodImplOptions.AggressiveInlining | MethodImplOptions.AggressiveOptimization)]
    public static void DebugMessageCallback(
        [NativeTypeName("GLDEBUGPROC")]
            delegate* unmanaged<uint, uint, uint, uint, uint, sbyte*, void*, void> callback,
        [NativeTypeName("const void *")] void* userParam
    ) => ThisThread.DebugMessageCallback(callback, userParam);

TODO: This SupportedApiProfile attribute is the new way we will enforce extensions, by using an analyser similar to SupportedOSPlatform. Essentially, this function is to be interpreted as "supported in the GL_KHR_debug extension or GL_VERSION_4_3 or later". So an analyser would encourage you to either annotate your function as such (such that the requirement bubbles up throughout the program) or to check that requirement a la GL.IsExtensionPresent("GL_KHR_debug") or GL.IsVersionAtLeast(4, 3). This has not been implemented yet.

DONE: Ignore the delegate* in this function signature, it is our intention to have Pfn structures for function pointers similar to 2.X that will also take care of marshalling where they are implemented using a delegate.

Handles (Khronos and COM)

Currently in Silk.NET.Vulkan VkInstance is a structure that contains a void*. This is contrary to every other binding we have, which does not convert pointers to opaque types as to handle structures in this way. This is especially pertinent now that we're converging the Clang and Khronos generation mechanisms to both run atop ClangSharp, so our handles will actually be generated as VkInstanceT* which is likely not what we want. This presents an opportunity to come up with a solution that is applicable across all of our bindings (e.g. SDL, WebGPU, anywhere really...).

DONE: I believe that we should have these functions take a VkInstance handle encapsulating the opaque pointer, and that this should be applied at a generic level i.e. wherever we detect a pointer to an opaque type. Today, these are currently being represented as Ref<Instance>/Ptr<Instance> which is not what we want for something that the user is expected to store.

As for COM, 2.16+ was a great experiment in making our COM bindings more usable. We'd like to take those learnings forward into 3.0 to make our DirectX bindings even better. We've encountered issues with the methods being defined as extension methods atop ComPtr<T>, namely with IDE discoverability, but also all of the comments that our users have raised in this thread. We still need to find a way to make a generic ComPtr work so we can still handle the IID_PPV_ARGS pattern, but I feel like this needn't be the only part of the solution.

TODO: In line with the above opaque handle handling, I believe we should do something similar for COM APIs as well. Namely, instead of a ID3D11Device*, we shall have D3D11Device which encapsulates the void*** representing the instance of the vtable. Generic methods will take a type implementing IComVtbl as they do today (a TSelf generic parameter may be required though), so you can still do CreateFactory<DXGIFactory2>() and get a DXGIFactory2 out. DXGIFactory2 will implicitly cast to DXGIFactory1 for example, to address a comment raised in this thread about polymorphism.

TODO: To address a comment raised by #1951 and #408, we should generate an actual interface for each COM type i.e. have a IDXGIFactory2 in addition to a DXGIFactory2 which represents the native pointer. This should allow managed implementations of COM types. I would like to avoid ComWrappers for this, but it's unclear what our own COM interface marshalling implementation would look like.

DONE: As discussed in Discord, opaque handles (not COM handles) shall have a Handle suffix. By having a Handle suffix, we won't conflict with user code (e.g. a user-defined type called Shader) which users have expressed that this is sometimes an issue.

TODO: Moreover, by creating a differentiated handle type, this opens up future opportunities for opaque handle detection to go further by introducing Object-suffixed classes to enable C# classes to mirror OOP-style C functions. e.g. instead of NamedBufferData, you could do BufferObject.BufferData. The consensus on the maintainers team is that this doesn't add much to the bindings, but it does help make the library feel more at home with the rest of your C# code. Vulkan is probably going to be the primary use case for this.

Addressing Individual Comments

Currently on OpenGL there are several inconsistencies with what enum you can use with what function.
For example gl.TexImage2D does not accept GLEnum for all of its enum parameters.
I haven't looked at the spec in a really, really long time, but aren't new enums occasionally added specifically for EXT and ARB extensions? I think in cases like that you may want to still use the raw enums instead of encapsulating potentially constantly changing enum definitions. I know I'd personally like the option to use enums for those just-in-case moments.

Addressed in the grouping section wrt duck typing.

Replace void* with nuint in Gl.VertexAttribPointer

TODO: This is unsolved and needs to be rectified.

The main one for me is to respect the inheritance chain in bindings. Currently you can't write methods that take a ComPtr, and then pass in a ComPtr, and there's a similar issue around generic functions where the generic constraints won't work. For some interfaces it's not that big a deal, but there's a couple like IUnknown where it would be a lot more convenient.

Addressed in the handle section wrt handle types instead of a generic COM pointer type with extension methods.

There's also quite a few cases where the function seems like it should be simplified, although I'm not totally sure how obvious it is from a code generation perspective. This seems largely to relate to parameters by reference which generates three overloads for pointer, ref, and Span, when they should be generated as being taken by value or returned by value, e.g. ID3D12Device's CreateCommandQueue (input) or IDXGIAdapter's GetDesc() 1/2/3 (output). There's also a few like CreateSwapChainForHwnd where I would have expected at least one overload that returns ComPtr as this is the main output of the function (instead it has 90 overloads).
Some API should NOT accept a Span overload (eg: QueryInterface)
SilkMarshal.PtrToString should have an overload for byte* (or is there a reason there isnt)
Rework on ref and out modifier based on SAL annotation (eg: it should be ID3D12ShaderReflection.GetResourceBindingDesc(uint, out ShaderInputBindDesc) instead of ref)
NamedBufferSubData and NamedBufferData are missing ReadOnlySpan<> overloads
glDebugMessageInsert has no string overload
There are several instances of methods that have ridiculous amounts of overloads due to the sheer number of parameters and combinations of ptr/ref/span permutations also in combination with for example the GLEnum vs. enum types. TexImage2D for example has 48 different combinations. I've seen certain methods with upwards of 100 overload options. It may be beneficial to limit overloads by a common type - e.g. either all by ptr, all by ref or all by span if possible.

We will still have some overloads because we have discovered that our userbase has a lot of distinct ways of working with the library (so we don't want to form too much of an opinion to avoid alienating fragments of our userbase), but the duck typing mechanism should help get this number way down. I will be very shocked if any function in the entire library ends up with over 10 overloads. For more information, consult the SilkTouch 3.0 proposal in documentation/proposals. Similar mechanisms are used for Span/string/array parameters.

TODO: We are unlikely to make use of in/out/ref as it currently stands for simplicity and keeping the overload count down (we will provide ample documentation and utilities for equivalent functionality)

Silk.NET.Direct3D12.DescriptorRangeFlags.DataStaticWhileSetATExecute should not capitalize the T in AT
CL.EnqueueNdrangeKernel should be named EnqueueNDRangeKernel
MapFlag.DONotWait is also named wrong, should be MapFlag.DoNotWait

This is complicated. I've made some improvements as of #2020 to the naming prettifier but it's still very hard to get right and close to a "one size fits all" solution. Some sacrifices should be expected to be made somewhere, we are not going to get everything right and I can't promise that these issues will be rectified.

Silk.NET.Direct3D12.RootParameterType's shorten name of the enum is not sufficient enough (enum members still have the Type prefix) A slight problem: 32-bit constants enum, if shorten then the enum name will start with a number, which is not valid.

This one is the name translator working as expected! The Type prefix is included because removing it would generate invalid member names.

VkInstance and VkDevice handling behind the scenes in Vk.

TODO: Some of this is unfortunately necessary to use the vkLoad*ProcAddr functions correctly. I can't promise that this is going to go away in 3.0. Perhaps we'll make it less complicated and just throw (with a helpful message!) if the user tries to use multiple instance/device combos with one object.

Extensions.
It's kinda... complicated? There's some generic stuff, KhrSurface vs SurfaceKHR etc

Addressed above.

The GLFW bindings are missing GetWindowContentScale, despite having GetMonitorContentScale. (Unfortunately GetMonitorContentScale cannot be used instead, because some platforms don't seem to return a Monitor.)
The GLFW bindings seem to be missing the {Get,Set}WindowUserPointer functions, despite having the equivalents for Monitor and Joystick.

We're likely to remove our GLFW bindings in 3.0, at least for the initial versions. The team is leaning more towards using SDL3 instead, but we are actively working on establishing a policy that enables the community to add and independently maintain more non-core bindings.

As an extra case, IDXDGIFactory's EnumAdapters could maybe use an extension that simply returns IEnumerable of the given T.

TODO: This is a great idea!

Caps9.VertexShaderVersion doesnt seem to be as simple as just a uint (it seems to be similar to a Version32[?])

TODO: This should be investigated.

I'm not entirely sure how the bindings work currently in this regard, but how about automatic error checking for all the Vulkan functions which return a Result? For example Vulkan-Hpp does that, and only returns Results for functions where it makes sense to check for anything else other than Succcess, like with AcquireNextImage.

TODO: This is a good idea, but our users are likely to want choice here. Perhaps a Throw/Assert/Expect extension method on Result shall suffice?

This would also solve something I wouldn't mind seeing - which would be allowing the entire api to be usable inside a safe context if so desired. Currently certain methods are completely unavailable outside of unsafe - and arguably there may be certain ones that would be extremely difficult to craft into a safe context. (I'm looking at you, Vulkan!) (e.g all ref/out or span params)

Addressed in the handles section with Object-suffixed types. I can't speak on whether this means everything will be completely safe, but my hope with the duck typing described is that unsafe may be completely avoidable.

D3D9 Missing ClearFlags enum
Update Assimp's new post-process flags.
D3D9 missing devicecaps enum
D3Dcolorvalue is named wrong, should likely just be ColorValue
There also eem to be a few missing constants, like DXGI_MWA_NO_ALT_ENTER, DXGI_SWAP_CHAIN_FLAG_ALLOW_TEARING, and DXGI_USAGE_RENDER_TARGET_OUTPUT.
D3D9 Swapeffect enum should be called SwapEffect
D3D9 PresentParameters.Windowed should be a bool, not an int. [...] It should probably be a Bool32 given that bool is a managed type but I agree otherwise
The function definition for PfnDebugUtilsMessengerCallbackEXT in vulkan is incorrect, it should return a Boolean32, not a uint

TODO: We should investigate these comments once bindings parity with 2.X has been achieved in 3.0.

[Perksey]

TODO: Per #2020: Note for a future PR: add [Flags] back
TODO: Per #2020: Note that we need to make changes with/in ClangSharp to allow us to get the canonical type details e.g. HWND is actually HWND__* but the attribute only shows us HWND.

[Perksey]

The issue description has been updated to reflect the megacomment and is representative of the remaining work in SilkTouch 3.0. Please don't stop suggesting things though, it is not an immutable list!