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.