[3.0] Windowing Rewrite

.gitattributes

@@ -23,6 +23,7 @@
 *.sln       text        eol=lf
 *.targets   text        eol=lf
 *.yml       text        eol=lf
+*.hlsl      text        eof=lf
 
 ###############################################################################
 # Set explicit file behavior to:
@@ -53,10 +54,35 @@
 *.7z binary
 *.ttf binary
 *.stout binary
+*.p7s binary
+*.sample binary
+*.nupkg binary
+*.exe binary
+*.idx binary
+*.pack binary
+*.spv binary
+*.lib binary
+*.dylib binary
 *.so binary
 *.dll binary
-*.dylib binary
+*.xcscheme binary
+*.xcworkspacedata binary
+*.pdf binary
+*.pfx binary
+*.metal binary
 *.jar binary
+*.apk binary
+*.aar binary
+*.aidl binary
+*.flata binary
+*.metallib binary
+*.items binary
+*.stamp binary
+*.icns binary
+*.mdb binary
+*.pdb binary
+*.bmp binary
+*.dat binary
 
 # Verify
 *.verified.txt text eol=lf working-tree-encoding=UTF-8

.github/workflows/publish-site.yml

@@ -13,7 +13,15 @@ jobs:
   Build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+      - name: Setup .NET 8
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '8.0.x'
+      - name: Setup .NET 9
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '9.0.102'
       - name: Build Website
         run: |
           git submodule update --init eng/submodules/silk.net-2.x

Directory.Build.props

@@ -67,6 +67,7 @@
     <PackageVersionDependsOn>SilkShippingControl;$(PackageVersionDependsOn)</PackageVersionDependsOn>
     <TargetsForTfmSpecificContentInPackage>SilkNativePackaging;$(TargetsForTfmSpecificContentInPackage)</TargetsForTfmSpecificContentInPackage>
     <GenerateNuspecDependsOn>SilkShippingControl;$(GenerateNuspecDependsOn)</GenerateNuspecDependsOn>
+    <UseMonoRuntime>false</UseMonoRuntime>
   </PropertyGroup>
 
   <!-- SourceLink -->

Directory.Packages.props

@@ -19,6 +19,9 @@
     <PackageVersion Include="Fody" Version="6.8.2" PrivateAssets="all" />
     <PackageVersion Include="InlineIL.Fody" Version="1.9.0" PrivateAssets="all" />
 
+    <!-- Analyzers -->
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
+
     <!-- SilkTouch -->
     <PackageVersion Include="ClangSharp.PInvokeGenerator" Version="18.1.0.2" />
     <PackageVersion Include="CSharpier.Core" Version="0.30.2" />

Silk.NET.sln

@@ -13,6 +13,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		LICENSE.md = LICENSE.md
 		generator.json = generator.json
 		Silk.NET.sln.DotSettings = Silk.NET.sln.DotSettings
+		Directory.Packages.props = Directory.Packages.props
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{9DB0EA3E-7216-4F9C-98F5-8A7483E9F083}"
@@ -97,6 +98,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Win32", "Win32", "{6E739132
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Silk.NET.SDL.Native", "sources\SDL\Native\Silk.NET.SDL.Native.csproj", "{F16C0AB9-DE7E-4C09-9EE9-DAA8B8E935A6}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Windowing", "Windowing", "{FE4414F8-5370-445D-9F24-C3AD3223F299}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Silk.NET.Windowing", "sources\Windowing\Windowing\Silk.NET.Windowing.csproj", "{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -159,6 +164,10 @@ Global
 		{F16C0AB9-DE7E-4C09-9EE9-DAA8B8E935A6}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{F16C0AB9-DE7E-4C09-9EE9-DAA8B8E935A6}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{F16C0AB9-DE7E-4C09-9EE9-DAA8B8E935A6}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EF07CBB5-D253-4CA9-A5DA-8B3DF2B0DF8E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{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
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -189,6 +198,8 @@ Global
 		{6FA628B8-9696-4847-89F9-E58F470AF4FB} = {5CD096DB-6C44-48F1-9093-AD4C84B6B7EC}
 		{6E739132-EEAB-43A5-83C7-EB58C50D03A1} = {DD29EA8F-B1A6-45AA-8D2E-B38DA56D9EF6}
 		{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}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {78D2CF6A-60A1-43E3-837B-00B73C9DA384}

docs/for-contributors/Windowing/Implementations/SDL3/event-pump.md

@@ -0,0 +1,18 @@
+# The Event Pump
+
+The largest influence in the `ISurfaceApplication` design is the fact that for many platforms only the entry thread is
+allowed to interact with the window manager (e.g. for the purposes of events). This creates a problem because rendering
+is very much not single-threaded, nor are most use cases where the user has multiple windows. As such,
+`ISurfaceApplication` gives the implementation freedom to decide what the most appropriate thread is to call into the
+surface to raise events. This is further emphasised by the definition of `ISurfaceChildren` where the user can only
+`Spawn` a surface, and not have a blocking call they can send off to their own thread. This allows the child windows to
+use the same event thread and synchronization. This is likely inconvenient for rendering scenarios though
+(e.g. for OpenGL where it's one thread per context/window, but all surfaces use the same thread by default...), for
+which I expect that we'll add the ability to multithread for certain events in `SurfaceTimingOptions` or
+`SurfaceTickOptions`. This however has been excluded from the initial 3.0 proposal.
+
+Note that `SDL_AppEvent` is only guaranteed to be called on the event thread for events raised by the window
+manager/operating system. As such, we always assume that those events are on the event thread when received and invoke
+the window directly. For other events, we should be wary of concurrency. Note that I have absolutely no idea what this
+means for things like our `Surface.Continue` method for `IsEventDriven` - right now this isn't implemented. Read more
+here: https://github.com/libsdl-org/SDL/issues/11387

docs/for-contributors/Windowing/README.md

@@ -0,0 +1,32 @@
+# Silk.NET.Windowing
+
+Silk.NET.Windowing is our cross-platform windowing abstraction. For more information about what it is, see the [proposal](../../proposals/Proposal%20-%20Windowing%203.0.md).
+
+As per the proposal, Windowing is implemented in exactly one project/assembly containing the abstractions and one
+"reference implementation" given available target information (e.g. TFM). Today, this includes:
+- SDL3, used for every platform.
+
+If the user doesn't want to use our reference implementation, it is expected that they use the trimmer to make its
+presence benign.
+
+Note that for each "reference implementation" it is expected that there shall be a matching Silk.NET.Input "reference
+implementation" capable of receiving an `INativeWindow` from the Silk.NET.Windowing implementation in use. How you
+interpret this requirement is up to you, e.g. we could have a Silk.NET.Input Win32-specific implementation that uses
+`Win32PlatformInfo` for our SDL3 surface, likewise we could have a Silk.NET.Input SDL3 implementation that receives a
+`Win32PlatformInfo` from a Silk.NET.Windowing implementation and automatically creates a wrapping window - this is up to
+you (but try to keep it sane please, that last one sounded extremely cursed). Ultimately, the goal is the user being
+able to pull in `Silk.NET.Windowing` and `Silk.NET.Input`, create a surface, be able to do `surface.CreateInput()` and
+it all Just Work. Right now, this equates to a 1:1 match of Silk.NET.Windowing/Silk.NET.Input implementations, and is
+not expected to change.
+
+Silk.NET.Input is completely independent from Silk.NET.Windowing this time around, unlike 1.X/2.X. This is because we
+believe the Input HLU can target wider applicability beyond just receiving input for a window, with VR being the
+principal use case in mind when making this decision. For more information, read the [Multi-Backend Input proposal](../../proposals/Proposal%20-%20Multi-Backend%20Input.md).
+
+Most of the files within the top-level Windowing directory are exactly as proposed. The exception is the `Surface`
+class, which seeks to make as much common as humanly possible (this includes the Render/Update timing logic and some
+other auxiliary functions). Beyond that, this is functionally an interface. The actual entry-points into the Windowing
+API, `ISurfaceApplication.Run` and `IDetachedSurfaceLifecycle.TryCreate`, are defined `partial`ly with matching
+implementation parts in the `Implementations` subdirectories.
+
+To find out more about the implementation details, see the `Implementations` directory.

docs/for-contributors/Windowing/future-improvements.md

@@ -0,0 +1,87 @@
+# Future Improvements
+
+Initially when we were having design discussions around Silk.NET 3.0's Windowing API, we wanted to introduce a
+lower-level API upon which our high-level API. The idea being that this would be an extensible API for which there would
+be lower implementation friction and delegating common boilerplate code to a common higher-level implementation i.e.
+there's very little work for us to do in mapping our API into new backends. This would functionally be a PAL, but the
+details of this would depend on the actual requirements we derive as part of designing this API. Ultimately it was
+determined that this work was simply out-of-scope for the initial 3.0 release as the extensibility benefits emerging
+from having a lower-level API was determined to not be a requirement for the initial release, and was not included in
+the original Working Group approved software development plan.
+
+We're well aware this sounds very similar to what our friends at OpenTK are planning for 5.0, for much of the same
+reasons. Indeed we still have community members who are also OpenTK community members that were advocating for it for
+this reason. It's great to consider this sort of prior art, the sharing of insights and lifting eachother up is what
+makes open-source amazing after all. We should also consider how other libraries like SDL and GLFW handle this
+internally. Much like OpenTK, there is motivation for adding a lower-level API to Silk.NET to reduce the implementation
+friction in adding more windowing backends as we believe esoteric platforms like mobile could be served well by them.
+Unlike OpenTK, for desktop there's less appetite due to the shear number of platforms that would cause a lot of
+maintenance effort - OpenTK 4.0 moved to use GLFW because of this, and most of the issues logged before this were
+regarding its per-platform custom implementations, whereas Silk.NET 3.0 is keen to optimise for maintainability and
+delegating maintenance effort to more expert sources (as we have done for SilkTouch by using ClangSharp's P/Invoke
+Generator) like SDL is part of this so we can focus on crafting the best user experience specific to our project. Hence
+why even if we would add this lower-level API, unlike OpenTK 5.0 I don't think we'd use it to implement desktop
+windowing ourselves. But that can change after the initial release, and in any case having this lower-level API would be
+useful.
+
+When reviewing OpenTK specifically, their API design is indeed sound however the mechanisms by which it was exposed to
+the higher-level API left a lot to be desired. Namely, using a dictionary of enums to implementations did not feel like
+the best way to do this. There are likely more intelligent things we can do with the type system to make these patterns
+more JIT friendly and also more extensible - having an enum enumerating the component types requires the extensibility
+model to be defined in a way that is contrary to how the type system works e.g. to define components that are extensions
+beyond our standard set. It was also deemed to be desirable to use `static abstract`s for this sort of low-level API,
+which does help towards JIT friendliness, but this needn't prejudice any future efforts towards these goals - this was
+just an idea.
+
+Ultimately, to make our solution more write-once-run-everywhere, the API design philosophy behind the `Surface`
+type was primarily to make it seem like a modular "component bag" e.g. `window.OpenGL` for OpenGL-specific
+functionality, rather than having specific APIs always exposed as part of the standard interface but only valid for
+usage in specific circumstances. The `IView` separation in 2.X achieved what we wanted somewhat, but this again left a
+lot to be desired given that writing against `IView` instead of `IWindow` is contrary to what most users were doing
+(this is also likely a symptom of being an afterthought introduced quite late into the 1.0 Preview cycle). By using this
+design philosophy, our users have to get used to not assuming that functionality is available, meaning that users are
+encouraged to write in a way that is portable instead of them having to go out of their way by writing against `IView`
+as in 1.X and 2.X.
+
+As for the extensibility goals (i.e. additional components being defined on top of our standard API), my hope was to
+eventually have a `GetComponent` API on `Surface` which things like `window.OpenGL` were defined on top of. This has
+been excluded from the 3.0 initial release, but we could in theory add something like this without the PAL concepts in
+this document being implemented - a component-based architecture for our high-level API and a component-based
+architecture for our low-level API can be developed independently. An example of why we might want this is a virtual
+reality extension that manages the creation of OpenXR bindings from a surface, but this is just one example. It is
+possible that "extension everything" might make this easier on the user while also making it easier for us (e.g.
+extension everything defining an `window.OpenXR` property that implicitly checks the component can be created or
+whatever, `DependentHandle` can probably used for this if we wanted or we could just use `window is IMyComponent` -
+again these are all just ideas, this is just to demonstrate the idea of the API shape). Way earlier in 3.0's development
+we were discussing the use of `IDynamicInterfaceCastable`, but the Silk.NET team were not able to implement support for
+this in the Mono runtime in an acceptable timeframe and complexity level. All of these details depend on how and if we
+make it possible to attach components to existing implementations without requiring modification of the original
+backend. I would quite like this to be the case, but again it depends on the nature of the high-level component-based
+architecture and/or the low-level component-based architecture i.e. where is the extensibility point.
+
+As much as we didn't continue down the path illustrated in this document, it was certainly explored somewhat before we
+decided it wasn't needed for 3.0 (engineers like to overengineer, go figure). The first exploration was essentially a
+static dependency injection API i.e. a [`IHluComponentRegistry`](https://github.com/dotnet/Silk.NET/blob/56af8e1b34dc41a43de10dff45d09d25f12e8e57/sources/Core/Core/Abstractions/IHluComponentRegistry.cs)
+provides components (these can be changed together for extensibility) that configures a [`Surface`](https://github.com/dotnet/Silk.NET/blob/56af8e1b34dc41a43de10dff45d09d25f12e8e57/sources/Windowing/Common/Surface.cs)
+(well, a [`IHluComponentHost`](https://github.com/dotnet/Silk.NET/blob/56af8e1b34dc41a43de10dff45d09d25f12e8e57/sources/Core/Core/Abstractions/IHluComponentHost.cs)
+which `Surface` implements) with the components. There was also some [source generator magic](https://github.com/dotnet/Silk.NET/blob/56af8e1b34dc41a43de10dff45d09d25f12e8e57/sources/Core/Analyzers/HluSourceGenerator.Hosts.cs)
+explored to make this more JIT friendly, but that itself had some downsides e.g. one object being an implementation type
+of multiple component types had two references stored in the surface. These problems aren't insurmountable but
+ultimately it was determined that making an entire dependency injection API just for this was a bit silly.
+
+After this attempt at implementing these concepts, another attempt was made that encompassed the low-level API desired
+to reduce implementation friction. Essentially, [`ISurfaceHost`](https://github.com/dotnet/Silk.NET/blob/129d4957ce1058252723add2f6890fb53f234432/sources/Windowing/Common/Hosting/ISurfaceHost.cs)
+had a bunch of lower-level APIs as `static abstract`s that essentially boiled down to "get a property, set a property"
+on surface objects or surface requests. Didn't quite get round to implementing the "additional component" extensibility
+concepts described but this could likely be done using type chaining and essentially changing those get/set property
+methods to accept a generic "property type", but again these are just ideas - this was never realised or prototyped.
+This was progressing well enough, and had some decent benefits as well like centralising all the [multi-threading logic](https://github.com/dotnet/Silk.NET/blob/129d4957ce1058252723add2f6890fb53f234432/sources/Windowing/Common/Hosting/MultiThreadedSurfaceHost%601.cs)
+at the lowest level of implementation.
+
+All in all, there's a lot of benefits to having a modular, component-based, and extensible approach to designing our
+windowing API and this is definitely something we're keen to pursue. But for now, we determined that for the 3.0 initial
+release we only needed to do this for the user-facing API (as per the goals stated in the SDP to make the API more
+encouraging of write-once-run-everywhere) and as much as we want to fulfill that `GetComponent` extensibility vision to
+allow extensions of our standard API set, that also isn't needed for the initial release. Nonetheless, it was key to
+ensure we had enough jumping off points to ensure this can be implemented in the future, and also to implement the
+lower-level, implementation-facing API to make our life easier if we did want to add more backends outside of SDL.

eng/silktouch/sdl/SDL3/generate.rsp

@@ -9,6 +9,9 @@ SDL_memmove
 SDL_memset
 SDL_BeginThreadFunction
 SDL_EndThreadFunction
+SDL_fabsf
+SDL_size_add_check_overflow_builtin
+SDL_size_mul_check_overflow_builtin
 --file
 sdl-SDL.h
 --methodClassName
@@ -32,6 +35,7 @@ Silk.NET.SDL
 ../../../submodules/sdl/include/SDL3/SDL_events.h
 ../../../submodules/sdl/include/SDL3/SDL_filesystem.h
 ../../../submodules/sdl/include/SDL3/SDL_gamepad.h
+../../../submodules/sdl/include/SDL3/SDL_gpu.h
 ../../../submodules/sdl/include/SDL3/SDL_guid.h
 ../../../submodules/sdl/include/SDL3/SDL_haptic.h
 ../../../submodules/sdl/include/SDL3/SDL_hidapi.h
@@ -45,6 +49,7 @@ Silk.NET.SDL
 ../../../submodules/sdl/include/SDL3/SDL_locale.h
 ../../../submodules/sdl/include/SDL3/SDL_log.h
 ../../../submodules/sdl/include/SDL3/SDL_messagebox.h
+../../../submodules/sdl/include/SDL3/SDL_main.h
 ../../../submodules/sdl/include/SDL3/SDL_metal.h
 ../../../submodules/sdl/include/SDL3/SDL_misc.h
 ../../../submodules/sdl/include/SDL3/SDL_mouse.h
@@ -53,11 +58,13 @@ Silk.NET.SDL
 ../../../submodules/sdl/include/SDL3/SDL_pixels.h
 ../../../submodules/sdl/include/SDL3/SDL_platform.h
 ../../../submodules/sdl/include/SDL3/SDL_power.h
+../../../submodules/sdl/include/SDL3/SDL_process.h
 ../../../submodules/sdl/include/SDL3/SDL_properties.h
 ../../../submodules/sdl/include/SDL3/SDL_rect.h
 ../../../submodules/sdl/include/SDL3/SDL_render.h
 ../../../submodules/sdl/include/SDL3/SDL_scancode.h
 ../../../submodules/sdl/include/SDL3/SDL_sensor.h
+../../../submodules/sdl/include/SDL3/SDL_stdinc.h
 ../../../submodules/sdl/include/SDL3/SDL_storage.h
 ../../../submodules/sdl/include/SDL3/SDL_surface.h
 ../../../submodules/sdl/include/SDL3/SDL_system.h
@@ -67,3 +74,4 @@ Silk.NET.SDL
 ../../../submodules/sdl/include/SDL3/SDL_touch.h
 ../../../submodules/sdl/include/SDL3/SDL_version.h
 ../../../submodules/sdl/include/SDL3/SDL_video.h
+../../../submodules/sdl/include/SDL3/SDL_vulkan.h

eng/silktouch/sdl/SDL3/sdl-SDL.h

@@ -1 +1,3 @@
 #include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+#include <SDL3/SDL_vulkan.h>

eng/silktouch/sdl/remap.rsp

@@ -1,2 +1,6 @@
 --remap
 SDL_fabsf=float.Abs
+VkSurfaceKHR=ulong
+VkInstance=void*
+VkPhysicalDevice=ulong
+VkAllocationCallbacks=void