add doc comments for the Input namespace

remotes/1695061714407202320/main
cosmonaut 2023-09-14 11:23:04 -07:00
parent 1bff459be6
commit 7e18764942
23 changed files with 210 additions and 31 deletions

View File

@ -3,6 +3,9 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Represents a specific joystick direction on a gamepad.
/// </summary>
public class Axis public class Axis
{ {
public Gamepad Parent { get; } public Gamepad Parent { get; }

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Can be used to access a gamepad axis virtual button without a direct reference to the button object.
/// </summary>
public enum AxisButtonCode public enum AxisButtonCode
{ {
LeftX_Left, LeftX_Left,

View File

@ -1,6 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
// Enum values are equivalent to SDL GameControllerAxis /// <summary>
/// Can be used to access a gamepad axis without a direct reference to the axis object.
/// Enum values are equivalent to SDL_GameControllerAxis.
/// </summary>
public enum AxisCode public enum AxisCode
{ {
LeftX, LeftX,

View File

@ -1,6 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
// Enum values are equivalent to the SDL GameControllerButton value. /// <summary>
/// Can be used to access a gamepad button without a direct reference to the button object.
/// Enum values are equivalent to the SDL GameControllerButton value.
/// </summary>
public enum GamepadButtonCode public enum GamepadButtonCode
{ {
A, A,

View File

@ -1,14 +1,40 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Container for the current state of a binary input.
/// </summary>
public struct ButtonState public struct ButtonState
{ {
public ButtonStatus ButtonStatus { get; } public ButtonStatus ButtonStatus { get; }
/// <summary>
/// True if the button was pressed this frame.
/// </summary>
public bool IsPressed => ButtonStatus == ButtonStatus.Pressed; public bool IsPressed => ButtonStatus == ButtonStatus.Pressed;
/// <summary>
/// True if the button was pressed this frame and the previous frame.
/// </summary>
public bool IsHeld => ButtonStatus == ButtonStatus.Held; public bool IsHeld => ButtonStatus == ButtonStatus.Held;
/// <summary>
/// True if the button was either pressed or continued to be held this frame.
/// </summary>
public bool IsDown => ButtonStatus == ButtonStatus.Pressed || ButtonStatus == ButtonStatus.Held; public bool IsDown => ButtonStatus == ButtonStatus.Pressed || ButtonStatus == ButtonStatus.Held;
/// <summary>
/// True if the button was let go this frame.
/// </summary>
public bool IsReleased => ButtonStatus == ButtonStatus.Released; public bool IsReleased => ButtonStatus == ButtonStatus.Released;
/// <summary>
/// True if the button was not pressed this frame or the previous frame.
/// </summary>
public bool IsIdle => ButtonStatus == ButtonStatus.Idle; public bool IsIdle => ButtonStatus == ButtonStatus.Idle;
/// <summary>
/// True if the button was either idle or released this frame.
/// </summary>
public bool IsUp => ButtonStatus == ButtonStatus.Idle || ButtonStatus == ButtonStatus.Released; public bool IsUp => ButtonStatus == ButtonStatus.Idle || ButtonStatus == ButtonStatus.Released;
public ButtonState(ButtonStatus buttonStatus) public ButtonState(ButtonStatus buttonStatus)
@ -43,7 +69,7 @@
} }
/// <summary> /// <summary>
/// Combines two button states. Useful for alt controls or input buffering. /// Combines two button states. Useful for alt control sets or input buffering.
/// </summary> /// </summary>
public static ButtonState operator |(ButtonState a, ButtonState b) public static ButtonState operator |(ButtonState a, ButtonState b)
{ {

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Represents the current status of a binary input.
/// </summary>
public enum ButtonStatus public enum ButtonStatus
{ {
/// <summary> /// <summary>

View File

@ -1,10 +0,0 @@
namespace MoonWorks.Input
{
public enum DeviceKind
{
None,
Keyboard,
Mouse,
Gamepad,
}
}

View File

@ -5,6 +5,12 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A Gamepad input abstraction that represents input coming from a console controller or other such devices.
/// The button names map to a standard Xbox 360 controller.
/// For different controllers the relative position of the face buttons will determine the button mapping.
/// For example on a DualShock controller the Cross button will map to the A button.
/// </summary>
public class Gamepad public class Gamepad
{ {
internal IntPtr Handle; internal IntPtr Handle;
@ -51,7 +57,14 @@ namespace MoonWorks.Input
public bool IsDummy => Handle == IntPtr.Zero; public bool IsDummy => Handle == IntPtr.Zero;
/// <summary>
/// True if any input on the gamepad is active. Useful for input remapping.
/// </summary>
public bool AnyPressed { get; private set; } public bool AnyPressed { get; private set; }
/// <summary>
/// Contains a reference to an arbitrary VirtualButton that was pressed on the gamepad this frame. Useful for input remapping.
/// </summary>
public VirtualButton AnyPressedButton { get; private set; } public VirtualButton AnyPressedButton { get; private set; }
private Dictionary<SDL.SDL_GameControllerButton, GamepadButton> EnumToButton; private Dictionary<SDL.SDL_GameControllerButton, GamepadButton> EnumToButton;
@ -195,7 +208,7 @@ namespace MoonWorks.Input
}; };
} }
public void Register(IntPtr handle) internal void Register(IntPtr handle)
{ {
Handle = handle; Handle = handle;
@ -203,7 +216,7 @@ namespace MoonWorks.Input
JoystickInstanceID = SDL.SDL_JoystickInstanceID(joystickHandle); JoystickInstanceID = SDL.SDL_JoystickInstanceID(joystickHandle);
} }
public void Unregister() internal void Unregister()
{ {
Handle = IntPtr.Zero; Handle = IntPtr.Zero;
JoystickInstanceID = -1; JoystickInstanceID = -1;
@ -267,16 +280,25 @@ namespace MoonWorks.Input
) == 0; ) == 0;
} }
/// <summary>
/// Obtains a gamepad button object given a button code.
/// </summary>
public GamepadButton Button(GamepadButtonCode buttonCode) public GamepadButton Button(GamepadButtonCode buttonCode)
{ {
return EnumToButton[(SDL.SDL_GameControllerButton) buttonCode]; return EnumToButton[(SDL.SDL_GameControllerButton) buttonCode];
} }
/// <summary>
/// Obtains an axis button object given a button code.
/// </summary>
public AxisButton Button(AxisButtonCode axisButtonCode) public AxisButton Button(AxisButtonCode axisButtonCode)
{ {
return AxisButtonCodeToAxisButton[axisButtonCode]; return AxisButtonCodeToAxisButton[axisButtonCode];
} }
/// <summary>
/// Obtains a trigger button object given a button code.
/// </summary>
public TriggerButton Button(TriggerCode triggerCode) public TriggerButton Button(TriggerCode triggerCode)
{ {
return TriggerCodeToTriggerButton[triggerCode]; return TriggerCodeToTriggerButton[triggerCode];

View File

@ -3,18 +3,36 @@ using System;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// The main container class for all input tracking.
/// Your Game class will automatically have a reference to this class.
/// </summary>
public class Inputs public class Inputs
{ {
public const int MAX_GAMEPADS = 4; public const int MAX_GAMEPADS = 4;
/// <summary>
/// The reference to the Keyboard input abstraction.
/// </summary>
public Keyboard Keyboard { get; } public Keyboard Keyboard { get; }
/// <summary>
/// The reference to the Mouse input abstraction.
/// </summary>
public Mouse Mouse { get; } public Mouse Mouse { get; }
Gamepad[] gamepads; Gamepad[] Gamepads;
public static event Action<char> TextInput; public static event Action<char> TextInput;
/// <summary>
/// True if any input on any input device is active. Useful for input remapping.
/// </summary>
public bool AnyPressed { get; private set; } public bool AnyPressed { get; private set; }
/// <summary>
/// Contains a reference to an arbitrary VirtualButton that was pressed this frame. Useful for input remapping.
/// </summary>
public VirtualButton AnyPressedButton { get; private set; } public VirtualButton AnyPressedButton { get; private set; }
internal Inputs() internal Inputs()
@ -22,12 +40,12 @@ namespace MoonWorks.Input
Keyboard = new Keyboard(); Keyboard = new Keyboard();
Mouse = new Mouse(); Mouse = new Mouse();
gamepads = new Gamepad[MAX_GAMEPADS]; Gamepads = new Gamepad[MAX_GAMEPADS];
// initialize dummy controllers // initialize dummy controllers
for (var slot = 0; slot < MAX_GAMEPADS; slot += 1) for (var slot = 0; slot < MAX_GAMEPADS; slot += 1)
{ {
gamepads[slot] = new Gamepad(IntPtr.Zero, slot); Gamepads[slot] = new Gamepad(IntPtr.Zero, slot);
} }
} }
@ -53,7 +71,7 @@ namespace MoonWorks.Input
AnyPressedButton = Mouse.AnyPressedButton; AnyPressedButton = Mouse.AnyPressedButton;
} }
foreach (var gamepad in gamepads) foreach (var gamepad in Gamepads)
{ {
gamepad.Update(); gamepad.Update();
@ -65,6 +83,11 @@ namespace MoonWorks.Input
} }
} }
/// <summary>
/// Returns true if a gamepad is currently connected in the given slot.
/// </summary>
/// <param name="slot">Range: 0-3</param>
/// <returns></returns>
public bool GamepadExists(int slot) public bool GamepadExists(int slot)
{ {
if (slot < 0 || slot >= MAX_GAMEPADS) if (slot < 0 || slot >= MAX_GAMEPADS)
@ -72,13 +95,19 @@ namespace MoonWorks.Input
return false; return false;
} }
return !gamepads[slot].IsDummy; return !Gamepads[slot].IsDummy;
} }
// From 0-4 /// <summary>
/// Gets a gamepad associated with the given slot.
/// The first n slots are guaranteed to occupied with gamepads if they are connected.
/// If a gamepad does not exist for the given slot, a dummy object with all inputs in default state will be returned.
/// You can check if a gamepad is connected in a slot with the GamepadExists function.
/// </summary>
/// <param name="slot">Range: 0-3</param>
public Gamepad GetGamepad(int slot) public Gamepad GetGamepad(int slot)
{ {
return gamepads[slot]; return Gamepads[slot];
} }
internal void AddGamepad(int index) internal void AddGamepad(int index)
@ -95,7 +124,7 @@ namespace MoonWorks.Input
} }
else else
{ {
gamepads[slot].Register(openResult); Gamepads[slot].Register(openResult);
System.Console.WriteLine($"Gamepad added to slot {slot}!"); System.Console.WriteLine($"Gamepad added to slot {slot}!");
} }
return; return;
@ -109,10 +138,10 @@ namespace MoonWorks.Input
{ {
for (int slot = 0; slot < MAX_GAMEPADS; slot += 1) for (int slot = 0; slot < MAX_GAMEPADS; slot += 1)
{ {
if (joystickInstanceID == gamepads[slot].JoystickInstanceID) if (joystickInstanceID == Gamepads[slot].JoystickInstanceID)
{ {
SDL.SDL_GameControllerClose(gamepads[slot].Handle); SDL.SDL_GameControllerClose(Gamepads[slot].Handle);
gamepads[slot].Unregister(); Gamepads[slot].Unregister();
System.Console.WriteLine($"Removing gamepad from slot {slot}!"); System.Console.WriteLine($"Removing gamepad from slot {slot}!");
return; return;
} }

View File

@ -1,6 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
// Enum values are equivalent to the SDL Scancode value. /// <summary>
/// Can be used to determine key state without a direct reference to the virtual button object.
/// Enum values are equivalent to the SDL Scancode value.
/// </summary>
public enum KeyCode : int public enum KeyCode : int
{ {
Unknown = 0, Unknown = 0,

View File

@ -4,12 +4,22 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// The keyboard input device abstraction.
/// </summary>
public class Keyboard public class Keyboard
{ {
/// <summary>
/// True if any button on the keyboard is active. Useful for input remapping.
/// </summary>
public bool AnyPressed { get; private set; } public bool AnyPressed { get; private set; }
/// <summary>
/// Contains a reference to an arbitrary KeyboardButton that was pressed this frame. Useful for input remapping.
/// </summary>
public KeyboardButton AnyPressedButton { get; private set; } public KeyboardButton AnyPressedButton { get; private set; }
public IntPtr State { get; private set; } internal IntPtr State { get; private set; }
private KeyCode[] KeyCodes; private KeyCode[] KeyCodes;
private KeyboardButton[] Keys { get; } private KeyboardButton[] Keys { get; }
@ -78,41 +88,65 @@ namespace MoonWorks.Input
} }
} }
/// <summary>
/// True if the button was pressed this frame.
/// </summary>
public bool IsPressed(KeyCode keycode) public bool IsPressed(KeyCode keycode)
{ {
return Keys[(int) keycode].IsPressed; return Keys[(int) keycode].IsPressed;
} }
/// <summary>
/// True if the button was pressed this frame and the previous frame.
/// </summary>
public bool IsHeld(KeyCode keycode) public bool IsHeld(KeyCode keycode)
{ {
return Keys[(int) keycode].IsHeld; return Keys[(int) keycode].IsHeld;
} }
/// <summary>
/// True if the button was either pressed or continued to be held this frame.
/// </summary>
public bool IsDown(KeyCode keycode) public bool IsDown(KeyCode keycode)
{ {
return Keys[(int) keycode].IsDown; return Keys[(int) keycode].IsDown;
} }
/// <summary>
/// True if the button was let go this frame.
/// </summary>
public bool IsReleased(KeyCode keycode) public bool IsReleased(KeyCode keycode)
{ {
return Keys[(int) keycode].IsReleased; return Keys[(int) keycode].IsReleased;
} }
/// <summary>
/// True if the button was not pressed this frame or the previous frame.
/// </summary>
public bool IsIdle(KeyCode keycode) public bool IsIdle(KeyCode keycode)
{ {
return Keys[(int) keycode].IsIdle; return Keys[(int) keycode].IsIdle;
} }
/// <summary>
/// True if the button was either idle or released this frame.
/// </summary>
public bool IsUp(KeyCode keycode) public bool IsUp(KeyCode keycode)
{ {
return Keys[(int) keycode].IsUp; return Keys[(int) keycode].IsUp;
} }
/// <summary>
/// Gets a reference to a keyboard button object using a key code.
/// </summary>
public KeyboardButton Button(KeyCode keycode) public KeyboardButton Button(KeyCode keycode)
{ {
return Keys[(int) keycode]; return Keys[(int) keycode];
} }
/// <summary>
/// Gets the state of a keyboard button from a key code.
/// </summary>
public ButtonState ButtonState(KeyCode keycode) public ButtonState ButtonState(KeyCode keycode)
{ {
return Keys[(int) keycode].State; return Keys[(int) keycode].State;

View File

@ -3,6 +3,9 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// The mouse input device abstraction.
/// </summary>
public class Mouse public class Mouse
{ {
public MouseButton LeftButton { get; } public MouseButton LeftButton { get; }
@ -21,12 +24,23 @@ namespace MoonWorks.Input
internal int WheelRaw; internal int WheelRaw;
private int previousWheelRaw = 0; private int previousWheelRaw = 0;
/// <summary>
/// True if any button on the keyboard is active. Useful for input remapping.
/// </summary>
public bool AnyPressed { get; private set; } public bool AnyPressed { get; private set; }
/// <summary>
/// Contains a reference to an arbitrary MouseButton that was pressed this frame. Useful for input remapping.
/// </summary>
public MouseButton AnyPressedButton { get; private set; } public MouseButton AnyPressedButton { get; private set; }
public uint ButtonMask { get; private set; } internal uint ButtonMask { get; private set; }
private bool relativeMode; private bool relativeMode;
/// <summary>
/// If set to true, the cursor is hidden, the mouse position is constrained to the window,
/// and relative mouse motion will be reported even if the mouse is at the edge of the window.
/// </summary>
public bool RelativeMode public bool RelativeMode
{ {
get => relativeMode; get => relativeMode;
@ -42,6 +56,9 @@ namespace MoonWorks.Input
} }
private bool hidden; private bool hidden;
/// <summary>
/// If set to true, the OS cursor will not be shown in your application window.
/// </summary>
public bool Hidden public bool Hidden
{ {
get => hidden; get => hidden;
@ -54,7 +71,7 @@ namespace MoonWorks.Input
private readonly Dictionary<MouseButtonCode, MouseButton> CodeToButton; private readonly Dictionary<MouseButtonCode, MouseButton> CodeToButton;
public Mouse() internal Mouse()
{ {
LeftButton = new MouseButton(this, MouseButtonCode.Left, SDL.SDL_BUTTON_LMASK); LeftButton = new MouseButton(this, MouseButtonCode.Left, SDL.SDL_BUTTON_LMASK);
MiddleButton = new MouseButton(this, MouseButtonCode.Middle, SDL.SDL_BUTTON_MMASK); MiddleButton = new MouseButton(this, MouseButtonCode.Middle, SDL.SDL_BUTTON_MMASK);
@ -99,11 +116,17 @@ namespace MoonWorks.Input
} }
} }
/// <summary>
/// Gets a button from the mouse given a MouseButtonCode.
/// </summary>
public MouseButton Button(MouseButtonCode buttonCode) public MouseButton Button(MouseButtonCode buttonCode)
{ {
return CodeToButton[buttonCode]; return CodeToButton[buttonCode];
} }
/// <summary>
/// Gets a button state from a mouse button corresponding to the given MouseButtonCode.
/// </summary>
public ButtonState ButtonState(MouseButtonCode buttonCode) public ButtonState ButtonState(MouseButtonCode buttonCode)
{ {
return CodeToButton[buttonCode].State; return CodeToButton[buttonCode].State;

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Can be used to determine virtual mouse button state without a direct reference to the button object.
/// </summary>
public enum MouseButtonCode public enum MouseButtonCode
{ {
Left, Left,

View File

@ -3,6 +3,9 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// Represents a trigger input on a gamepad.
/// </summary>
public class Trigger public class Trigger
{ {
public Gamepad Parent { get; } public Gamepad Parent { get; }

View File

@ -1,6 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
// Enum values correspond to SDL GameControllerAxis /// <summary>
/// Can be used to determine trigger state or trigger virtual button state without direct reference to the trigger object or virtual button object.
/// Enum values correspond to SDL_GameControllerAxis.
/// </summary>
public enum TriggerCode public enum TriggerCode
{ {
Left = 4, Left = 4,

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// VirtualButtons map inputs to binary inputs, like a trigger threshold or joystick axis threshold.
/// </summary>
public abstract class VirtualButton public abstract class VirtualButton
{ {
public ButtonState State { get; protected set; } public ButtonState State { get; protected set; }

View File

@ -1,5 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A virtual button corresponding to a direction on a joystick.
/// If the axis value exceeds the threshold, it will be treated as a press.
/// </summary>
public class AxisButton : VirtualButton public class AxisButton : VirtualButton
{ {
public Axis Parent { get; } public Axis Parent { get; }

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A dummy button that can never be pressed. Used for the dummy gamepad.
/// </summary>
public class EmptyButton : VirtualButton public class EmptyButton : VirtualButton
{ {
internal override bool CheckPressed() internal override bool CheckPressed()

View File

@ -2,6 +2,9 @@ using SDL2;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A virtual button corresponding to a gamepad button.
/// </summary>
public class GamepadButton : VirtualButton public class GamepadButton : VirtualButton
{ {
public Gamepad Parent { get; } public Gamepad Parent { get; }

View File

@ -2,6 +2,9 @@ using System.Runtime.InteropServices;
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A virtual button corresponding to a keyboard button.
/// </summary>
public class KeyboardButton : VirtualButton public class KeyboardButton : VirtualButton
{ {
Keyboard Parent; Keyboard Parent;

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A virtual button corresponding to a mouse button.
/// </summary>
public class MouseButton : VirtualButton public class MouseButton : VirtualButton
{ {
Mouse Parent; Mouse Parent;

View File

@ -1,5 +1,9 @@
namespace MoonWorks.Input namespace MoonWorks.Input
{ {
/// <summary>
/// A virtual button corresponding to a trigger on a gamepad.
/// If the trigger value exceeds the threshold, it will be treated as a press.
/// </summary>
public class TriggerButton : VirtualButton public class TriggerButton : VirtualButton
{ {
public Trigger Parent { get; } public Trigger Parent { get; }

View File

@ -5,6 +5,11 @@ using SDL2;
namespace MoonWorks namespace MoonWorks
{ {
/// <summary>
/// Represents a window in the client operating system.
/// Every Game has a MainWindow automatically.
/// You can create dditional Windows if you desire. They must be Claimed by the GraphicsDevice to be rendered to.
/// </summary>
public class Window : IDisposable public class Window : IDisposable
{ {
internal IntPtr Handle { get; } internal IntPtr Handle { get; }