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
{
/// <summary>
/// Represents a specific joystick direction on a gamepad.
/// </summary>
public class Axis
{
public Gamepad Parent { get; }

View File

@ -1,5 +1,8 @@
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
{
LeftX_Left,

View File

@ -1,6 +1,9 @@
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
{
LeftX,

View File

@ -1,6 +1,9 @@
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
{
A,

View File

@ -1,14 +1,40 @@
namespace MoonWorks.Input
{
/// <summary>
/// Container for the current state of a binary input.
/// </summary>
public struct ButtonState
{
public ButtonStatus ButtonStatus { get; }
/// <summary>
/// True if the button was pressed this frame.
/// </summary>
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;
/// <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;
/// <summary>
/// True if the button was let go this frame.
/// </summary>
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;
/// <summary>
/// True if the button was either idle or released this frame.
/// </summary>
public bool IsUp => ButtonStatus == ButtonStatus.Idle || ButtonStatus == ButtonStatus.Released;
public ButtonState(ButtonStatus buttonStatus)
@ -43,7 +69,7 @@
}
/// <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>
public static ButtonState operator |(ButtonState a, ButtonState b)
{

View File

@ -1,5 +1,8 @@
namespace MoonWorks.Input
{
/// <summary>
/// Represents the current status of a binary input.
/// </summary>
public enum ButtonStatus
{
/// <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
{
/// <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
{
internal IntPtr Handle;
@ -51,7 +57,14 @@ namespace MoonWorks.Input
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; }
/// <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; }
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;
@ -203,7 +216,7 @@ namespace MoonWorks.Input
JoystickInstanceID = SDL.SDL_JoystickInstanceID(joystickHandle);
}
public void Unregister()
internal void Unregister()
{
Handle = IntPtr.Zero;
JoystickInstanceID = -1;
@ -267,16 +280,25 @@ namespace MoonWorks.Input
) == 0;
}
/// <summary>
/// Obtains a gamepad button object given a button code.
/// </summary>
public GamepadButton Button(GamepadButtonCode buttonCode)
{
return EnumToButton[(SDL.SDL_GameControllerButton) buttonCode];
}
/// <summary>
/// Obtains an axis button object given a button code.
/// </summary>
public AxisButton Button(AxisButtonCode axisButtonCode)
{
return AxisButtonCodeToAxisButton[axisButtonCode];
}
/// <summary>
/// Obtains a trigger button object given a button code.
/// </summary>
public TriggerButton Button(TriggerCode triggerCode)
{
return TriggerCodeToTriggerButton[triggerCode];

View File

@ -3,18 +3,36 @@ using System;
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 const int MAX_GAMEPADS = 4;
/// <summary>
/// The reference to the Keyboard input abstraction.
/// </summary>
public Keyboard Keyboard { get; }
/// <summary>
/// The reference to the Mouse input abstraction.
/// </summary>
public Mouse Mouse { get; }
Gamepad[] gamepads;
Gamepad[] Gamepads;
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; }
/// <summary>
/// Contains a reference to an arbitrary VirtualButton that was pressed this frame. Useful for input remapping.
/// </summary>
public VirtualButton AnyPressedButton { get; private set; }
internal Inputs()
@ -22,12 +40,12 @@ namespace MoonWorks.Input
Keyboard = new Keyboard();
Mouse = new Mouse();
gamepads = new Gamepad[MAX_GAMEPADS];
Gamepads = new Gamepad[MAX_GAMEPADS];
// initialize dummy controllers
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;
}
foreach (var gamepad in gamepads)
foreach (var gamepad in Gamepads)
{
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)
{
if (slot < 0 || slot >= MAX_GAMEPADS)
@ -72,13 +95,19 @@ namespace MoonWorks.Input
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)
{
return gamepads[slot];
return Gamepads[slot];
}
internal void AddGamepad(int index)
@ -95,7 +124,7 @@ namespace MoonWorks.Input
}
else
{
gamepads[slot].Register(openResult);
Gamepads[slot].Register(openResult);
System.Console.WriteLine($"Gamepad added to slot {slot}!");
}
return;
@ -109,10 +138,10 @@ namespace MoonWorks.Input
{
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);
gamepads[slot].Unregister();
SDL.SDL_GameControllerClose(Gamepads[slot].Handle);
Gamepads[slot].Unregister();
System.Console.WriteLine($"Removing gamepad from slot {slot}!");
return;
}

View File

@ -1,6 +1,9 @@
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
{
Unknown = 0,

View File

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

View File

@ -3,6 +3,9 @@ using SDL2;
namespace MoonWorks.Input
{
/// <summary>
/// The mouse input device abstraction.
/// </summary>
public class Mouse
{
public MouseButton LeftButton { get; }
@ -21,12 +24,23 @@ namespace MoonWorks.Input
internal int WheelRaw;
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; }
/// <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 uint ButtonMask { get; private set; }
internal uint ButtonMask { get; private set; }
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
{
get => relativeMode;
@ -42,6 +56,9 @@ namespace MoonWorks.Input
}
private bool hidden;
/// <summary>
/// If set to true, the OS cursor will not be shown in your application window.
/// </summary>
public bool Hidden
{
get => hidden;
@ -54,7 +71,7 @@ namespace MoonWorks.Input
private readonly Dictionary<MouseButtonCode, MouseButton> CodeToButton;
public Mouse()
internal Mouse()
{
LeftButton = new MouseButton(this, MouseButtonCode.Left, SDL.SDL_BUTTON_LMASK);
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)
{
return CodeToButton[buttonCode];
}
/// <summary>
/// Gets a button state from a mouse button corresponding to the given MouseButtonCode.
/// </summary>
public ButtonState ButtonState(MouseButtonCode buttonCode)
{
return CodeToButton[buttonCode].State;

View File

@ -1,5 +1,8 @@
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
{
Left,

View File

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

View File

@ -1,6 +1,9 @@
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
{
Left = 4,

View File

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

View File

@ -1,5 +1,9 @@
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 Axis Parent { get; }

View File

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

View File

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

View File

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

View File

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

View File

@ -1,5 +1,9 @@
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 Trigger Parent { get; }

View File

@ -5,6 +5,11 @@ using SDL2;
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
{
internal IntPtr Handle { get; }