Tracking Issue for Bindings Generation & Improvements

# 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:
- https://github.com/dotnet/Silk.NET/issues/887#issuecomment-2127867602

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)

- [x] OpenGL generates both GLEnum and the stronger group enums. Functions taking enums as parameters are declared as a "duck type" `Constant` or `Constant`, meaning that you can pass in a `uint`, `GLEnum`, or `BufferUsage` using **implicit casts** thereby not requiring an explosion in overloads.
- [x] 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.
- [x] Automatically detect pointers to opaque structures and encapsulate these as handle structures e.g. `VkInstanceT*` or `Ptr`/`Ref` becomes `VkInstance` which contains a `void*` - make sure this is generic and can work with any binding.
- Vulkan, WebGPU, and SDL depend on this.
- [x] Handle suffix has been added to generated structs
- [x] Fixed buffer structs should be extracted and have a sensible name
- [x] 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` `where T : IComVtbl`/`IComVtbl` 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 https://github.com/dotnet/Silk.NET/pull/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.
- [x] 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.
- [x] 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)
- [ ] ClangSharp currently erroneously renames "param" to "param". Once fixed upstream, remove this hack. https://discord.com/channels/521092042781229087/587346162802229298/1437503858849878037
- [ ] Don't drop the last word from a name trimming prefix if an enum name would start with a number once trimmed - instead, just prepend an `X` to the trimmed name.
- [ ] 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)`.
- [x] Introduce `Pfn` structures for function pointers that marshal invocations of the delegate being marshalled to DSL structures i.e. so users can use `Ptr` 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 https://github.com/dotnet/Silk.NET/pull/2020: Note for a future PR: add [Flags] back
- Edit by @Exanite: I believe this is done. Just need to verify.
- [ ] 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 #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 https://github.com/dotnet/Silk.NET/issues/887#issuecomment-2127867602

# 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.