libnx  v4.2.0
pad.h
Go to the documentation of this file.
1 /**
2  * @file pad.h
3  * @brief Simple wrapper for the HID Npad API.
4  * @author fincs
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../services/hid.h"
10 
11 /// Mask including all existing controller IDs.
12 #define PAD_ANY_ID_MASK 0x1000100FFUL
13 
14 /// Pad state object.
15 typedef struct {
16  u8 id_mask;
17  u8 active_id_mask;
18  bool read_handheld;
19  bool active_handheld;
20  u32 style_set;
21  u32 attributes;
22  u64 buttons_cur;
23  u64 buttons_old;
24  HidAnalogStickState sticks[2];
25  u32 gc_triggers[2];
26 } PadState;
27 
28 /// Pad button repeater state object.
29 typedef struct {
30  u64 button_mask;
31  s32 counter;
32  u16 delay;
33  u16 repeat;
34 } PadRepeater;
35 
36 /**
37  * @brief Configures the input layout supported by the application.
38  * @param[in] max_players The maximum supported number of players (1 to 8).
39  * @param[in] style_set Bitfield of supported controller styles (see \ref HidNpadStyleTag).
40  */
41 void padConfigureInput(u32 max_players, u32 style_set);
42 
43 /**
44  * @brief Initializes a \ref PadState object to read input from one or more controller input sources.
45  * @param[in] _pad Pointer to \ref PadState.
46  * @remarks This is a variadic macro, pass the \ref HidNpadIdType value of each controller to add to the set.
47  */
48 #define padInitialize(_pad, ...) ({ \
49  const HidNpadIdType _pad_ids[] = { __VA_ARGS__ }; \
50  u64 _pad_mask = 0; \
51  for (unsigned _pad_i = 0; _pad_i < (sizeof(_pad_ids)/sizeof(_pad_ids[0])); ++_pad_i) \
52  _pad_mask |= 1UL << (_pad_ids[_pad_i]); \
53  padInitializeWithMask((_pad), _pad_mask); \
54 })
55 
56 /**
57  * @brief Same as \ref padInitialize, but taking a bitfield of controller IDs directly.
58  * @param[in] pad Pointer to \ref PadState.
59  * @param[in] mask Bitfield of controller IDs (each bit's position indicates a different \ref HidNpadIdType value).
60  */
61 void padInitializeWithMask(PadState* pad, u64 mask);
62 
63 /**
64  * @brief Same as \ref padInitialize, but including every single controller input source.
65  * @param[in] pad Pointer to \ref PadState.
66  * @remark Use this function if you want to accept input from any controller.
67  */
70 }
71 
72 /**
73  * @brief Same as \ref padInitialize, but including \ref HidNpadIdType_No1 and \ref HidNpadIdType_Handheld.
74  * @param[in] pad Pointer to \ref PadState.
75  * @remark Use this function if you just want to accept input for a single-player application.
76  */
79 }
80 
81 /**
82  * @brief Updates pad state by reading from the controller input sources specified during initialization.
83  * @param[in] pad Pointer to \ref PadState.
84  */
85 void padUpdate(PadState* pad);
86 
87 /**
88  * @brief Retrieves whether \ref HidNpadIdType_Handheld is an active input source (i.e. it was possible to read from it).
89  * @param[in] pad Pointer to \ref PadState.
90  * @return Boolean value.
91  * @remark \ref padUpdate must have been previously called.
92  */
94  return pad->active_handheld;
95 }
96 
97 /**
98  * @brief Retrieves whether the specified controller is an active input source (i.e. it was possible to read from it).
99  * @param[in] pad Pointer to \ref PadState.
100  * @param[in] id ID of the controller input source (see \ref HidNpadIdType)
101  * @return Boolean value.
102  * @remark \ref padUpdate must have been previously called.
103  */
105  if (id <= HidNpadIdType_No8)
106  return pad->active_id_mask & BIT(id);
107  else if (id == HidNpadIdType_Handheld)
108  return pad->active_handheld;
109  else
110  return false;
111 }
112 
113 /**
114  * @brief Retrieves the set of input styles supported by the selected controller input sources.
115  * @param[in] pad Pointer to \ref PadState.
116  * @return Bitfield of \ref HidNpadStyleTag.
117  * @remark \ref padUpdate must have been previously called.
118  */
120  return pad->style_set;
121 }
122 
123 /**
124  * @brief Retrieves the set of attributes reported by the system for the selected controller input sources.
125  * @param[in] pad Pointer to \ref PadState.
126  * @return Bitfield of \ref HidNpadAttribute.
127  * @remark \ref padUpdate must have been previously called.
128  */
130  return pad->attributes;
131 }
132 
133 /**
134  * @brief Retrieves whether any of the selected controller input sources is connected.
135  * @param[in] pad Pointer to \ref PadState.
136  * @return Boolean value.
137  * @remark \ref padUpdate must have been previously called.
138  */
140  return pad->attributes & HidNpadAttribute_IsConnected;
141 }
142 
143 /**
144  * @brief Retrieves the current set of pressed buttons across all selected controller input sources.
145  * @param[in] pad Pointer to \ref PadState.
146  * @return Bitfield of \ref HidNpadButton.
147  * @remark \ref padUpdate must have been previously called.
148  */
150  return pad->buttons_cur;
151 }
152 
153 /**
154  * @brief Retrieves the set of buttons that are newly pressed.
155  * @param[in] pad Pointer to \ref PadState.
156  * @return Bitfield of \ref HidNpadButton.
157  * @remark \ref padUpdate must have been previously called.
158  */
160  return ~pad->buttons_old & pad->buttons_cur;
161 }
162 
163 /**
164  * @brief Retrieves the set of buttons that are newly released.
165  * @param[in] pad Pointer to \ref PadState.
166  * @return Bitfield of \ref HidNpadButton.
167  * @remark \ref padUpdate must have been previously called.
168  */
170  return pad->buttons_old & ~pad->buttons_cur;
171 }
172 
173 /**
174  * @brief Retrieves the position of an analog stick in a controller.
175  * @param[in] pad Pointer to \ref PadState.
176  * @param[in] i ID of the analog stick to read (0=left, 1=right).
177  * @return \ref HidAnalogStickState.
178  * @remark \ref padUpdate must have been previously called.
179  */
181  return pad->sticks[i];
182 }
183 
184 /**
185  * @brief Retrieves the position of an analog trigger in a GameCube controller.
186  * @param[in] pad Pointer to \ref PadState.
187  * @param[in] i ID of the analog trigger to read (0=left, 1=right).
188  * @return Analog trigger position (range is 0 to 0x7fff).
189  * @remark \ref padUpdate must have been previously called.
190  * @remark \ref HidNpadStyleTag_NpadGc must have been previously configured as a supported style in \ref padConfigureInput for GC trigger data to be readable.
191  */
192 NX_CONSTEXPR u32 padGetGcTriggerPos(const PadState* pad, unsigned i) {
193  return pad->gc_triggers[i];
194 }
195 
196 /**
197  * @brief Initializes a \ref PadRepeater object with the specified settings.
198  * @param[in] r Pointer to \ref PadRepeater.
199  * @param[in] delay Number of input updates between button presses being first detected and them being considered for repeat.
200  * @param[in] repeat Number of input updates between autogenerated repeat button presses.
201  */
203  r->button_mask = 0;
204  r->counter = 0;
205  r->delay = delay;
206  r->repeat = repeat;
207 }
208 
209 /**
210  * @brief Updates pad repeat state.
211  * @param[in] r Pointer to \ref PadRepeater.
212  * @param[in] button_mask Bitfield of currently pressed \ref HidNpadButton that will be considered for repeat.
213  */
214 void padRepeaterUpdate(PadRepeater* r, u64 button_mask);
215 
216 /**
217  * @brief Retrieves the set of buttons that are being repeated according to the parameters specified in \ref padRepeaterInitialize.
218  * @param[in] r Pointer to \ref PadRepeater.
219  * @return Bitfield of \ref HidNpadButton.
220  * @remark It is suggested to bitwise-OR the return value of this function with that of \ref padGetButtonsDown.
221  */
223  return r->counter == 0 ? r->button_mask : 0;
224 }
HidNpadIdType_No1
@ HidNpadIdType_No1
Player 1 controller.
Definition: hid.h:215
padIsConnected
static bool padIsConnected(const PadState *pad)
Retrieves whether any of the selected controller input sources is connected.
Definition: pad.h:139
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
NX_CONSTEXPR
#define NX_CONSTEXPR
Flags a function as constexpr in C++14 and above; or as (always) inline otherwise.
Definition: types.h:88
padRepeaterUpdate
void padRepeaterUpdate(PadRepeater *r, u64 button_mask)
Updates pad repeat state.
HidNpadIdType_Handheld
@ HidNpadIdType_Handheld
Handheld mode controls.
Definition: hid.h:224
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
PadRepeater
Pad button repeater state object.
Definition: pad.h:29
padGetStickPos
static HidAnalogStickState padGetStickPos(const PadState *pad, unsigned i)
Retrieves the position of an analog stick in a controller.
Definition: pad.h:180
HidNpadIdType
HidNpadIdType
HID controller IDs.
Definition: hid.h:214
padInitialize
#define padInitialize(_pad,...)
Initializes a PadState object to read input from one or more controller input sources.
Definition: pad.h:48
PAD_ANY_ID_MASK
#define PAD_ANY_ID_MASK
Mask including all existing controller IDs.
Definition: pad.h:12
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
padGetButtonsDown
static u64 padGetButtonsDown(const PadState *pad)
Retrieves the set of buttons that are newly pressed.
Definition: pad.h:159
padInitializeWithMask
void padInitializeWithMask(PadState *pad, u64 mask)
Same as padInitialize, but taking a bitfield of controller IDs directly.
HidAnalogStickState
HidAnalogStickState.
Definition: hid.h:560
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
padRepeaterGetButtons
static u64 padRepeaterGetButtons(const PadRepeater *r)
Retrieves the set of buttons that are being repeated according to the parameters specified in padRepe...
Definition: pad.h:222
padGetButtonsUp
static u64 padGetButtonsUp(const PadState *pad)
Retrieves the set of buttons that are newly released.
Definition: pad.h:169
PadState
Pad state object.
Definition: pad.h:15
padConfigureInput
void padConfigureInput(u32 max_players, u32 style_set)
Configures the input layout supported by the application.
padIsNpadActive
static bool padIsNpadActive(const PadState *pad, HidNpadIdType id)
Retrieves whether the specified controller is an active input source (i.e.
Definition: pad.h:104
padUpdate
void padUpdate(PadState *pad)
Updates pad state by reading from the controller input sources specified during initialization.
HidNpadAttribute_IsConnected
@ HidNpadAttribute_IsConnected
IsConnected.
Definition: hid.h:315
padGetStyleSet
static u32 padGetStyleSet(const PadState *pad)
Retrieves the set of input styles supported by the selected controller input sources.
Definition: pad.h:119
padGetAttributes
static u32 padGetAttributes(const PadState *pad)
Retrieves the set of attributes reported by the system for the selected controller input sources.
Definition: pad.h:129
padGetGcTriggerPos
static u32 padGetGcTriggerPos(const PadState *pad, unsigned i)
Retrieves the position of an analog trigger in a GameCube controller.
Definition: pad.h:192
padRepeaterInitialize
static void padRepeaterInitialize(PadRepeater *r, u16 delay, u16 repeat)
Initializes a PadRepeater object with the specified settings.
Definition: pad.h:202
padGetButtons
static u64 padGetButtons(const PadState *pad)
Retrieves the current set of pressed buttons across all selected controller input sources.
Definition: pad.h:149
BIT
#define BIT(n)
Creates a bitmask from a bit number.
Definition: types.h:54
padInitializeAny
static void padInitializeAny(PadState *pad)
Same as padInitialize, but including every single controller input source.
Definition: pad.h:68
padIsHandheld
static bool padIsHandheld(const PadState *pad)
Retrieves whether HidNpadIdType_Handheld is an active input source (i.e.
Definition: pad.h:93
NX_INLINE
#define NX_INLINE
Flags a function as (always) inline.
Definition: types.h:82
padInitializeDefault
static void padInitializeDefault(PadState *pad)
Same as padInitialize, but including HidNpadIdType_No1 and HidNpadIdType_Handheld.
Definition: pad.h:77
u16
uint16_t u16
16-bit unsigned integer.
Definition: types.h:20
HidNpadIdType_No8
@ HidNpadIdType_No8
Player 8 controller.
Definition: hid.h:222