Platform: add D3D12 to modulemap

[compnerd]

Add the DirectX 12 header to the modulemap for the Windows SDK.

Replace this paragraph with a description of your changes and rationale. Provide links to external references/discussions if appropriate.

Resolves SR-NNNN.

[compnerd]

CC: @egorzhdan

[compnerd]

@swift-ci please test

[compnerd]

@swift-ci please test

[STREGAsGate]

Can we unlock these too? To make sure they are all compatible with the same version of Swift.

XInput XINPUT1_4.DLL
XAudio2 XAUDIO2_9.DLL

[compnerd]

Sure, that seems reasonable; got a pointer to the docs for the covered API?

[STREGAsGate]

Yup

D3d12 library info here
Xinput library info here.
XAudio2 library info here.
DXCore library info here

[stevapple]

Discussion: Should we place this module at WinSDK.DirectX.Direct3D.V12, for a clearer classification and versioning?

[stevapple]

Consideration: There’re many APIs in Windows which has many patches (for example, Direct2D), which can be “subversion”ed in the module map. Therefore, I propose to use such structure for Windows SDK:

module DirectX {
  module Direct3D {
    explicit module V12 {
      header "d3d12.h"
      export *

      link "d3d12.lib"
    }

    explicit module V11 {
      // ...
    }
  }

  module Direct2D {
    module V1 {
      header "d2d1.h"
      export *

      link "d2d1.lib"
    }

    explicit module V1_1 {
      header "d2d1_1.h"
      use V1

      export *
    }

    explicit module V1_2 {
      header "d2d1_2.h"
      use V1

      export *
    }
    // ...
  }
  // ...
}

[egorzhdan]

This works well for me (SourceKit produces a valid generated Swift interface for this submodule), however, I would agree with @stevapple's suggestion on naming: MSDN lists this header under "Direct3D 12 Graphics", could this submodule be located under WinSDK.Direct3D or WinSDK.DirectX?

[compnerd]

Yes, if we are adding the remainder of the DirectX APIs, it makes sense to organize them as @stevapple was pointing out. Although, I plan on only doing the minimum for the requested set. The organization of the modules has been somewhat ... difficult, at least in the past, so I tend to do the most minimal evolution of the module.

[stevapple]

I think the bigger problem is about versioning the same API set (as for the case of Direct2D and many others). Direct3D 12 is newer so it doesn’t have such variety yet. Direct3D 11, for example, has extra headers ranging from d3d11_1.h to d3d11_4.h, which requires higher target versions. It’s really a question how we can prove both compatibility and functionality.

[compnerd]

@stevapple you cannot - the user is responsible for handling the version compatibility checking. That is one of the problems with not having control over the platform. The best you can do is augment the information with APINotes.

[compnerd]

To be a bit more clear, we already have the ability to have conditional versioning on Windows:

if #available(Windows 10.0.18362) {
  ...
} else {
  ...
}

I haven't made much use of the deployment target handling as of yet, but I don't see why that would not afford us the necessary support for the version checking. We can continue to bump the minimum supported SDK, but as long as the runtime can be backdeployed to 17763, I think that we are okay. The annotations would need to be per-API, but we could add availability information as an APINotes supplement to validate on deployment targets.

The reason for the 17763 support to continue is that it is a LTSC release with support until 1/9/2029, and was the first version that I had targeted (due to missing APIs for UWP support in the earlier releases needed to support Dispatch and backtracing). This allows us to continue to deploy to various targets - the current implementation was carefully considered in order to be able to support Windows desktop (laptops/tablets/desktops), XBox, HoloLens, and Windows Phone.

[compnerd]

@STREGAsGate - I've added the DXCore bindings, but note that they are not usable. It requires the C++ interop to be functional, which is currently not fully working on Windows. There are problems with the modules (which is also why I prefer keeping the changes to the modules minimal) which prevent the C++ interop tests from even running on Windows with an updated environment. Once the module is well formed enough to allow the C++ interop to be used with a modern SDK, you should be able to use it with -enable-cxx-interop flag.

[compnerd]

@swift-ci please test

[compnerd]

@swift-ci please test Windows platform

[swift-ci]

Build failed
Swift Test Linux Platform
Git Sha - d2b8462effe54c2c92a463a096cfd1a6509e7038

[STREGAsGate]

Okay, we don't actually need DXCore. The functionality I would need is also found in DXGI so we could add that instead.

We do also need to add D3d12SDKLayers though, which is where all the debug and validation tools appear to be.

[stevapple]

The best you can do is augment the information with APINotes.

I mean we may introduce such headers with explicit module and an API note. Then everything depends on the user itself. @compnerd

This is the best solution I’ve come up with. I don’t like the idea of bumping minimum target version either. Oppositely, we should lower the bound to use a Swift application.

[compnerd]

I don't think that we need the explicit module, simply adding the APINotes for the interfaces should be sufficient. I think that we can assume, at least for the time being, anything at 17763 to always be available and annotate the newer interfaces? If so, if you want to create such an APINotes, I think that would be fine to add in.

[compnerd]

@swift-ci please test Linux platform

[STREGAsGate]

Okay, we don't actually need DXCore. The functionality I would need is also found in DXGI so we could add that instead.

We do also need to add D3d12SDKLayers though, which is where all the debug and validation tools appear to be.

Sry I edited my comment instead of posting again.
We can ditch DXCore and use DXGI which is older and shouldn't need build flags or API notes.
Also will need SDKLayers to be added. And I think that's it I think 🤞

[compnerd]

Sorry for the silly request, while I could try to fish out the docs, I want to make sure that I get the correct header. Would you mind sharing a pointer to MSDN for the API surface so I can cross-check and validate the module setup?

[STREGAsGate]

No prob. I think these are what you want.
DXGI and D3d12/D3d12SDKLayers

[compnerd]

It seems that we should be okay with additional link directives to pick up the import libraries. The dxd312.h includes d3d12sdklayers.h and d3d12sdklayers.h will include dxgi.h. The problem with the explicit include is that dxgi.h is a shared header, and the module map is in the um path, which makes it slight more challenging to get it explicitly handled.

[compnerd]

@swift-ci please test

[compnerd]

@swift-ci please smoke test macOS platform

[compnerd]

@swift-ci please test Windows platform

[drodriguez]

Does this need any change in the VS2017 CI machines? Seems that at least xaudio2.h is not being parsed correctly.