DirectX and COM interoperability for .NET

[atcarter714]

So, I found my way here after a lot of research, landing on the WinMD repo and being directed to @AArnott by Mr. Kerr. I've managed to get CsWin32 to work for me for a simple test of DXGI and enumerating my adapters and outputs. This is lovely! I support this effort/project to the fullest because the possibilities here are truly amazing. It was like a Hollywood villain moment when I saw all those Win32 and COM APIs in C# IntelliSense! The power! 😄

So I would like to know, first of all: What can I do to help, support and contribute to this? I think bringing full DirectX to .NET is an important and noble effort, and this project is a godsend for that sort of thing. I'm more than happy to convert existing DirectX sample code over to C# with this, for example, that shouldn't be super hard. I can also possibly contribute to the code generation system as well as supplying feedback and testing things. Basically, whatever needs doing I'm willing to take a shot at it. Really interested in learning more about this and doing whatever I can to help things along and make improvements.

I'm sure to have a ton of questions. One I've got now is what is the most elegant way to get the RRID / GUID / UUID or whatever name you prefer of these COM interfaces. I couldn't figure out an obvious way other than clicking on Go to Definition and copying the Guid attribute string and using Guid.Parse. Ideally, this is something I think could be handled in a cleaner and more ".NET-like" way like a generic/Type argument (like with a where T: constraint) and it would infer the GUID from the attribute. Barring that, what would be a nice way to get it in my own code? Should I use reflection at startup to find them all or something? Don't really care for that idea but it would work. 🤷

Anyhow, I can't wait to have some fun with this converting some C++ samples to C# and building a game/3D framework and would love to assist! ❤️

[atcarter714]

Also, I expect HRESULT as a return type for many of these DirectX functions and COM methods but many of them seem to be changed to void. I made EnumAdapters fail and it threw an exception, which made me feel a little better about it. Is that the ideal way to handle that just use the try/catch mechanism instead of capturing HRESULTS like in C++ and checking return codes?

[atcarter714]

OK, I see the ComException type has way more info in it than a simple HRESULT including documentation help links and a message. That's actually ... beautiful 😍

[AArnott]

I'm gratified that you're pleased with CsWin32 so far.

what is the most elegant way to get the RRID / GUID / UUID or whatever name you prefer of these COM interfaces.

The ".NET way" is like this: typeof(ISomeInterface).GUID.

I expect HRESULT as a return type for many of these DirectX functions and COM methods but many of them seem to be changed to void.

That's another .NET convention. Learn more about PreserveSig. CsWin32 will default to using PreserveSig (which preserves the HRESULT return type) only for those members that the metadata describes as needing it. In the metadata, we annotate PreserveSig on methods that return non-S_OK success return codes (e.g. S_FALSE), which are otherwise impossible to detect in .NET. We also annotate APIs that commonly fail (e.g. when reaching the end of an enumeration). That leaves the exception-throwing behavior to those methods that one would not typically expect to fail.
But if you like PreserveSig and want to see it more, you can add a property like this to your NativeMethods.json file (see the readme):

  "comInterop": {
    "preserveSigMethods": [
      "IEnumString",
      "ISpellChecker"
    ]
  }

the ComException type has way more info in it than a simple HRESULT

There isn't anything there that your program couldn't obtain after detecting a failing HRESULT, but yes, it's nice when it comes for free.

What can I do to help, support and contribute to this?

Well, I love to hear that! Please pick an issue and dig in. You might start with the help wanted issues, but you don't have to restrict yourself to that issue label. I recommend of anything more than a trivial change, comment on the issue that you'd like to take it, and how you intend to resolve it (e.g. describe the design or changes you'll make) and wait for my confirmation before proceeding to reduce risk of wasted effort if someone else is already working on it or the approach isn't the way we'll want to accept a PR for it later.

I'm looking forward to hearing more from you!

[atcarter714]

I was wondering who the issue belongs to when I find some kind of issue with generation and how to determine if it belongs to the Win32 metadata project or CsWin32 ... for example, I found some types getting generated as uint instead of proper enum types, and not sure who that belongs to or how to decide where to draw the line on the issues.

Also, what about auto-documentation issues? I'm sure that belongs here?

[atcarter714]

There's also some apparent type duplication between Windows.Win32.Graphics.Dxgi and Windows.Win32.Graphics.Dxgi.Common ... it seems that it's generating a lot of the DXGI stuff twice, which I guess is caused by Windows headers having some DXGI stuff and DirectX having it, so the metadata and code generator are considering these belonging to separate namespaces or something. Might not be a big deal but for the fact that when it generates an internal type like DXGI_SWAP_CHAIN_DESC it defines it in Dxgi namespace but its members will be declared as belonging to Dxgi.Common, so I get this weird namespace criss-crossing and alias trouble in my generated code:

// Using Directives:
using winmdroot = global::Windows.Win32;

// Inside generated structure def for DXGI_SWAP_CHAIN_DESC:
internal winmdroot.Graphics.Dxgi.Common.DXGI_MODE_DESC BufferDesc;

Is this my fault? Do I need to do something in NativeMethods .txt/.json files to deal with this, or is this a legitimate issue?

[AArnott]

I was wondering who the issue belongs to when I find some kind of issue with generation and how to determine if it belongs to the Win32 metadata project or CsWin32 ... for example,

When in doubt, file it at CsWin32 and we can transfer the issue if appropriate. CsWin32 owns C# specific things, and there's quite a set of candidate bugs (not doing varargs right, not using SafeHandle when we should, etc). But when you want an enum instead of an int, or a struct is missing a field, that's a metadata issue and[ you can file it there.

Also, what about auto-documentation issues? I'm sure that belongs here?

Most of the doc content comes from docs.microsoft.com (or rather, the git repo behind it). But that funnels through the win32metadata site into a nuget package which CsWin32 consumes. We can't do much to improve that. We used a hand-crafted scraping tool to get the docs, so it's imperfect and incomplete.
CsWin32 owns how that data is formatted as C# xml doc comments. And a very little bit of docs come straight out of CsWin32. These only apply to the hand-crafted code such as inline arrays, a few helper methods, etc.

[AArnott]

There's also some apparent type duplication

That would be a metadata issue.

[atcarter714]

Roger that, I'll gather my notes and post those soon 📫