Separate files

Author: Perksey

sources/Windowing/Windowing/DisplayAvailabilityChangeEvent.cs

@@ -0,0 +1,12 @@
+/// <summary>
+/// Contains properties pertaining to a display being connected or disconnected.
+/// </summary>
+/// <param name="Surface">The surface for which display(s) were connected.</param>
+/// <remarks>
+/// Old display objects are not guaranteed to be valid or relevant after this event is raised.
+/// </remarks>
+// Currently this event does not include the displays that were connected or disconnected. This is primarily because
+// there's no clean way to expose such "diffs" from an API perspective (as disconnected IDisplay objects are likely to
+// be invalid), and also why would we need to? If a use case arises and this can be implemented in a sound way, let's
+// evaluate that then.
+public readonly record struct DisplayAvailabilityChangeEvent(Surface Surface);

sources/Windowing/Windowing/DisplayChangeEvent.cs

@@ -0,0 +1,13 @@
+/// <summary>
+/// Contains properties pertaining to a surface changing to a different display.
+/// </summary>
+/// <param name="Surface">The surface changing to a different display.</param>
+/// <param name="Display">The display the surface has changed to.</param>
+/// <remarks>
+/// It is expected that this event shall be raised for each logically substantial change to the display parameters and
+/// this can be defined by each individual platform. For instance, if the underlying platform does not give the
+/// application access to any displays other than the one it's currently being displayed on, then it is expected that
+/// this event shall be raised if the display changed even if this is represented by the same object. Old display
+/// objects are not guaranteed to be valid or relevant after this event is raised.
+/// </remarks>
+public readonly record struct DisplayChangeEvent(Surface Surface, IDisplay Display);

sources/Windowing/Windowing/DisplayCoordinatesEvent.cs

@@ -0,0 +1,19 @@
+using Silk.NET.Maths;
+
+/// <summary>
+/// Contains properties pertaining to a change in the location and/or size of a display.
+/// </summary>
+/// <param name="Surface">The surface owning the display.</param>
+/// <param name="Display">The display for which the location and/or size changed.</param>
+/// <param name="OldBounds">The previous value of <see cref="IDisplay.Bounds" />.</param>
+/// <param name="NewBounds">The new value of <see cref="IDisplay.Bounds" />.</param>
+/// <param name="OldWorkArea">The previous value of <see cref="IDisplay.WorkArea" />.</param>
+/// <param name="NewWorkArea">The new value of <see cref="IDisplay.WorkArea" />.</param>
+public readonly record struct DisplayCoordinatesEvent(
+    Surface Surface,
+    IDisplay Display,
+    Rectangle<float> OldBounds,
+    Rectangle<float> NewBounds,
+    Rectangle<float> OldWorkArea,
+    Rectangle<float> NewWorkArea
+);

sources/Windowing/Windowing/DisplayVideoModeAvailabilityChangeEvent.cs

@@ -0,0 +1,10 @@
+/// <summary>
+/// Contains properties pertaining to a change in the available video modes for a display.
+/// </summary>
+/// <param name="Surface">The surface owning the display.</param>
+/// <param name="Display">The display for which the video mode availability changed.</param>
+// I don't think we need to have a diff here either, why would old video modes be relevant?
+public readonly record struct DisplayVideoModeAvailabilityChangeEvent(
+    Surface Surface,
+    IDisplay Display
+);

sources/Windowing/Windowing/IDisplay.cs

@@ -0,0 +1,52 @@
+using Silk.NET.Maths;
+
+/// <summary>
+/// Represents a display on which a surface can be rendered.
+/// </summary>
+/// <remarks>
+/// These objects may be shared with child windows created using <see cref="ISurfaceChildren" /> and vice versa i.e.
+/// this object can be shared between all surfaces that share a common ancestor (the "root surface"). Beyond that, these
+/// objects are not guaranteed to be valid across surfaces. This allows one event handler to enact changes on multiple
+/// surfaces.
+/// </remarks>
+public interface IDisplay
+{
+    /// <summary>
+    /// Gets the position and resolution of the monitor in screen space.
+    /// </summary>
+    Rectangle<float> Bounds { get; }
+
+    /// <summary>
+    /// Gets the area within <see cref="Bounds" /> where surfaces are <i>intended</i> to be drawn.
+    /// </summary>
+    /// <remarks>
+    /// This typically is the area left once you account for things like the menu bar and taskbar.
+    /// </remarks>
+    Rectangle<float> WorkArea { get; }
+
+    /// <summary>
+    /// Gets a list of video modes known to be available when this display is <see cref="ISurfaceDisplay.Current" />.
+    /// It may be the case that a list of video modes can't be determined until that's the case.
+    /// </summary>
+    IReadOnlyList<VideoMode>? KnownVideoModes { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the user has designated this display their primary display.
+    /// </summary>
+    bool IsPrimary { get; }
+
+    /// <summary>
+    /// Gets a colloquial name for the display. This may change, but hopefully not to something the end user won't recognise.
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// An event raised when <see cref="Bounds" /> and/or <see cref="WorkArea" /> changes.
+    /// </summary>
+    event Action<DisplayCoordinatesEvent>? CoordinatesChanged;
+
+    /// <summary>
+    /// An event raised when <see cref="KnownVideoModes" /> changes.
+    /// </summary>
+    event Action<DisplayVideoModeAvailabilityChangeEvent>? KnownVideoModesChanged;
+}

sources/Windowing/Windowing/ISurfaceApplication.cs

@@ -0,0 +1,26 @@
+using System.Runtime.Versioning;
+
+/// <summary>
+/// Represents an application running within a surface.
+/// </summary>
+public interface ISurfaceApplication
+{
+    /// <summary>
+    /// An optional window class.
+    /// </summary>
+    static virtual string? WindowClass => null;
+
+    /// <summary>
+    /// Called upon initialization of the application.
+    /// </summary>
+    static abstract void Initialize<TSurface>(TSurface surface)
+        where TSurface : Surface;
+
+    /// <summary>
+    /// Runs an application using the reference implementation of Silk.NET.Windowing.
+    /// </summary>
+    /// <typeparam name="T">The application.</typeparam>
+    [UnsupportedOSPlatform("android")]
+    public static sealed void Run<T>()
+        where T : ISurfaceApplication => throw new NotImplementedException();
+}

sources/Windowing/Windowing/ISurfaceChildren.cs

@@ -0,0 +1,12 @@
+/// <summary>
+/// Provides the ability to spawn children surfaces.
+/// </summary>
+public interface ISurfaceChildren
+{
+    /// <summary>
+    /// Spawns an application to run within a new child surface. This call shall not block.
+    /// </summary>
+    /// <typeparam name="T">The application to run within the child surface.</typeparam>
+    void Spawn<T>()
+        where T : ISurfaceApplication;
+}

sources/Windowing/Windowing/ISurfaceDisplay.cs

@@ -0,0 +1,45 @@
+/// <summary>
+/// Provides the ability to configure displays on which the surface can render.
+/// </summary>
+public interface ISurfaceDisplay
+{
+    /// <summary>
+    /// Gets or sets display on which the surface is currently rendering. If setting, <c>value</c> must be contained in
+    /// <see cref="Available" />.
+    /// </summary>
+    IDisplay Current { get; set; }
+
+    /// <summary>
+    /// Gets a list of other displays that this surface can be moved to. If the surface cannot be programmatically moved
+    /// to another display, it is expected that this shall return a single element list containing
+    /// <see cref="Current" />.
+    /// </summary>
+    IReadOnlyList<IDisplay> Available { get; }
+
+    /// <summary>
+    /// Gets or sets the video mode with which the surface is being rendered to the display. If setting, <c>value</c>
+    /// must be contained in <see cref="AvailableVideoModes" />.
+    /// </summary>
+    VideoMode VideoMode { get; set; }
+
+    /// <summary>
+    /// Gets a list of video modes with which the surface can be rendered. If the surface cannot programmatically change
+    /// its video mode, it is expected that this shall return a single element list containing <see cref="VideoMode" />.
+    /// </summary>
+    IReadOnlyList<VideoMode> AvailableVideoModes { get; }
+
+    /// <summary>
+    /// An event raised when <see cref="Current" /> changes.
+    /// </summary>
+    event Action<DisplayChangeEvent>? CurrentDisplayChanged;
+
+    /// <summary>
+    /// An event raised when <see cref="Available" /> changes.
+    /// </summary>
+    event Action<DisplayAvailabilityChangeEvent>? AvailableChanged;
+
+    /// <summary>
+    /// An event raised when <see cref="AvailableVideoModes" /> changes.
+    /// </summary>
+    event Action<DisplayVideoModeAvailabilityChangeEvent>? AvailableVideoModesChanged;
+}

sources/Windowing/Windowing/ISurfaceOpenGL.cs

@@ -0,0 +1,124 @@
+using Silk.NET.Maths;
+
+/// <summary>
+/// The OpenGL component of a <see cref="Surface" />. The <see cref="IGLContext" /> methods can only be executed once
+/// <see cref="ISurfaceApplication.Initialize{TSurface}" /> has executed.
+/// </summary>
+/// <remarks>
+/// These objects may be shared with child windows created using <see cref="ISurfaceChildren" /> and vice versa i.e.
+/// this object can be shared between all surfaces that share a common ancestor (the "root surface"). Beyond that, these
+/// objects are not guaranteed to be valid across surfaces. This allows one event handler to enact changes on multiple
+/// surfaces. This is important for <see cref="SharedContext" /> purposes.
+/// </remarks>
+public interface ISurfaceOpenGL : IGLContext
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether OpenGL support is enabled for this surface. Setting
+    /// <see cref="Profile" /> to a value other than <see cref="OpenGLContextProfile.None" /> will automatically set
+    /// this property to <c>true</c>, and likewise toggling the value assigned to this property will change the value of
+    /// <see cref="Profile" />.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// </remarks>
+    // Included for consistency with Vulkan.
+    bool IsEnabled
+    {
+        get => Profile != OpenGLContextProfile.None;
+        set =>
+            Profile = value
+                ? Profile == OpenGLContextProfile.None
+                    ? OpenGLContextProfile.Default
+                    : Profile
+                : OpenGLContextProfile.None;
+    }
+
+    /// <summary>
+    /// Preferred depth buffer bits of the window's framebuffer.
+    /// </summary>
+    /// <remarks>
+    /// Pass <c>null</c> or <c>-1</c> to use the system default.
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// Setting this property will automatically set <see cref="Profile" /> to
+    /// <see cref="OpenGLContextProfile.Default" /> if it is currently <see cref="OpenGLContextProfile.None" />.
+    /// </remarks>
+    int? PreferredDepthBufferBits { get; set; }
+
+    /// <summary>
+    /// Preferred stencil buffer bits of the window's framebuffer.
+    /// </summary>
+    /// <remarks>
+    /// Pass <c>null</c> or <c>-1</c> to use the system default.
+    /// </remarks>
+    int? PreferredStencilBufferBits { get; set; }
+
+    /// <summary>
+    /// Preferred red, green, blue, and alpha bits of the window's framebuffer.
+    /// </summary>
+    /// <remarks>
+    /// Pass <c>null</c> or <c>-1</c> for any of the channels to use the system default.
+    /// </remarks>
+    Vector4D<int>? PreferredBitDepth { get; set; }
+
+    /// <summary>
+    /// Preferred number of samples for multi-sample anti-aliasing.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// </remarks>
+    int? PreferredSampleCount { get; set; }
+
+    /// <summary>
+    /// The API version to use.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// </remarks>
+    Version32? Version { get; set; }
+
+    /// <summary>
+    /// Flags used to create the OpenGL context.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// </remarks>
+    OpenGLContextFlags Flags { get; set; }
+
+    /// <summary>
+    /// The profile the OpenGL context should use. If <see cref="OpenGLContextProfile.None" /> is used, the OpenGL
+    /// component is effectively disabled, allowing for other graphics APIs/components to be used. If any of the other
+    /// properties on this class are set while this property is <see cref="OpenGLContextProfile.None" />, this property
+    /// shall automatically be populated with the value <see cref="OpenGLContextProfile.Default" />.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method. If the value is
+    /// <see cref="OpenGLContextProfile.Default" />, this shall be replaced with the actual value upon exit from
+    /// <see cref="ISurfaceApplication.Initialize{TSurface}" />.
+    /// </remarks>
+    OpenGLContextProfile Profile { get; set; }
+
+    /// <summary>
+    /// Gets a value indicating whether the current configuration is supported (e.g. version number). If
+    /// <see cref="Profile" /> is not <see cref="OpenGLContextProfile.None" /> and this property is <c>true</c>, the
+    /// OpenGL context shall be created and accessible upon exit from
+    /// <see cref="ISurfaceApplication.Initialize{TSurface}" />.
+    /// </summary>
+    bool IsSupported { get; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the platform should automatically <see cref="IGLContext.SwapBuffers" />
+    /// after <see cref="Surface.Render" />. Defaults to <c>true</c>.
+    /// </summary>
+    /// <remarks>
+    /// This can be set at any point throughout the surface's execution.
+    /// </remarks>
+    bool ShouldSwapAutomatically { get; set; }
+
+    /// <summary>
+    /// Gets or sets the context with which this context should share resources.
+    /// </summary>
+    /// <remarks>
+    /// This can only be set during the <see cref="ISurfaceApplication.Initialize{TSurface}" /> method.
+    /// </remarks>
+    IGLContext? SharedContext { get; set; }
+}

sources/Windowing/Windowing/ISurfaceScale.cs

@@ -0,0 +1,47 @@
+/// <summary>
+/// Provides information pertaining to the surface's graphical scaling.
+/// </summary>
+/// <remarks>
+/// <see cref="ContentScale" /> is typically used to scale UI elements to the correct size for the end user.
+/// <see cref="PixelDensity" /> on the other hand is used to scale the entire application to cover the entire client
+/// area in cases where the window client size is smaller than the actual drawable size (i.e. it is high density).
+/// If scaling content for legibility and scaling the application's rendering as a whole are not needed to be separated,
+/// it is recommended to use <see cref="DrawScale" />. Implementations shall always request a high density surface if
+/// given the choice, to account for the platforms where applications may not be able to opt-out of high density.
+/// </remarks>
+public interface ISurfaceScale
+{
+    /// <summary>
+    /// Gets the factor with which the application should scale its content to make the content more legible for the
+    /// user. This has no influence on <see cref="Surface.DrawableSize" />.
+    /// </summary>
+    /// <seealso cref="DrawScale" />
+    float ContentScale { get; }
+
+    /// <summary>
+    /// Gets the suggested amplification factor when drawing in terms of <see cref="Surface.DrawableSize" />. This
+    /// represents the scale from the pixel resolution to the desired content size, and is typically the multiplication
+    /// of <see cref="PixelDensity" /> and <see cref="ContentScale" />.
+    /// </summary>
+    /// <remarks>
+    /// For example, if <see cref="PixelDensity" /> is <c>2.0</c> (i.e. there are 2 pixels per screen coordinate)
+    /// <i>and</i> the window manager requests that applications scale their content up by <c>2.0</c> to meet the user's
+    /// settings as per <see cref="ContentScale" />, this would be <c>4.0</c>. This is because we're scaling once to
+    /// account for the fact that the application has twice the amount of pixels available to it for the given window
+    /// size, and then scaling again so that what we are drawing appears zoomed in as per the user's request. Note that
+    /// it is rarely the case that an operating system employs both dense pixels <i>and</i> content scale. macOS for
+    /// instance, instead of setting <see cref="ContentScale" />, opts to scale the resolution in the cases where the
+    /// user wants magnified visuals instead of having the applications scale their content; whereas Windows sets
+    /// <see cref="ContentScale" /> and instead always keeps <see cref="PixelDensity" /> as <c>1.0</c>. This is down
+    /// to philosophical differences between the window coordinate systems on platforms as to whether they prefer to
+    /// deal in physical device pixels or physical content sizes.
+    /// </remarks>
+    float DrawScale { get; }
+
+    /// <summary>
+    /// Gets the ratio of pixels rendered to window size. This shall be equivalent to
+    /// <see cref="Surface.DrawableSize" /> divided by <see cref="ISurfaceWindow.ClientSize" />.
+    /// </summary>
+    /// <seealso cref="DrawScale" />
+    float PixelDensity { get; }
+}