dotnet · Exanite · May 23, 2025 · May 23, 2025 · May 23, 2025 · May 23, 2025
@@ -7,14 +7,14 @@ permissions:
   contents: write
 env:
   # A space-separated list of paths to native libraries to build.
-  NATIVE_LIBRARY_PATHS: "sources/SDL/Native"
+  NATIVE_LIBRARY_PATHS: "sources/SDL/Native sources/OpenAL/Soft.Native"
   # A space-separated list of submodule paths for each native library path. Use _ if a submodule is not used - this must
   # match the number of spaces in NATIVE_LIBRARY_PATHS.
-  NATIVE_LIBRARY_SUBMODULE_PATHS: "eng/submodules/sdl"
+  NATIVE_LIBRARY_SUBMODULE_PATHS: "eng/submodules/sdl eng/submodules/openal-soft"
   # A space-separated list of shorthands to the native library paths that will build the native library for each native
   # library path. This must match the number of spaces in NATIVE_LIBRARY_PATHS. If a shorthand builds multiple native
   # binary paths, these will be deduplicated.
-  NATIVE_LIBRARY_SHORTHANDS: "SDL"
+  NATIVE_LIBRARY_SHORTHANDS: "SDL OpenAL-Soft"
 jobs:
   prerequisites:
     name: PR Check
@@ -61,13 +61,15 @@ jobs:
   build:
     needs: [prerequisites]
     strategy:
+      fail-fast: false
       matrix:
         flat: ${{ fromJSON(needs.prerequisites.outputs.matrix_strategy) }}
     runs-on: ${{ (startsWith(matrix.flat.runtime, 'osx') || startsWith(matrix.flat.runtime, 'ios') || startsWith(matrix.flat.runtime, 'tvos')) && 'macos-latest' || startsWith(matrix.flat.runtime, 'win') && 'windows-latest' || 'ubuntu-latest' }}
     name: ${{ matrix.flat.target }} / ${{ matrix.flat.runtime }}
     steps:
       - uses: actions/checkout@v3
-      - run: |
+      - name: Build
+        run: |
           echo "https://github.com/actions/upload-artifact/issues/174" > .workaround-${{ matrix.flat.target }}-${{ matrix.flat.runtime }}.txt
           ${{ format('.{0}{1}', startsWith(matrix.flat.runtime, 'win') && '\' || '/', matrix.flat.exec) }}
         working-directory: ${{ matrix.flat.dir }}

@@ -13,3 +13,12 @@
 [submodule "eng/submodules/silk.net-2.x"]
 	path = eng/submodules/silk.net-2.x
 	url = https://github.com/dotnet/Silk.NET
+[submodule "eng/submodules/openal-soft"]
+	path = eng/submodules/openal-soft
+	url = https://github.com/kcat/openal-soft
+[submodule "eng/submodules/vulkan"]
+	path = eng/submodules/vulkan
+	url = https://github.com/KhronosGroup/Vulkan-Docs.git
+[submodule "eng/submodules/vulkan-headers"]
+	path = eng/submodules/vulkan-headers
+	url = https://github.com/KhronosGroup/Vulkan-Headers.git
@@ -270,4 +270,7 @@
     </ItemGroup>
     <Copy SourceFiles="@(SilkThisRidItems)" DestinationFiles="@(SilkThisRidItems->'$(OutDir)%(TargetPath)')" />
   </Target>
+
+  <!-- DSL dogfooding -->
+  <Import Project="$(MSBuildThisFileDirectory)sources/Core/Core/Silk.NET.Core.targets" Condition="'$(SilkDSLExempt)' != 'true' and '$(SilkNativePackage)' != 'true' and '$(SilkMetapackage)' != 'true'" />
 </Project>
@@ -1,52 +1,46 @@
 <Project>
   <ItemGroup>
     <!-- Common -->
-    <PackageVersion Include="DotNet.ReproducibleBuilds" Version="1.1.1" />
-    <PackageVersion Include="DotNet.ReproducibleBuilds.Isolated" Version="1.1.1" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.4" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
-    <PackageVersion Include="NUnit3TestAdapter" Version="4.6.0" />
-    <PackageVersion Include="NUnit.Analyzers" Version="4.4.0" />
-    <PackageVersion Include="coverlet.collector" Version="6.0.2" />
-    <PackageVersion Include="NUnit" Version="4.2.2" />
-    <PackageVersion Include="xunit" Version="2.9.2" />
-    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
-
+    <PackageVersion Include="DotNet.ReproducibleBuilds" Version="1.2.39" />
+    <PackageVersion Include="DotNet.ReproducibleBuilds.Isolated" Version="1.2.39" />
+    <PackageVersion Include="Microsoft.Build.Tasks.Core" Version="17.14.28" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
+    <PackageVersion Include="NAudio.Core" Version="2.2.1" />
+    <PackageVersion Include="NUnit3TestAdapter" Version="5.2.0" />
+    <PackageVersion Include="NUnit.Analyzers" Version="4.11.2" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
+    <PackageVersion Include="NUnit" Version="4.4.0" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
     <!-- eng/benchmarks -->
-    <PackageVersion Include="BenchmarkDotNet" Version="0.14.0" />
-
+    <PackageVersion Include="BenchmarkDotNet" Version="0.15.6" />
     <!-- Silk.NET.Core -->
-    <PackageVersion Include="Fody" Version="6.8.2" PrivateAssets="all" />
-    <PackageVersion Include="InlineIL.Fody" Version="1.9.0" PrivateAssets="all" />
-
+    <PackageVersion Include="Fody" Version="6.9.3" PrivateAssets="all" />
+    <PackageVersion Include="InlineIL.Fody" Version="1.10.1" PrivateAssets="all" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="5.0.0-1.25277.114" />
     <!-- Analyzers -->
-    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
-
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.12.0-beta1.25218.8" />
     <!-- SilkTouch -->
-    <PackageVersion Include="ClangSharp.PInvokeGenerator" Version="18.1.0.2" />
+    <PackageVersion Include="ClangSharp.PInvokeGenerator" Version="20.1.2.4" />
     <PackageVersion Include="CSharpier.Core" Version="0.30.2" />
     <PackageVersion Include="Humanizer.Core" Version="2.14.1" />
-    <PackageVersion Include="Microsoft.Build.Locator" Version="1.7.8" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.11.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.CommandLine" Version="8.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="8.0.0" />
-    <PackageVersion Include="Microsoft.VisualStudio.Setup.Configuration.Interop" Version="3.12.2149" />
+    <PackageVersion Include="Microsoft.Build.Locator" Version="1.10.12" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.CommandLine" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.VisualStudio.Setup.Configuration.Interop" Version="3.14.2075" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
-    <PackageVersion Include="System.IO.Hashing" Version="9.0.0" />
-
-    <!-- This is not used but it is used transitively and the version pulled in has a vulnerability -->
-    <PackageVersion Include="System.Formats.Asn1" Version="9.0.0" />
-
+    <PackageVersion Include="System.IO.Hashing" Version="10.0.0" />
     <!-- SilkTouch Unit Tests -->
     <PackageVersion Include="Silk.NET.BuildTools" Version="2.22.0" />
-    <PackageVersion Include="System.Linq.Async" Version="6.0.1" />
+    <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
     <PackageVersion Include="Verify.DiffPlex" Version="3.1.2" />
-    <PackageVersion Include="Verify.NUnit" Version="28.3.2" />
+    <PackageVersion Include="Verify.NUnit" Version="31.6.0" />
   </ItemGroup>
 </Project>
@@ -102,6 +102,22 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Windowing", "Windowing", "{
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Silk.NET.Windowing", "sources\Windowing\Windowing\Silk.NET.Windowing.csproj", "{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Vulkan", "Vulkan", "{5E20252F-E2A0-46C9-BBEF-4CE5C96D0E07}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Silk.NET.Vulkan", "sources\Vulkan\Vulkan\Silk.NET.Vulkan.csproj", "{E5E8FFBF-1319-4D33-B084-E732656E8A04}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "OpenAL", "OpenAL", "{AF13F7C9-4EE2-403E-B3D2-C4C2E45D9EF3}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Silk.NET.OpenAL", "sources\OpenAL\OpenAL\Silk.NET.OpenAL.csproj", "{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{6077EDD4-F16F-4CA4-B72E-E4627D64B104}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "CSharp", "CSharp", "{12B4D1CB-8938-4EC4-8895-79C4E6ABD1E8}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "OpenAL", "OpenAL", "{662A1AEC-91F2-48FA-AA29-6F27038D30F2}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Tutorial001.HelloSound", "examples\CSharp\OpenAL\Tutorial001.HelloSound\Tutorial001.HelloSound.csproj", "{946C912C-5BBB-446A-A566-0D1696D19F59}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -168,7 +184,19 @@ Global
 		{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}.Release|Any CPU.Build.0 = Release|Any CPU
-	EndGlobalSection
+		{E5E8FFBF-1319-4D33-B084-E732656E8A04}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E5E8FFBF-1319-4D33-B084-E732656E8A04}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E5E8FFBF-1319-4D33-B084-E732656E8A04}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E5E8FFBF-1319-4D33-B084-E732656E8A04}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9}.Release|Any CPU.Build.0 = Release|Any CPU
+		{946C912C-5BBB-446A-A566-0D1696D19F59}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{946C912C-5BBB-446A-A566-0D1696D19F59}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{946C912C-5BBB-446A-A566-0D1696D19F59}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{946C912C-5BBB-446A-A566-0D1696D19F59}.Release|Any CPU.Build.0 = Release|Any CPU
+    EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
@@ -200,6 +228,13 @@ Global
 		{F16C0AB9-DE7E-4C09-9EE9-DAA8B8E935A6} = {EC4D7B06-D277-4411-BD7B-71A6D37683F0}
 		{FE4414F8-5370-445D-9F24-C3AD3223F299} = {DD29EA8F-B1A6-45AA-8D2E-B38DA56D9EF6}
 		{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E} = {FE4414F8-5370-445D-9F24-C3AD3223F299}
+		{AF13F7C9-4EE2-403E-B3D2-C4C2E45D9EF3} = {DD29EA8F-B1A6-45AA-8D2E-B38DA56D9EF6}
+		{1FFFDD72-D023-441C-AF49-F1EA78FF7DE9} = {AF13F7C9-4EE2-403E-B3D2-C4C2E45D9EF3}
+		{12B4D1CB-8938-4EC4-8895-79C4E6ABD1E8} = {6077EDD4-F16F-4CA4-B72E-E4627D64B104}
+		{662A1AEC-91F2-48FA-AA29-6F27038D30F2} = {12B4D1CB-8938-4EC4-8895-79C4E6ABD1E8}
+		{946C912C-5BBB-446A-A566-0D1696D19F59} = {662A1AEC-91F2-48FA-AA29-6F27038D30F2}
+		{5E20252F-E2A0-46C9-BBEF-4CE5C96D0E07} = {DD29EA8F-B1A6-45AA-8D2E-B38DA56D9EF6}
+		{E5E8FFBF-1319-4D33-B084-E732656E8A04} = {5E20252F-E2A0-46C9-BBEF-4CE5C96D0E07}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {78D2CF6A-60A1-43E3-837B-00B73C9DA384}

@@ -59,7 +59,7 @@ command like
 where the values for the `-s` arguments are replaced with the job names (the keys of the `Jobs` dictionary in
 `generator.json` e.g. `SDL`, `OpenGL`, etc).
 
-For more information on SilkTocuh arguments, consult the [SilkTouch User Guide](../silktouch) or use
+For more information on SilkTouch arguments, consult the [SilkTouch User Guide](../silktouch) or use
 `dotnet run --project sources/SilkTouch/SilkTouch/Silk.NET.SilkTouch.csproj -- --help`.
 
 <DocCardList items={useCurrentSidebarCategory().items.filter((e) => e.label != "Overview")} />
@@ -0,0 +1,131 @@
+# Static vs Input Bindings
+
+## Overview
+
+Silk.NET has multiple ways to access the underlying APIs, either through a static method (e.g. `GL.GenBuffers`) or
+through an "API object" (e.g. created with `GL.Create` and then accessed as `gl.GenBuffers`). Not all APIs are the
+same, and some are better accessed through one method or the other. Note that Silk.NET does make both available however,
+so if you're prefer consistency feel free to pick one method and stick to it, though you may result in some minor
+inefficiencies.
+
+All native APIs are accessed using a "function pointer" - a location in memory at which the native code resides.
+This is typically fetched using `DllImport`, but some APIs require custom mechanisms. An example in OpenGL, where you
+must use a "context API" (e.g. WGL, GLX, EGL, etc) to create a context and, after setting up that context state, use a
+function provided by that context API to get the function pointers for OpenGL (e.g. `wglGetProcAddress`). We refer to
+these as "stateful APIs" in this document. Note that OpenGL is not the only stateful API, this will be elaborated later.
+
+Stateless APIs are those where the function pointers aren't contingent on any other state, and they're effectively
+accessed as if they were static functions. For these, the function pointers are typically retrieved through `DllImport`,
+but this needn't preclude other APIs from having bespoke mechanisms to statelessly retrieve function pointers (though,
+there are no examples of this today).
+
+When using a stateful API, you should use API objects if possible i.e. `API.Create`, and dispose of that object when you
+are done using that API. When using a stateless API, you should use the static functions exposed directly on the API
+class.
+
+> [!NOTE]
+> Future releases of Silk.NET are intended to contain analysers to indicate the correct access method.
+
+Below is a description of the stateful APIs. All other APIs not listed here are, or can be treated as, stateless.
+
+## OpenGL
+
+OpenGL is a stateful API because it requires a context to be created and "made current" on that thread before function
+pointers can be retrieved. Typically, this context is created using Silk.NET.Windowing, and the functions would be
+retrieved using `surface.OpenGL.GetProcAddress` in that example.
+
+To create an API object, our OpenGL bindings provide a utility function `CreateOpenGL`:
+```csharp
+IGL gl = null!;
+surface.Created += _ =>
+{
+    gl = surface.CreateOpenGL();
+    // Use gl functions here...
+    gl.Flush();
+}
+surface.Render += _ =>
+{
+    // Use gl functions here...
+    gl.Clear(ClearBufferMask.ColorBufferBit);
+}
+```
+
+If you'd prefer to use static methods despite OpenGL being stateful, the static functions on `GL` will forward to
+`GL.ThisThread`, which essentially forwards to a thread-specific `IGL` instance. You can change the `IGL` instance used
+by a thread using `GL.ThisThread.MakeCurrent`, which will also implicitly make the `IGLContext` you pass it current
+(if applicable). Note that Silk.NET.Windowing will implicitly call this, so you can use the static OpenGL functions in
+the obvious way, albeit with the implied indirection through `GL.ThisThread`:
+```csharp
+surface.Created += _ =>
+{
+    GL.Flush();
+}
+surface.Render += _ =>
+{
+    GL.Clear(ClearBufferMask.ColorBufferBit);
+}
+```
+
+> [!CAUTION]
+> TODO: Silk.NET.Windowing does not currently do this! `surface.MakeCurrent()` must be used in `surface.Created` to make
+> this happen.
+
+## Vulkan
+
+Vulkan is a stateful API because its function pointers are dependent on the `InstanceHandle` and `DeviceHandle` being
+used. Our Vulkan bindings intercept calls to `Vk.CreateInstance` and `Vk.CreateDevice`, and set `CurrentInstance` and
+`CurrentDevice` respectively on the Vulkan API object for later use with `Vk.GetDeviceProcAddr` and
+`Vk.GetInstanceProcAddr`.
+
+The Vulkan API object will first try `vkGetDeviceProcAddr` to load a function pointer (where the value for `device` is
+as in `CurrentDevice`), followed by `vkGetInstanceProcAddr` (where the value for `instance` is as in `CurrentInstance`).
+For `vkGetInstanceProcAddr` itself, `DllImport` is used.
+
+`CurrentInstance` is set upon a successful call to `vkCreateInstance`, and `CurrentDevice` is set upon a successful call
+to `vkCreateDevice`. Note that it is illegal to change these values on an API object if they're already set, if you have
+scenarios requiring multiple instance-device combinations you must create multiple API objects.
+
+> [!TIP]
+> In cases where you have one instance from which multiple devices are created, simply clone the `IVk` object using
+> `IVk.Clone()` prior to **any device** being created. This will reuse the function pointers already loaded for that
+> instance.
+
+If you'd prefer to use static methods despite Vulkan being stateful, the static functions on `Vk` will forward to
+`Vk.ThisThread`, which essentially forwards to a thread-specific `IVk` instance. You can change the `IVk` instance used
+by a thread using `Vk.ThisThread.MakeCurrent`. The static functions, much like using a single `IVk` instance, will throw
+if multiple instance-device combinations are used on the same thread without changing the `IVk` object being used.
+
+## OpenXR
+
+OpenXR has the same caveats as Vulkan but with `CurrentInstance` only.
+
+## OpenAL
+
+OpenAL has the same caveats as OpenGL, with the exception that `alGetProcAddress` is made available to retrieve the
+function pointers. This still has the requirement of a thread-specific context, however, which can be made current using
+`AL.ThisThread.MakeCurrent`.
+
+Unlike OpenGL, OpenAL has an official context API: OpenAL Context (ALC). `alcMakeContextCurrent` will implicitly call
+`AL.ThisThread.MakeCurrent` meaning that the static OpenAL functions are made available in the obvious way:
+
+```csharp
+// NOTE: We are making use of ALContext's static functions here as well.
+// The same applies as if `ALContext.Create` were used.
+DeviceHandle device = ALContext.OpenDevice("");
+if (device == nullptr) throw new("failed to create device");
+
+ContextHandle context = ALContext.CreateContext(device, nullptr);
+if (context == nullptr) throw new("failed to create context");
+
+// Now make the context current. This implicitly calls AL.ThisThread.MakeCurrent
+ALContext.MakeContextCurrent(context);
+
+// Static functions now just work.
+var source = AL.GenSource();
+```
+
+## OpenAL Context (ALContext/ALC)
+
+ALC has the same caveats as Vulkan, given that the ALC function pointers are tied to a specific device. As a result,
+`alcOpenDevice` is intercepted to set the value of `CurrentDevice` to then be fed into `alcGetProcAddress` (or
+`alcGetProcAddress2` if available).
@@ -2,7 +2,7 @@
 
     <PropertyGroup>
         <OutputType>Exe</OutputType>
-        <TargetFramework>net8.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <DefineConstants>$(DefineConstants);MATHF</DefineConstants>
     </PropertyGroup>