Document Input.Common (#19)

devvoid · Perksey · commit 3fa6668a4008 · 2019-07-13T23:11:24.000+01:00
* Start of Input.ComCommon documentation

* Start of Input.Common documentation

* Document most structs

* Remove mention of d-pad

* Change some key names for parity with input

* Make Position2D powers of two

* Document enums

* Document interfaces and Deadzone

* Correct template mistake

* Document Thumbstick

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

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

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs

Co-Authored-By: Dylan Perks &lt;dylanperks23@gmail.com&gt;

* Update IMouse.cs
diff --git a/documentation/proposals/Proposal - Input.md b/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;
 }
 ```
 
diff --git a/src/Input/Silk.NET.Input.Common/Axis.cs b/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;
diff --git a/src/Input/Silk.NET.Input.Common/Button.cs b/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)
diff --git a/src/Input/Silk.NET.Input.Common/Deadzone.cs b/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;
diff --git a/src/Input/Silk.NET.Input.Common/Enums/ButtonName.cs b/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,
diff --git a/src/Input/Silk.NET.Input.Common/Enums/DeadzoneMethod.cs b/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
     }
-}
+}
diff --git a/src/Input/Silk.NET.Input.Common/Enums/Key.cs b/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
     }
-}
+}
diff --git a/src/Input/Silk.NET.Input.Common/Enums/MouseButton.cs b/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,
diff --git a/src/Input/Silk.NET.Input.Common/Enums/Position2D.cs b/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,
diff --git a/src/Input/Silk.NET.Input.Common/Hat.cs b/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;
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IGamepad.cs b/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;
     }
-}
+}
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IInputContext.cs b/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; }
     }
 }
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IInputDevice.cs b/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;
     }
 }
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IInputPlatform.cs b/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);
     }
-}
+}
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs b/src/Input/Silk.NET.Input.Common/Interfaces/IJoystick.cs
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IKeyboard.cs b/src/Input/Silk.NET.Input.Common/Interfaces/IKeyboard.cs
diff --git a/src/Input/Silk.NET.Input.Common/Interfaces/IMouse.cs b/src/Input/Silk.NET.Input.Common/Interfaces/IMouse.cs
diff --git a/src/Input/Silk.NET.Input.Common/ScrollWheel.cs b/src/Input/Silk.NET.Input.Common/ScrollWheel.cs
diff --git a/src/Input/Silk.NET.Input.Common/Thumbstick.cs b/src/Input/Silk.NET.Input.Common/Thumbstick.cs
diff --git a/src/Input/Silk.NET.Input.Common/Trigger.cs b/src/Input/Silk.NET.Input.Common/Trigger.cs
diff --git a/src/Windowing/Silk.NET.GLFW/Enums/Keys.cs b/src/Windowing/Silk.NET.GLFW/Enums/Keys.cs

Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ public interface IGamepad : IInputDevice`
`49`	`49`	`event Action<IGamepad, Button> ButtonDown;`
`50`	`50`	`event Action<IGamepad, Button> ButtonUp;`
`51`	`51`	`event Action<IGamepad, Thumbstick> ThumbstickMoved;`
`52`		`- event Action<IGamepad, Thumbstick> TriggerMoved;`
	`52`	`+ event Action<IGamepad, Trigger> TriggerMoved;`
`53`	`53`	`}`
`54`	`54`	```
`55`	`55`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,9 @@`
`5`	`5`
`6`	`6`	`namespace Silk.NET.Input.Common`
`7`	`7`	`{`
	`8`	`+ /// <summary>`
	`9`	`+ /// The different names a <see cref="Button"/> can have.`
	`10`	`+ /// </summary>`
`8`	`11`	`public enum ButtonName`
`9`	`12`	`{`
`10`	`13`	`A,`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,14 @@`
`5`	`5`
`6`	`6`	`namespace Silk.NET.Input.Common`
`7`	`7`	`{`
	`8`	`+ /// <summary>`
	`9`	`+ /// Represents the keys on a keyboard.`
	`10`	`+ /// </summary>`
	`11`	`+ /// <remarks>`
	`12`	`+ /// <para>`
	`13`	`+ /// 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.`
	`14`	`+ /// </para>`
	`15`	`+ /// </remarks>`
`8`	`16`	`public enum Key`
`9`	`17`	`{`
`10`	`18`	`Unknown = 0,`
`@@ -155,4 +163,4 @@ public enum Key`
`155`	`163`	`NonUSBackSlash,`
`156`	`164`	`LastKey`
`157`	`165`	`}`
`158`		`-}`
	`166`	`+}`