Document Input.Common

documentation/proposals/Proposal - Input.md

@@ -49,7 +49,7 @@ public interface IGamepad : IInputDevice
     event Action<IGamepad, Button> ButtonDown;
     event Action<IGamepad, Button> ButtonUp;
     event Action<IGamepad, Thumbstick> ThumbstickMoved;
-    event Action<IGamepad, Thumbstick> TriggerMoved;
+    event Action<IGamepad, Trigger> TriggerMoved;
 }
 ```
 

src/Input/Silk.NET.Input.Common/Axis.cs

@@ -5,11 +5,26 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents an axis on a joystick.
+    /// </summary>
     public struct Axis
     {
+        /// <summary>
+        /// The index of this axis, used to determine which axis it is.
+        /// </summary>
         public int Index { get; }
+
+        /// <summary>
+        /// The position of this axis.
+        /// </summary>
         public float Position { get; }
 
+        /// <summary>
+        /// Creates a new instance of the Axis struct.
+        /// </summary>
+        /// <param name="index">The index of the new axis.</param>
+        /// <param name="position">The position of the new axis.</param>
         public Axis(int index, float position)
         {
             Index = index;

src/Input/Silk.NET.Input.Common/Button.cs

@@ -5,10 +5,24 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents a joystick button.
+    /// </summary>
     public struct Button
     {
+        /// <summary>
+        /// The name of this button. Only guaranteed to be valid if this comes from an <see cref="IGamepad"/>.
+        /// </summary>
         public ButtonName Name { get; }
+
+        /// <summary>
+        /// The index of this button. Use this if this button comes from an <see cref="IJoystick"/>.
+        /// </summary>
         public int Index { get; }
+
+        /// <summary>
+        /// Whether or not this button is currently pressed.
+        /// </summary>
         public bool Pressed { get; }
 
         public Button(ButtonName name, int index, bool pressed)

src/Input/Silk.NET.Input.Common/Deadzone.cs

@@ -5,11 +5,26 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// The deadzone to use for a joystick/gamepad's sticks.
+    /// </summary>
     public struct Deadzone
     {
+        /// <summary>
+        /// The size of the deadzone to use.
+        /// </summary>
         public float Value { get; }
+
+        /// <summary>
+        /// The deadzone method to use.
+        /// </summary>
         public DeadzoneMethod Method { get; }
 
+        /// <summary>
+        /// Creates a new instance of the Deadzone struct.
+        /// </summary>
+        /// <param name="value">The deadzone size.</param>
+        /// <param name="method">The deadzone method.</param>
         public Deadzone(float value, DeadzoneMethod method)
         {
             Value = value;

src/Input/Silk.NET.Input.Common/Enums/ButtonName.cs

@@ -5,6 +5,9 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// The different names a <see cref="Button"/> can have.
+    /// </summary>
     public enum ButtonName
     {
         A,

src/Input/Silk.NET.Input.Common/Enums/DeadzoneMethod.cs

@@ -5,11 +5,36 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Available methods to control the deadzone of a control stick.
+    /// </summary>
     public enum DeadzoneMethod
     {
-        // y = x except where |x| is between 0 and d (the deadzone value)
+        /// <summary>
+        /// The traditional deadzone method, where the reported value is directly proportional with the actual value until the actual value is within the deadzone - the reported value will be 0 in this case.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// y = x except where |x| is between 0 and d
+        /// </para>
+        /// <para>
+        /// y is the output, x is the raw value, and d is the deadzone value.
+        /// </para>
+        /// </remarks>
         Traditional,
-        // y = (1 - d)x + (d * sgn(x))
+
+        /// <summary>
+        /// A deadzone method where the reported value adapts to the range of the deadzone. If the value is within the deadzone, the reported value is 0.
+        /// After exiting the deadzone, the reported value increases from 0 (when the actual value first exits the deadzone) to 1 (when the actual value is 1).
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// y = (1 - d)x + (d * sgn(x))
+        /// </para>
+        /// <para>
+        /// y is the output, x is the raw value, and d is the deadzone value.
+        /// </para>
+        /// </remarks>
         AdaptiveGradient
     }
-}
+}

src/Input/Silk.NET.Input.Common/Enums/Key.cs

@@ -5,6 +5,14 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents the keys on a keyboard.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When using some backends, only a certain number of function keys may be available. For example, if the backend only supports up to F12, events regarding F13 through F35 will never be raised.
+    /// </para>
+    /// </remarks>
     public enum Key
     {
         Unknown = 0,
@@ -155,4 +163,4 @@ public enum Key
         NonUSBackSlash,
         LastKey
     }
-}
+}

src/Input/Silk.NET.Input.Common/Enums/MouseButton.cs

@@ -5,6 +5,14 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents the indices of the mouse buttons.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The number of buttons provided depends on the input backend currently being used.
+    /// </para>
+    /// </remarks>
     public enum MouseButton
     {
         Left,

src/Input/Silk.NET.Input.Common/Enums/Position2D.cs

@@ -7,13 +7,16 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents the position of a joystick <see cref="Hat"/>
+    /// </summary>
     [Flags]
     public enum Position2D
     {
-        Up,
-        Down,
-        Left,
-        Right,
+        Up = 1,
+        Down = 2,
+        Left = 4,
+        Right = 8,
 
         UpLeft = Up | Left,
         UpRight = Up | Right,

src/Input/Silk.NET.Input.Common/Hat.cs

@@ -5,11 +5,26 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents a joystick hat.
+    /// </summary>
     public struct Hat
     {
+        /// <summary>
+        /// The index of this hat.
+        /// </summary>
         public int Index { get; }
+
+        /// <summary>
+        /// The position of this hat.
+        /// </summary>
         public Position2D Position { get; }
 
+        /// <summary>
+        /// Creates a new instance of the Hat struct.
+        /// </summary>
+        /// <param name="index">The index of the hat.</param>
+        /// <param name="position">The position of the hat.</param>
         public Hat(int index, Position2D position)
         {
             Index = index;

src/Input/Silk.NET.Input.Common/Interfaces/IGamepad.cs

@@ -8,15 +8,55 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Represents a gamepad/controller with a set amount of thumbsticks, buttons, and triggers.
+    /// </summary>
     public interface IGamepad : IInputDevice
     {
+        /// <summary>
+        /// A list of all available buttons.
+        /// </summary>
         IReadOnlyCollection<Button> Buttons { get; }
+
+        /// <summary>
+        /// A list of all available thumbsticks.
+        /// </summary>
         IReadOnlyCollection<Thumbstick> Thumbsticks { get; }
+
+        /// <summary>
+        /// A list of all available triggers.
+        /// </summary>
         IReadOnlyCollection<Trigger> Triggers { get; }
+
+        /// <summary>
+        /// The deadzone for this gamepad.
+        /// </summary>
         Deadzone Deadzone { get; set; }
+
+        /// <summary>
+        /// Called when a button is pressed.
+        /// </summary>
+        /// <remarks>
+        /// This event is only called when the button is first pressed, and not every frame where the button is still pressed.
+        /// </remarks>
         event Action<IGamepad, Button> ButtonDown;
+
+        /// <summary>
+        /// Called when a button is released.
+        /// </summary>
+        /// <remarks>
+        /// This event is only called when the button is first released, and not every frame where the button is still released.
+        /// </remarks>
         event Action<IGamepad, Button> ButtonUp;
+
+        /// <summary>
+        /// Called when a thumbstick is moved.
+        /// </summary>
         event Action<IGamepad, Thumbstick> ThumbstickMoved;
-        event Action<IGamepad, Thumbstick> TriggerMoved;
+
+        /// <summary>
+        /// Called when a trigger is moved.
+        /// </summary>
+        event Action<IGamepad, Trigger> TriggerMoved;
     }
-}
+}

src/Input/Silk.NET.Input.Common/Interfaces/IInputContext.cs

@@ -8,13 +8,39 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// An interface representing the input context.
+    /// </summary>
     public interface IInputContext
     {
+        /// <summary>
+        /// A handle to the underlying window.
+        /// </summary>
         IntPtr Handle { get; }
+
+        /// <summary>
+        /// A list of all available gamepads.
+        /// </summary>
         IReadOnlyCollection<IGamepad> Gamepads { get; }
+
+        /// <summary>
+        /// A list of all available joysticks.
+        /// </summary>
         IReadOnlyCollection<IJoystick> Joysticks { get; }
+
+        /// <summary>
+        /// A list of all available keyboards.
+        /// </summary>
         IReadOnlyCollection<IKeyboard> Keyboards { get; }
+
+        /// <summary>
+        /// A list of all available mice.
+        /// </summary>
         IReadOnlyCollection<IMouse> Mice { get; }
+
+        /// <summary>
+        /// A list of all other available input devices.
+        /// </summary>
         IReadOnlyCollection<IInputDevice> OtherDevices { get; }
     }
 }

src/Input/Silk.NET.Input.Common/Interfaces/IInputDevice.cs

@@ -7,11 +7,29 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// Generic interface representing an input device.
+    /// </summary>
     public interface IInputDevice
     {
+        /// <summary>
+        /// The name of this device, as reported by the hardware.
+        /// </summary>
         string Name { get; }
+
+        /// <summary>
+        /// The index of this device.
+        /// </summary>
         int Index { get; }
+
+        /// <summary>
+        /// Whether or not this device is currently connected.
+        /// </summary>
         bool IsConnected { get; }
+
+        /// <summary>
+        /// Called when the connection of this device changes.
+        /// </summary>
         event Action<IInputDevice, bool> ConnectionChanged;
     }
 }

src/Input/Silk.NET.Input.Common/Interfaces/IInputPlatform.cs

@@ -7,9 +7,30 @@
 
 namespace Silk.NET.Input.Common
 {
+    /// <summary>
+    /// An interface representing an input platform.
+    /// </summary>
     public interface IInputPlatform
     {
+        /// <summary>
+        /// If this platform is applicable to this window.
+        /// </summary>
+        /// <param name="window">The window to check.</param>
+        /// <returns>Whether or not this platform is applicable.</returns>
+        /// <remarks>
+        /// Generally, each Input package will also have a matching Windowing package,
+        /// and the Input package will reference the Windowing package. IsApplicable works
+        /// by checking that the given window is an instance created by the Windowing
+        /// package the Input package references. For example, GlfwInputPlatform will only
+        /// be applicable for a GlfwWindow.
+        /// </remarks>
         bool IsApplicable(IWindow window);
+
+        /// <summary>
+        /// Get an input context for this window.
+        /// </summary>
+        /// <param name="window">The window to get a context for.</param>
+        /// <returns>The context.</returns>
         IInputContext GetInput(IWindow window);
     }
-}
+}