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);
  }
-}
+}