Finish documenting API & split out files

Author: Perksey

sources/Input/Input/Button.cs

@@ -0,0 +1,23 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Represents a button the user can push.
+/// </summary>
+/// <param name="Name">The name of the button.</param>
+/// <param name="IsDown">Whether the user is pushing the button.</param>
+/// <param name="Pressure">
+/// The pressure with which the user is pushing the button, where <c>0.0</c> is the smallest measurable pressure and
+/// <c>1.0</c> is the largest measurable pressure.
+/// </param>
+/// <typeparam name="T">
+/// The button type (e.g. <see cref="JoystickButton"/>, <see cref="PointerButton"/>, etc).
+/// </typeparam>
+public readonly record struct Button<T>(T Name, bool IsDown, float Pressure) where T : struct, Enum
+{
+    /// <summary>
+    /// Collapses this <see cref="Button{T}"/> struct into just its <see cref="IsDown"/> value.
+    /// </summary>
+    /// <param name="state">The button state.</param>
+    /// <returns>The <see cref="IsDown"/> value.</returns>
+    public static implicit operator bool(Button<T> state) => state.IsDown;
+}

sources/Input/Input/ButtonChangedEvent.cs

@@ -0,0 +1,15 @@
+using System.Diagnostics;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Contains information pertaining to a button state change (e.g. press, depress, etc).
+/// </summary>
+/// <param name="Device">The device on which the button being pressed or depressed resides.</param>
+/// <param name="Timestamp">
+/// The timestamp (as retrieved from <see cref="Stopwatch.GetTimestamp"/>) at which the event occurred.
+/// </param>
+/// <param name="Button">The new state of the button being pressed or depressed.</param>
+/// <param name="Previous">The previous state of the button.</param>
+/// <typeparam name="T">The button type e.g. <see cref="JoystickButton"/>, <see cref="PointerButton"/>, etc.</typeparam>
+public readonly record struct ButtonChangedEvent<T>(IButtonDevice<T> Device, long Timestamp, Button<T> Button, Button<T> Previous) where T : struct, Enum;

sources/Input/Input/ButtonReadOnlyList.cs

@@ -0,0 +1,24 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// An implementation of <see cref="IReadOnlyList{T}"/> providing utility APIs for getting a <see cref="Button{T}"/>
+/// given a button name <typeparamref name="T"/>, that is optimised for storing <see cref="Button{T}"/>s with the
+/// given button name type <typeparamref name="T"/> using the most memory-efficient mechanism available.
+/// </summary>
+/// <typeparam name="T">
+/// The button type (e.g. <see cref="JoystickButton"/>, <see cref="PointerButton"/>, etc).
+/// </typeparam>
+public struct ButtonReadOnlyList<T> : IReadOnlyList<Button<T>> where T : struct, Enum
+{
+    /// <summary>
+    /// Creates an <see cref="ButtonReadOnlyList{T}"/> from a <see cref="IReadOnlyList{T}"/>.
+    /// </summary>
+    /// <param name="other">The list to copy.</param>
+    public ButtonReadOnlyList(IReadOnlyList<Button<T>> other);
+
+    /// <summary>
+    /// Gets the state for the button with the given name.
+    /// </summary>
+    /// <param name="name">The button name.</param>
+    public Button<T> this[T name] { get; }
+}

sources/Input/Input/ConnectionEvent.cs

@@ -0,0 +1,13 @@
+using System.Diagnostics;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Contains information pertaining to a device connection or disconnection event.
+/// </summary>
+/// <param name="Device">The device that has disconnected or connected.</param>
+/// <param name="Timestamp">
+/// The timestamp (as retrieved from <see cref="Stopwatch.GetTimestamp"/>) at which the event occurred.
+/// </param>
+/// <param name="IsConnected">Whether the device has connected (<c>true</c>) or disconnected (<c>false</c>).</param>
+public readonly record struct ConnectionEvent(IInputDevice Device, long Timestamp, bool IsConnected);

sources/Input/Input/CursorModes.cs

@@ -0,0 +1,57 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Enumerates the modes in which a mouse cursor can operate.
+/// </summary>
+/// <remarks>
+/// <see cref="IPointerDevice"/> implementations for <see cref="IMouse"/> implementations typically have two
+/// <see cref="IPointerDevice.Targets"/>:
+/// <list type="bullet">
+/// <item>
+/// <term>Bounded <see cref="IPointerTarget"/></term>
+/// <description>
+/// An <see cref="IPointerTarget"/> that is bounded to the desktop environment i.e. the
+/// <see cref="IPointerTarget.Bounds"/> are not infinite and reflect the total screen space that is available to the
+/// running application in window coordinates. This is typically the sum of all monitor resolutions, with the positions
+/// being defined using an implementation-defined mechanism. The window bounds operate in this same coordinate space.
+/// It is highly unlikely that you will be unable to determine the individual points for multiple mice on this target,
+/// as desktop environments typically aggregate all movement from all mice into a single <see cref="TargetPoint"/>.
+/// This target is used for every cursor mode except <see cref="Unbounded"/>.
+/// </description>
+/// </item>
+/// <item>
+/// <term>Unbounded <see cref="IPointerTarget"/></term>
+/// <description>
+/// An <see cref="IPointerTarget"/> that is unbounded and operates in an arbitrary coordinate space. This target is used
+/// for <b>raw mouse mode</b> and points on this target represent the net mouse movement from a mouse. Implementations
+/// are more likely to be able to give multiple <see cref="TargetPoint"/>s for each mouse when this target is used. This
+/// target is used when the <see cref="Unbounded"/> cursor mode is enabled. <see cref="IPointerTarget.Bounds"/> will
+/// represent an infinitely large unbounded target.
+/// </description>
+/// </item>
+/// </list>
+/// </remarks>
+[Flags]
+public enum CursorModes
+{
+    /// <summary>
+    /// The cursor is visible to the user and operating within the bounds of the <b>desktop environment</b>. The
+    /// coordinates received are in desktop coordinates, operating in the same coordinate space as the window
+    /// position/size.
+    /// </summary>
+    Normal = 1 << 0,
+
+    /// <summary>
+    /// The cursor is visible to the user but is constrained to the <b>window's client area</b>. The coordinates
+    /// received are in desktop coordinates, operating in the same coordinate space as the window position/size.
+    /// The <see cref="IPointerTarget"/> bounded to the desktop environment is used.
+    /// </summary>
+    Confined = 1 << 1,
+
+    /// <summary>
+    /// The cursor is invisible to the user and is <b>unconstrained/unbounded</b>. The coordinates received are
+    /// arbitrary values that have no bounds representing the net mouse movement since entering into this cursor mode.
+    /// The unbounded <see cref="IPointerTarget"/> is used. This is the equivalent of <b>raw mouse mode</b>.
+    /// </summary>
+    Unbounded = 1 << 2,
+}

sources/Input/Input/CursorStyles.cs

@@ -0,0 +1,61 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Enumerates the cursor styles with which the desktop environment should render the cursor.
+/// </summary>
+[Flags]
+public enum CursorStyles
+{
+    /// <summary>
+    /// The cursor should be rendered using its default image.
+    /// </summary>
+    Default,
+
+    /// <summary>
+    /// The cursor should be rendered using an arrow cursor image.
+    /// </summary>
+    Arrow = 1 << 0,
+
+    /// <summary>
+    /// The cursor should be rendered using an I-beam cursor image, which is used to show where the text cursor appears
+    /// when the mouse is clicked.
+    /// </summary>
+    IBeam = 1 << 1,
+
+    /// <summary>
+    /// The cursor should be rendered using a crosshair cursor image.
+    /// </summary>
+    Crosshair = 1 << 2,
+
+    /// <summary>
+    /// The cursor should be rendered using a hand cursor image, typically used when hovering over a web link.
+    /// </summary>
+    Hand = 1 << 3,
+
+    /// <summary>
+    /// The cursor should be rendered using a two-headed horizontal sizing cursor image.
+    /// </summary>
+    HResize = 1 << 4,
+
+    /// <summary>
+    /// The cursor should be rendered using a two-headed vertical sizing cursor image.
+    /// </summary>
+    VResize = 1 << 5,
+
+    /// <summary>
+    /// The cursor should not be rendered.
+    /// </summary>
+    /// <remarks>
+    /// When <see cref="CursorModes.Unbounded"/> is used, the cursor ceases to exist anyway. As such, while the
+    /// <see cref="ICursorConfiguration.Style"/> property may not reflect this (as it is retained across changes to
+    /// <see cref="ICursorConfiguration.Mode"/> and just ignored when <see cref="CursorModes.Unbounded"/> is used),
+    /// <see cref="ICursorConfiguration.Style"/> can be implied as being <see cref="CursorStyles.Hidden"/> when
+    /// <see cref="CursorModes.Unbounded"/> is used.
+    /// </remarks>
+    Hidden = 1 << 6,
+
+    /// <summary>
+    /// The cursor should be rendered using a custom application-provided image.
+    /// </summary>
+    Custom = 1 << 7,
+}

sources/Input/Input/CustomCursor.cs

@@ -0,0 +1,22 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Represents a custom image for a mouse cursor.
+/// </summary>
+public readonly ref struct CustomCursor
+{
+    /// <summary>
+    /// The number of pixels in the X axis.
+    /// </summary>
+    public int Width { get; init; }
+
+    /// <summary>
+    /// The number of pixels in the Y axis.
+    /// </summary>
+    public int Height { get; init; }
+
+    /// <summary>
+    /// The row-major 32-bit RGBA pixel data (i.e. 8 bytes for each colour component).
+    /// </summary>
+    public ReadOnlySpan<int> Data { get; init; } // Rgba32
+}

sources/Input/Input/DualReadOnlyList.cs

@@ -0,0 +1,39 @@
+using System.Collections;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Represents a list that has exactly two elements.
+/// </summary>
+/// <typeparam name="T">The element type.</typeparam>
+public readonly struct DualReadOnlyList<T> : IReadOnlyList<T>
+{
+    /// <summary>
+    /// The first/leftmost element.
+    /// </summary>
+    public readonly T Left;
+
+    /// <summary>
+    /// The second/rightmost element.
+    /// </summary>
+    public readonly T Right;
+
+    /// <inheritdoc />
+    public IEnumerator<T> GetEnumerator()
+    {
+        yield return Left;
+        yield return Right;
+    }
+
+    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
+
+    /// <inheritdoc />
+    public int Count => 2;
+
+    /// <inheritdoc />
+    public T this[int index] => index switch {
+        0 => Left,
+        1 => Right,
+        _ => throw new IndexOutOfRangeException()
+    };
+}

sources/Input/Input/GamepadState.cs

@@ -0,0 +1,24 @@
+using System.Numerics;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Contains user input received from an <see cref="IGamepad"/>.
+/// </summary>
+public class GamepadState
+{
+    /// <summary>
+    /// Gets the gamepad button state denoting the buttons being pressed or depressed.
+    /// </summary>
+    public ButtonReadOnlyList<JoystickButton> Buttons { get; }
+
+    /// <summary>
+    /// Gets the state of the twin sticks on the gamepad.
+    /// </summary>
+    public DualReadOnlyList<Vector2> Thumbsticks { get; }
+
+    /// <summary>
+    /// Gets the state of the triggers on the gamepad.
+    /// </summary>
+    public DualReadOnlyList<float> Triggers { get; }
+}

sources/Input/Input/GamepadThumbstickMoveEvent.cs

@@ -0,0 +1,17 @@
+using System.Diagnostics;
+using System.Numerics;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Contains information pertaining to the movement of a thumbstick.
+/// </summary>
+/// <param name="Gamepad">The gamepad on which the thumbstick resides.</param>
+/// <param name="Timestamp">
+/// The timestamp (as retrieved from <see cref="Stopwatch.GetTimestamp"/>) at which the event occurred.
+/// </param>
+/// <param name="Value">
+/// The new position of the thumbstick, where each axis is between <c>-1.0</c> and <c>1.0</c>.
+/// </param>
+/// <param name="Delta">The change in <see cref="Value"/> as a result of this event.</param>
+public readonly record struct GamepadThumbstickMoveEvent(IGamepad Gamepad, long Timestamp, Vector2 Value, Vector2 Delta);

sources/Input/Input/GamepadTriggerMoveEvent.cs

@@ -0,0 +1,17 @@
+using System.Diagnostics;
+
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Contains information pertaining to the movement of a trigger.
+/// </summary>
+/// <param name="Gamepad">The gamepad on which the trigger resides.</param>
+/// <param name="Timestamp">
+/// The timestamp (as retrieved from <see cref="Stopwatch.GetTimestamp"/>) at which the event occurred.
+/// </param>
+/// <param name="Axis">The index of the trigger that has moved.</param>
+/// <param name="Value">
+/// The new value of the trigger, between <c>0.0</c> (fully depressed) and <c>1.0</c> (fully pressed).
+/// </param>
+/// <param name="Delta">The change in <see cref="Value"/> as a result of this event.</param>
+public readonly record struct GamepadTriggerMoveEvent(IGamepad Gamepad, long Timestamp, int Axis, float Value, float Delta);

sources/Input/Input/Gamepads.cs

@@ -0,0 +1,22 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Represents a collection of <see cref="IGamepad"/>s from which input events can be received.
+/// </summary>
+public partial class Gamepads : IReadOnlyList<IGamepad>
+{
+    /// <summary>
+    /// Raised when state pertaining to a pushable button on the gamepad changes (e.g. button up, button down).
+    /// </summary>
+    public event Action<ButtonChangedEvent<JoystickButton>>? ButtonChanged;
+
+    /// <summary>
+    /// Raised when a thumbstick on the gamepad moves.
+    /// </summary>
+    public event Action<GamepadThumbstickMoveEvent>? ThumbstickMove;
+
+    /// <summary>
+    /// Raised when a trigger on the gamepad moves.
+    /// </summary>
+    public event Action<GamepadTriggerMoveEvent>? TriggerMove;
+}

sources/Input/Input/IButtonDevice.cs

@@ -0,0 +1,16 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// Represents an input device that has buttons.
+/// </summary>
+/// <typeparam name="T">The type of buttons the input device has.</typeparam>
+public interface IButtonDevice<T> : IInputDevice where T: struct, Enum
+{
+    /// <summary>
+    /// Gets the current button state for this device.
+    /// </summary>
+    /// <remarks>
+    /// Only updated when <see cref="IInputBackend.Update"/> is called.
+    /// </remarks>
+    ButtonReadOnlyList<T> State { get; }
+}

sources/Input/Input/IButtonInputHandler.cs

@@ -0,0 +1,14 @@
+namespace Silk.NET.Input;
+
+/// <summary>
+/// An <see cref="IInputHandler"/> that also receives <see cref="IButtonDevice{T}"/> events.
+/// </summary>
+/// <typeparam name="T">The device's button type.</typeparam>
+public interface IButtonInputHandler<T> : IInputHandler where T : struct, Enum
+{
+    /// <summary>
+    /// Called when a button's state changes (e.g. button down, button up).
+    /// </summary>
+    /// <param name="event">The event details.</param>
+    void HandleButtonChanged(ButtonChangedEvent<T> @event);
+}