-
Notifications
You must be signed in to change notification settings - Fork 304
/
InputUser.cs
1939 lines (1718 loc) · 90 KB
/
InputUser.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
using System;
using System.Collections.Generic;
using Unity.Collections;
using UnityEngine.InputSystem.LowLevel;
using UnityEngine.InputSystem.Utilities;
using UnityEngine.Profiling;
////REVIEW: do we need to handle the case where devices are added to a user that are each associated with a different user account
////REVIEW: how should we handle pairings of devices *not* called for by a control scheme? should that result in a failed match?
////TODO: option to bind to *all* devices instead of just the paired ones (bindToAllDevices)
////TODO: the account selection stuff needs cleanup; the current flow is too convoluted
namespace UnityEngine.InputSystem.Users
{
/// <summary>
/// Represents a specific user/player interacting with one or more devices and input actions.
/// </summary>
/// <remarks>
/// Principally, an InputUser represents a human interacting with the application. Moreover, at any point
/// each InputUser represents a human actor distinct from all other InputUsers in the system.
///
/// Each user has one or more paired devices. In general, these devices are unique to each user. However,
/// it is permitted to use <see cref="PerformPairingWithDevice"/> to pair the same device to multiple users.
/// This can be useful in setups such as split-keyboard (e.g. one user using left side of keyboard and the
/// other the right one) use or hotseat-style gameplay (e.g. two players taking turns on the same game controller).
///
/// A user may be associated with a platform user account (<see cref="platformUserAccountHandle"/>), if supported by the
/// platform and the devices used. Support for this is commonly found on consoles. Note that the account
/// associated with an InputUser may change if the player uses the system's facilities to switch to a different
/// account (<see cref="InputUserChange.AccountChanged"/>). On Xbox and Switch, this may also be initiated from
/// the application by passing <see cref="InputUserPairingOptions.ForcePlatformUserAccountSelection"/> to
/// <see cref="PerformPairingWithDevice"/>.
///
/// Platforms that support user account association are <see cref="RuntimePlatform.XboxOne"/>,
/// <see cref="RuntimePlatform.PS4"/>, <see cref="RuntimePlatform.Switch"/>, <see cref="RuntimePlatform.WSAPlayerX86"/>,
/// <see cref="RuntimePlatform.WSAPlayerX64"/>, and <see cref="RuntimePlatform.WSAPlayerARM"/>. Note that
/// for WSA/UWP apps, the "User Account Information" capability must be enabled for the app in order for
/// user information to come through on input devices.
/// </remarks>
/// <seealso cref="InputUserChange"/>
public struct InputUser : IEquatable<InputUser>
{
public const uint InvalidId = 0;
/// <summary>
/// Whether this is a currently active user record in <see cref="all"/>.
/// </summary>
/// <remarks>
/// Users that are removed (<see cref="UnpairDevicesAndRemoveUser"/>) will become invalid.
/// </remarks>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.Removed"/>
public bool valid
{
get
{
if (m_Id == InvalidId)
return false;
// See if there's a currently active user with the given ID.
for (var i = 0; i < s_AllUserCount; ++i)
if (s_AllUsers[i].m_Id == m_Id)
return true;
return false;
}
}
/// <summary>
/// The sequence number of the user.
/// </summary>
/// <remarks>
/// It can be useful to establish a sorting of players locally such that it is
/// known who is the first player, who is the second, and so on. This property
/// gives the positioning of the user within <see cref="all"/>.
///
/// Note that the index of a user may change as users are added and removed.
/// </remarks>
/// <seealso cref="all"/>
public int index
{
get
{
if (m_Id == InvalidId)
throw new InvalidOperationException("Invalid user");
var userIndex = TryFindUserIndex(m_Id);
if (userIndex == -1)
throw new InvalidOperationException($"User with ID {m_Id} is no longer valid");
return userIndex;
}
}
/// <summary>
/// The unique numeric ID of the user.
/// </summary>
/// <remarks>
/// The ID of a user is internally assigned and cannot be changed over its lifetime. No two users, even
/// if not concurrently active, will receive the same ID.
///
/// Note that this is not the same as the platform's internal user ID (if relevant on the current
/// platform). To get the ID that the platform uses to identify the user, use <see cref="platformUserAccountHandle"/>.
///
/// The ID stays valid and unique even if the user is removed and no longer <see cref="valid"/>.
/// </remarks>
/// <seealso cref="platformUserAccountHandle"/>
public uint id => m_Id;
/// <summary>
/// If the user is is associated with a user account at the platform level, this is the handle used by the
/// underlying platform API for the account.
/// </summary>
/// <remarks>
/// Users may be associated with user accounts defined by the platform we are running on. Consoles, for example,
/// have user account management built into the OS and marketplaces like Steam also have APIs for user management.
///
/// If this property is not <c>null</c>, it is the handle associated with the user at the platform level. This can
/// be used, for example, to call platform-specific APIs to fetch additional information about the user (such as
/// user profile images).
///
/// Be aware that there may be multiple InputUsers that have the same platformUserAccountHandle in case the platform
/// allows different players to log in on the same user account.
/// </remarks>
/// <seealso cref="platformUserAccountName"/>
/// <seealso cref="platformUserAccountId"/>
/// <seealso cref="InputUserChange.AccountChanged"/>
public InputUserAccountHandle? platformUserAccountHandle => s_AllUserData[index].platformUserAccountHandle;
/// <summary>
/// Human-readable name assigned to the user account at the platform level.
/// </summary>
/// <remarks>
/// This property will be <c>null</c> on platforms that do not have user account management. In that case,
/// <see cref="platformUserAccountHandle"/> will be <c>null</c> as well.
///
/// On platforms such as Xbox, PS4, and Switch, the user name will be the name of the user as logged in on the platform.
/// </remarks>
/// <seealso cref="platformUserAccountHandle"/>
/// <seealso cref="platformUserAccountId"/>
/// <seealso cref="InputUserChange.AccountChanged"/>
/// <seealso cref="InputUserChange.AccountNameChanged"/>
public string platformUserAccountName => s_AllUserData[index].platformUserAccountName;
/// <summary>
/// Platform-specific user ID that is valid across sessions even if the <see cref="platformUserAccountName"/> of
/// the user changes.
/// </summary>
/// <remarks>
/// This is only valid if <see cref="platformUserAccountHandle"/> is not null.
///
/// Use this to, for example, associate application settings with the user. For display in UIs, use
/// <see cref="platformUserAccountName"/> instead.
/// </remarks>
/// <seealso cref="platformUserAccountHandle"/>
/// <seealso cref="platformUserAccountName"/>
/// <seealso cref="InputUserChange.AccountChanged"/>
public string platformUserAccountId => s_AllUserData[index].platformUserAccountId;
////REVIEW: Does it make sense to track used devices separately from paired devices?
/// <summary>
/// Devices assigned/paired/linked to the user.
/// </summary>
/// <remarks>
/// It is generally valid for a device to be assigned to multiple users. For example, two users could
/// both use the local keyboard in a split-keyboard or hot seat setup. However, a platform may restrict this
/// and mandate that a device never belong to more than one user. This is the case on Xbox and PS4, for
/// example.
///
/// To associate devices with users, use <see cref="PerformPairingWithDevice"/>. To remove devices, use
/// <see cref="UnpairDevice"/> or <see cref="UnpairDevicesAndRemoveUser"/>.
///
/// The array will be empty for a user who is currently not paired to any devices.
///
/// If <see cref="actions"/> is set (<see cref="AssociateActionsWithUser(IInputActionCollection)"/>), then
/// <see cref="IInputActionCollection.devices"/> will be kept synchronized with the devices paired to the user.
/// </remarks>
/// <seealso cref="PerformPairingWithDevice"/>
/// <seealso cref="UnpairDevice"/>
/// <seealso cref="UnpairDevices"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.DevicePaired"/>
/// <seealso cref="InputUserChange.DeviceUnpaired"/>
public ReadOnlyArray<InputDevice> pairedDevices
{
get
{
var userIndex = index;
return new ReadOnlyArray<InputDevice>(s_AllPairedDevices, s_AllUserData[userIndex].deviceStartIndex,
s_AllUserData[userIndex].deviceCount);
}
}
/// <summary>
/// Devices that were removed while they were still paired to the user.
/// </summary>
/// <remarks>
///
/// This list is cleared once the user has either regained lost devices or has regained other devices
/// such that the <see cref="controlScheme"/> is satisfied.
/// </remarks>
/// <seealso cref="InputUserChange.DeviceRegained"/>
/// <seealso cref="InputUserChange.DeviceLost"/>
public ReadOnlyArray<InputDevice> lostDevices
{
get
{
var userIndex = index;
return new ReadOnlyArray<InputDevice>(s_AllLostDevices, s_AllUserData[userIndex].lostDeviceStartIndex,
s_AllUserData[userIndex].lostDeviceCount);
}
}
/// <summary>
/// Actions associated with the user.
/// </summary>
/// <remarks>
/// Associating actions with a user will synchronize the actions with the devices paired to the
/// user. Also, it makes it possible to use support for control scheme activation (<see
/// cref="ActivateControlScheme(InputControlScheme)"/> and related APIs like <see cref="controlScheme"/>
/// and <see cref="controlSchemeMatch"/>).
///
/// Note that is generally does not make sense for users to share actions. Instead, each user should
/// receive a set of actions private to the user.
///
/// If <see cref="settings"/> are applied with customized bindings (<see cref="InputUserSettings.customBindings"/>),
/// these are applied automatically to the actions.
/// </remarks>
/// <seealso cref="AssociateActionsWithUser(IInputActionCollection)"/>
/// <seealso cref="InputActionMap"/>
/// <seealso cref="InputActionAsset"/>
/// <seealso cref="InputUserChange.BindingsChanged"/>
public IInputActionCollection actions => s_AllUserData[index].actions;
/// <summary>
/// The control scheme currently employed by the user.
/// </summary>
/// <remarks>
/// This is null by default.
///
/// Any time the value of this property changes (whether by <see cref="SetControlScheme"/>
/// or by automatic switching), a notification is sent on <see cref="onChange"/> with
/// <see cref="InputUserChange.ControlSchemeChanged"/>.
///
/// Be aware that using control schemes with InputUsers requires <see cref="actions"/> to
/// be set, i.e. input actions to be associated with the user (<see
/// cref="AssociateActionsWithUser(IInputActionCollection)"/>).
/// </remarks>
/// <seealso cref="ActivateControlScheme(string)"/>
/// <seealso cref="ActivateControlScheme(InputControlScheme)"/>
/// <seealso cref="InputUserChange.ControlSchemeChanged"/>
public InputControlScheme? controlScheme => s_AllUserData[index].controlScheme;
/// <summary>
/// The result of matching the device requirements given by <see cref="controlScheme"/> against
/// the devices paired to the user (<see cref="pairedDevices"/>).
/// </summary>
/// <remarks>
/// When devices are paired to or unpaired from a user, as well as when a new control scheme is
/// activated on a user, this property is updated automatically.
/// </remarks>
/// <seealso cref="InputControlScheme.deviceRequirements"/>
/// <seealso cref="InputControlScheme.PickDevicesFrom{TDevices}"/>
public InputControlScheme.MatchResult controlSchemeMatch => s_AllUserData[index].controlSchemeMatch;
/// <summary>
/// Whether the user is missing devices required by the <see cref="controlScheme"/> activated
/// on the user.
/// </summary>
/// <remarks>
/// This will only take required devices into account. Device requirements marked optional (<see
/// cref="InputControlScheme.DeviceRequirement.isOptional"/>) will not be considered missing
/// devices if they cannot be satisfied based on the devices paired to the user.
/// </remarks>
/// <seealso cref="InputControlScheme.deviceRequirements"/>
public bool hasMissingRequiredDevices => s_AllUserData[index].controlSchemeMatch.hasMissingRequiredDevices;
/// <summary>
/// List of all current users.
/// </summary>
/// <remarks>
/// Use <see cref="PerformPairingWithDevice"/> to add new users and <see cref="UnpairDevicesAndRemoveUser"/> to
/// remove users.
///
/// Note that this array does not necessarily correspond to the list of users present at the platform level
/// (e.g. Xbox and PS4). There can be users present at the platform level that are not present in this array
/// (e.g. because they are not joined to the game) and users can even be present more than once (e.g. if
/// playing on the user account but as two different players in the game). Also, there can be users in the array
/// that are not present at the platform level.
/// </remarks>
/// <seealso cref="PerformPairingWithDevice"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
public static ReadOnlyArray<InputUser> all => new ReadOnlyArray<InputUser>(s_AllUsers, 0, s_AllUserCount);
/// <summary>
/// Event that is triggered when the <see cref="InputUser">user</see> setup in the system
/// changes.
/// </summary>
/// <remarks>
/// Each notification receives the user that was affected by the change and, in the form of <see cref="InputUserChange"/>,
/// a description of what has changed about the user. The third parameter may be null but if the change will be related
/// to an input device, will reference the device involved in the change.
/// </remarks>
public static event Action<InputUser, InputUserChange, InputDevice> onChange
{
add
{
if (value == null)
throw new ArgumentNullException(nameof(value));
s_OnChange.AppendWithCapacity(value);
}
remove
{
if (value == null)
throw new ArgumentNullException(nameof(value));
var index = s_OnChange.IndexOf(value);
if (index != -1)
s_OnChange.RemoveAtWithCapacity(index);
}
}
/// <summary>
/// Event that is triggered when a device is used that is not currently paired to any user.
/// </summary>
/// <remarks>
/// A device is considered "used" when it has magnitude (<see cref="InputControl.EvaluateMagnitude()"/>) greater than zero
/// on a control that is not noisy (<see cref="InputControl.noisy"/>) and not synthetic (i.e. not a control that is
/// "made up" like <see cref="Keyboard.anyKey"/>; <see cref="InputControl.synthetic"/>).
///
/// Detecting the use of unpaired devices has a non-zero cost. While multiple levels of tests are applied to try to
/// cheaply ignore devices that have events sent to them that do not contain user activity, finding out whether
/// a device had real user activity will eventually require going through the device control by control.
///
/// To enable detection of the use of unpaired devices, set <see cref="listenForUnpairedDeviceActivity"/> to true.
/// It is disabled by default.
///
/// The callback is invoked for each non-leaf, non-synthetic, non-noisy control that has been actuated on the device.
/// It being restricted to non-leaf controls means that if, say, the stick on a gamepad is actuated in both X and Y
/// direction, you will see two calls: one with stick/x and one with stick/y.
///
/// The reason that the callback is invoked for each individual control is that pairing often relies on checking
/// for specific kinds of interactions. For example, a pairing callback may listen exclusively for button presses.
///
/// Note that whether the use of unpaired devices leads to them getting paired is under the control of the application.
/// If the device should be paired, invoke <see cref="PerformPairingWithDevice"/> from the callback. If you do so,
/// no further callbacks will get triggered for other controls that may have been actuated in the same event.
///
/// Be aware that the callback is fired <em>before</em> input is actually incorporated into the device (it is
/// indirectly triggered from <see cref="InputSystem.onEvent"/>). This means at the time the callback is run,
/// the state of the given device does not yet have the input that triggered the callback. For this reason, the
/// callback receives a second argument that references the event from which the use of an unpaired device was
/// detected.
///
/// What this sequence allows is to make changes to the system before the input is processed. For example, an
/// action that is enabled as part of the callback will subsequently respond to the input that triggered the
/// callback.
///
/// <example>
/// <code>
/// // Activate support for listening to device activity.
/// InputUser.listenForUnpairedDeviceActivity = true;
///
/// // When a button on an unpaired device is pressed, pair the device to a new
/// // or existing user.
/// InputUser.onUnpairedDeviceUsed +=
/// usedControl =>
/// {
/// // Only react to button presses on unpaired devices.
/// if (!(usedControl is ButtonControl))
/// return;
///
/// // Pair the device to a user.
/// InputUser.PerformPairingWithDevice(usedControl.device);
/// };
///
/// InputUser.onChange +=
/// (user, change) =>
/// {
/// ////TODO
/// };
/// </code>
/// </example>
///
/// Another possible use of the callback is for implementing automatic control scheme switching for a user such that
/// the user can, for example, switch from keyboard&mouse to gamepad seamlessly by simply picking up the gamepad
/// and starting to play.
/// </remarks>
public static event Action<InputControl, InputEventPtr> onUnpairedDeviceUsed
{
add
{
if (value == null)
throw new ArgumentNullException(nameof(value));
s_OnUnpairedDeviceUsed.AppendWithCapacity(value);
if (s_ListenForUnpairedDeviceActivity > 0)
HookIntoEvents();
}
remove
{
if (value == null)
throw new ArgumentNullException(nameof(value));
var index = s_OnUnpairedDeviceUsed.IndexOf(value);
if (index != -1)
s_OnUnpairedDeviceUsed.RemoveAtWithCapacity(index);
if (s_OnUnpairedDeviceUsed.length == 0)
UnhookFromDeviceStateChange();
}
}
/// <summary>
/// Whether to listen for user activity on currently unpaired devices and invoke <see cref="onUnpairedDeviceUsed"/>
/// if such activity is detected.
/// </summary>
/// <remarks>
/// This is off by default.
///
/// Note that enabling this has a non-zero cost. Whenever the state changes of a device that is not currently paired
/// to a user, the system has to spend time figuring out whether there was a meaningful change or whether it's just
/// noise on the device.
///
/// This is an integer rather than a bool to allow multiple systems to concurrently use to listen for unpaired
/// device activity without treading on each other when enabling/disabling the code path.
/// </remarks>
/// <seealso cref="onUnpairedDeviceUsed"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="PerformPairingWithDevice"/>
public static int listenForUnpairedDeviceActivity
{
get => s_ListenForUnpairedDeviceActivity;
set
{
if (value < 0)
throw new ArgumentOutOfRangeException(nameof(value), "Cannot be negative");
if (value > 0 && s_OnUnpairedDeviceUsed.length > 0)
HookIntoEvents();
else if (value == 0)
UnhookFromDeviceStateChange();
s_ListenForUnpairedDeviceActivity = value;
}
}
/// <summary>
/// Associate an .inputactions asset with the user.
/// </summary>
/// <param name="actions"></param>
/// <exception cref="InvalidOperationException"></exception>
public void AssociateActionsWithUser(IInputActionCollection actions)
{
var userIndex = index; // Throws if user is invalid.
if (s_AllUserData[userIndex].actions == actions)
return;
// If we already had actions associated, reset the binding mask and device list.
var oldActions = s_AllUserData[userIndex].actions;
if (oldActions != null)
{
oldActions.devices = null;
oldActions.bindingMask = null;
}
s_AllUserData[userIndex].actions = actions;
// If we've switched to a different set of actions, synchronize our state.
if (actions != null)
{
actions.devices = pairedDevices;
if (s_AllUserData[userIndex].controlScheme != null)
ActivateControlSchemeInternal(userIndex, s_AllUserData[userIndex].controlScheme.Value);
}
}
public ControlSchemeChangeSyntax ActivateControlScheme(string schemeName)
{
// Look up control scheme by name in actions.
var scheme = new InputControlScheme();
if (!string.IsNullOrEmpty(schemeName))
{
var userIndex = index; // Throws if user is invalid.
// Need actions to be available to be able to activate control schemes
// by name only.
if (s_AllUserData[userIndex].actions == null)
throw new InvalidOperationException(
$"Cannot set control scheme '{schemeName}' by name on user #{userIndex} as not actions have been associated with the user yet (AssociateActionsWithUser)");
var controlSchemes = s_AllUserData[userIndex].actions.controlSchemes;
for (var i = 0; i < controlSchemes.Count; ++i)
if (string.Compare(controlSchemes[i].name, schemeName,
StringComparison.InvariantCultureIgnoreCase) == 0)
{
scheme = controlSchemes[i];
break;
}
// Throw if we can't find it.
if (scheme == default)
throw new ArgumentException(
$"Cannot find control scheme '{schemeName}' in actions '{s_AllUserData[userIndex].actions}'");
}
return ActivateControlScheme(scheme);
}
public ControlSchemeChangeSyntax ActivateControlScheme(InputControlScheme scheme)
{
var userIndex = index; // Throws if user is invalid.
if (s_AllUserData[userIndex].controlScheme != scheme ||
(scheme == default && s_AllUserData[userIndex].controlScheme != null))
{
ActivateControlSchemeInternal(userIndex, scheme);
Notify(userIndex, InputUserChange.ControlSchemeChanged, null);
}
return new ControlSchemeChangeSyntax {m_UserIndex = userIndex};
}
private void ActivateControlSchemeInternal(int userIndex, InputControlScheme scheme)
{
var isEmpty = scheme == default;
if (isEmpty)
s_AllUserData[userIndex].controlScheme = null;
else
s_AllUserData[userIndex].controlScheme = scheme;
if (s_AllUserData[userIndex].actions != null)
{
if (isEmpty)
{
s_AllUserData[userIndex].actions.bindingMask = null;
s_AllUserData[userIndex].controlSchemeMatch.Dispose();
s_AllUserData[userIndex].controlSchemeMatch = new InputControlScheme.MatchResult();
}
else
{
s_AllUserData[userIndex].actions.bindingMask = new InputBinding {groups = scheme.bindingGroup};
UpdateControlSchemeMatch(userIndex);
}
}
}
public void PauseHaptics()
{
////TODO
}
public void ResumeHaptics()
{
////TODO
}
public void ResetHaptics()
{
////TODO
}
/// <summary>
/// Unpair a single device from the user.
/// </summary>
/// <param name="device">Device to unpair from the user. If the device is not currently paired to the user,
/// the method does nothing.</param>
/// <exception cref="ArgumentNullException"><paramref name="device"/> is <c>null</c>.</exception>
/// <remarks>
/// If actions are associated with the user (<see cref="actions"/>), the list of devices used by the
/// actions (<see cref="IInputActionCollection.devices"/>) is automatically updated.
///
/// If a control scheme is activated on the user (<see cref="controlScheme"/>), <see cref="controlSchemeMatch"/>
/// is automatically updated.
///
/// Sends <see cref="InputUserChange.DeviceUnpaired"/> through <see cref="onChange"/>.
/// </remarks>
/// <seealso cref="PerformPairingWithDevice"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="UnpairDevices"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.DeviceUnpaired"/>
public void UnpairDevice(InputDevice device)
{
if (device == null)
throw new ArgumentNullException(nameof(device));
var userIndex = index; // Throws if user is invalid.
// Ignore if not currently paired to user.
if (!pairedDevices.ContainsReference(device))
return;
RemoveDeviceFromUser(userIndex, device);
}
/// <summary>
/// Unpair all devices from the user.
/// </summary>
/// <remarks>
/// If actions are associated with the user (<see cref="actions"/>), the list of devices used by the
/// actions (<see cref="IInputActionCollection.devices"/>) is automatically updated.
///
/// If a control scheme is activated on the user (<see cref="controlScheme"/>), <see cref="controlSchemeMatch"/>
/// is automatically updated.
///
/// Sends <see cref="InputUserChange.DeviceUnpaired"/> through <see cref="onChange"/> for every device
/// unpaired from the user.
/// </remarks>
/// <seealso cref="PerformPairingWithDevice"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="UnpairDevice"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.DeviceUnpaired"/>
public void UnpairDevices()
{
var userIndex = index; // Throws if user is invalid.
// Reset device count so it appears all devices are gone from the user. We still want to send
// notifications one by one, so we can't yet remove the devices from s_AllPairedDevices.
var deviceCount = s_AllUserData[userIndex].deviceCount;
var deviceStartIndex = s_AllUserData[userIndex].deviceStartIndex;
s_AllUserData[userIndex].deviceCount = 0;
s_AllUserData[deviceStartIndex].deviceStartIndex = 0;
// Update actions, if necessary.
var actions = s_AllUserData[userIndex].actions;
if (actions != null)
actions.devices = null;
// Update control scheme, if necessary.
if (s_AllUserData[userIndex].controlScheme != null)
UpdateControlSchemeMatch(userIndex);
// Notify.
for (var i = 0; i < deviceCount; ++i)
Notify(userIndex, InputUserChange.DeviceUnpaired, s_AllPairedDevices[deviceStartIndex + i]);
// Remove.
ArrayHelpers.EraseSliceWithCapacity(ref s_AllPairedDevices, ref s_AllPairedDeviceCount, deviceStartIndex, deviceCount);
// Adjust indices of other users.
for (var i = 0; i < s_AllUserCount; ++i)
{
if (s_AllUserData[i].deviceStartIndex <= deviceStartIndex)
continue;
s_AllUserData[i].deviceStartIndex -= deviceCount;
}
}
/// <summary>
/// Unpair all devices from the user and remove the user.
/// </summary>
/// <remarks>
/// If actions are associated with the user (<see cref="actions"/>), the list of devices used by the
/// actions (<see cref="IInputActionCollection.devices"/>) is reset as is the binding mask (<see
/// cref="IInputActionCollection.bindingMask"/>) in case a control scheme is activated on the user.
///
/// Sends <see cref="InputUserChange.DeviceUnpaired"/> through <see cref="onChange"/> for every device
/// unpaired from the user.
///
/// Sends <see cref="InputUserChange.Removed"/>.
/// </remarks>
/// <seealso cref="PerformPairingWithDevice"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="UnpairDevice"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.DeviceUnpaired"/>
/// <seealso cref="InputUserChange.Removed"/>
public void UnpairDevicesAndRemoveUser()
{
UnpairDevices();
var userIndex = index;
RemoveUser(userIndex);
}
/// <summary>
/// Return a list of all currently added devices that are not paired to any user.
/// </summary>
/// <returns>A (possibly empty) list of devices that are currently not paired to a user.</returns>
/// <remarks>
/// The resulting list uses <see cref="Allocator.Temp"> temporary, unmanaged memory</see>. If not disposed of
/// explicitly, the list will automatically be deallocated at the end of the frame and will become unusable.
/// </remarks>
/// <seealso cref="InputSystem.devices"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="PerformPairingWithDevice"/>
public static InputControlList<InputDevice> GetUnpairedInputDevices()
{
var list = new InputControlList<InputDevice>(Allocator.Temp);
GetUnpairedInputDevices(ref list);
return list;
}
/// <summary>
/// Add all currently added devices that are not paired to any user to <paramref name="list"/>.
/// </summary>
/// <param name="list">List to add the devices to. Devices will be added to the end.</param>
/// <returns>Number of devices added to <paramref name="list"/>.</returns>
/// <seealso cref="InputSystem.devices"/>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="PerformPairingWithDevice"/>
public static int GetUnpairedInputDevices(ref InputControlList<InputDevice> list)
{
var countBefore = list.Count;
foreach (var device in InputSystem.devices)
{
// If it's in s_AllPairedDevices, there is *some* user that is using the device.
// We don't care which one it is here.
if (ArrayHelpers.ContainsReference(s_AllPairedDevices, s_AllPairedDeviceCount, device))
continue;
list.Add(device);
}
return list.Count - countBefore;
}
/// <summary>
/// Find the user (if any) that <paramref name="device"/> is currently paired to.
/// </summary>
/// <param name="device">An input device.</param>
/// <returns>The user that <paramref name="device"/> is currently paired to or <c>null</c> if the device
/// is not currently paired to an user.</returns>
/// <remarks>
/// Note that multiple users may be paired to the same device. If that is the case for <paramref name="device"/>,
/// the method will return one of the users with no guarantee which one it is.
///
/// To find all users paired to a device requires manually going through the list of users and their paired
/// devices.
/// </remarks>
/// <exception cref="ArgumentNullException"><paramref name="device"/> is <c>null</c>.</exception>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="PerformPairingWithDevice"/>
public static InputUser? FindUserPairedToDevice(InputDevice device)
{
if (device == null)
throw new ArgumentNullException(nameof(device));
var userIndex = TryFindUserIndex(device);
if (userIndex == -1)
return null;
return s_AllUsers[userIndex];
}
public static InputUser? FindUserByAccount(InputUserAccountHandle platformUserAccountHandle)
{
if (platformUserAccountHandle == default(InputUserAccountHandle))
throw new ArgumentException("Empty platform user account handle", nameof(platformUserAccountHandle));
var userIndex = TryFindUserIndex(platformUserAccountHandle);
if (userIndex == -1)
return null;
return s_AllUsers[userIndex];
}
public static InputUser CreateUserWithoutPairedDevices()
{
var userIndex = AddUser();
return s_AllUsers[userIndex];
}
////REVIEW: allow re-adding a user through this method?
/// <summary>
/// Pair the given device to a user.
/// </summary>
/// <param name="device">Device to pair to a user.</param>
/// <param name="user">Optional parameter. If given, instead of creating a new user to pair the device
/// to, the device is paired to the given user.</param>
/// <param name="options">Optional set of options to modify pairing behavior.</param>
/// <remarks>
/// By default, a new user is created and <paramref name="device"/> is added <see cref="pairedDevices"/>
/// of the user and <see cref="InputUserChange.DevicePaired"/> is sent on <see cref="onChange"/>.
///
/// If a valid user is supplied to <paramref name="user"/>, the device is paired to the given user instead
/// of creating a new user. By default, the device is added to the list of already paired devices for the user.
/// This can be changed by using <see cref="InputUserPairingOptions.UnpairCurrentDevicesFromUser"/> which causes
/// devices currently paired to the user to first be unpaired.
///
/// The method will not prevent pairing of the same device to multiple users.
///
/// Note that if the user has an associated set of actions (<see cref="actions"/>), the list of devices on the
/// actions (<see cref="IInputActionCollection.devices"/>) will automatically be updated meaning that the newly
/// paired devices will automatically reflect in the set of devices available to the user's actions. If the
/// user has a control scheme that is currently activated (<see cref="controlScheme"/>), then <see cref="controlSchemeMatch"/>
/// will also automatically update to reflect the matching of devices to the control scheme's device requirements.
///
/// If the given device is associated with a user account at the platform level (queried through
/// <see cref="QueryPairedUserAccountCommand"/>), the user's platform account details (<see cref="platformUserAccountHandle"/>,
/// <see cref="platformUserAccountName"/>, and <see cref="platformUserAccountId"/>) are updated accordingly. In this case,
/// <see cref="InputUserChange.AccountChanged"/> or <see cref="InputUserChange.AccountNameChanged"/> may be signalled.
/// through <see cref="onChange"/>.
///
/// If the given device is not associated with a user account at the platform level, but it does
/// respond to <see cref="InitiateUserAccountPairingCommand"/>, then the device is NOT immediately paired
/// to the user. Instead, pairing is deferred to until after an account selection has been made by the user.
/// In this case, <see cref="InputUserChange.AccountSelectionInProgress"/> will be signalled through <see cref="onChange"/>
/// and <see cref="InputUserChange.AccountChanged"/> will be signalled once the user has selected an account or
/// <see cref="InputUserChange.AccountSelectionCanceled"/> will be signalled if the user cancels account
/// selection. The device will be paired to the user once account selection is complete.
///
/// This behavior is most useful on Xbox and Switch to require the user to choose which account to play with. Note that
/// if the device is already associated with a user account, account selection will not be initiated. However,
/// it can be explicitly forced to be performed by using <see
/// cref="InputUserPairingOptions.ForcePlatformUserAccountSelection"/>. This is useful,
/// for example, to allow the user to explicitly switch accounts.
///
/// On Xbox and Switch, to permit playing even on devices that do not currently have an associated user account,
/// use <see cref="InputUserPairingOptions.ForceNoPlatformUserAccountSelection"/>.
///
/// On PS4, devices will always have associated user accounts meaning that the returned InputUser will always
/// have updated platform account details.
///
/// Note that user account queries and initiating account selection can be intercepted by the application. For
/// example, on Switch where user account pairing is not stored at the platform level, one can, for example, both
/// implement custom pairing logic as well as a custom account selection UI by intercepting <see cref="QueryPairedUserAccountCommand"/>
/// and <seealso cref="InitiateUserAccountPairingCommand"/>.
///
/// <example>
/// <code>
/// InputSystem.onDeviceCommand +=
/// (device, commandPtr, runtime) =>
/// {
/// // Dealing with InputDeviceCommands requires handling raw pointers.
/// unsafe
/// {
/// // We're only looking for QueryPairedUserAccountCommand and InitiateUserAccountPairingCommand here.
/// if (commandPtr->type != QueryPairedUserAccountCommand.Type && commandPtr->type != InitiateUserAccountPairingCommand)
/// return null; // Command not handled.
///
/// // Check if device is the one your interested in. As an example, we look for Switch gamepads
/// // here.
/// if (!(device is Npad))
/// return null; // Command not handled.
///
/// // If it's a QueryPairedUserAccountCommand, see if we have a user ID to use with the Npad
/// // based on last time the application ran.
/// if (commandPtr->type == QueryPairedUserAccountCommand.Type)
/// {
/// ////TODO
/// }
/// };
/// </code>
/// </example>
/// </remarks>
/// <example>
/// <code>
/// // Pair device to new user.
/// var user = InputUser.PerformPairingWithDevice(wand1);
///
/// // Pair another device to the same user.
/// InputUser.PerformPairingWithDevice(wand2, user: user);
/// </code>
/// </example>
/// <seealso cref="pairedDevices"/>
/// <seealso cref="UnpairDevice"/>
/// <seealso cref="UnpairDevices"/>
/// <seealso cref="UnpairDevicesAndRemoveUser"/>
/// <seealso cref="InputUserChange.DevicePaired"/>
public static InputUser PerformPairingWithDevice(InputDevice device,
InputUser user = default(InputUser),
InputUserPairingOptions options = InputUserPairingOptions.None)
{
if (device == null)
throw new ArgumentNullException(nameof(device));
if (user != default(InputUser) && !user.valid)
throw new ArgumentException("Invalid user", nameof(user));
// Create new user, if needed.
int userIndex;
if (user == default(InputUser))
{
userIndex = AddUser();
}
else
{
// We have an existing user.
userIndex = user.index;
// See if we're supposed to clear out the user's currently paired devices first.
if ((options & InputUserPairingOptions.UnpairCurrentDevicesFromUser) != 0)
user.UnpairDevices();
// Ignore call if device is already paired to user.
if (user.pairedDevices.ContainsReference(device))
{
// Still might have to initiate user account selection.
if ((options & InputUserPairingOptions.ForcePlatformUserAccountSelection) != 0)
InitiateUserAccountSelection(userIndex, device, options);
return user;
}
}
// Handle the user account side of pairing.
var accountSelectionInProgress = InitiateUserAccountSelection(userIndex, device, options);
// Except if we have initiate user account selection, pair the device to
// to the user now.
if (!accountSelectionInProgress)
AddDeviceToUser(userIndex, device);
return s_AllUsers[userIndex];
}
private static bool InitiateUserAccountSelection(int userIndex, InputDevice device,
InputUserPairingOptions options)
{
// See if there's a platform user account we can get from the device.
// NOTE: We don't query the current user account if the caller has opted to force account selection.
var queryUserAccountResult =
(options & InputUserPairingOptions.ForcePlatformUserAccountSelection) == 0
? UpdatePlatformUserAccount(userIndex, device)
: 0;
////REVIEW: what should we do if there already is an account selection in progress? InvalidOperationException?
// If the device supports user account selection but we didn't get one,
// try to initiate account selection.
if ((options & InputUserPairingOptions.ForcePlatformUserAccountSelection) != 0 ||
(queryUserAccountResult != InputDeviceCommand.GenericFailure &&
(queryUserAccountResult & (long)QueryPairedUserAccountCommand.Result.DevicePairedToUserAccount) == 0 &&
(options & InputUserPairingOptions.ForceNoPlatformUserAccountSelection) == 0))
{
if (InitiateUserAccountSelectionAtPlatformLevel(device))
{
s_AllUserData[userIndex].flags |= UserFlags.UserAccountSelectionInProgress;
s_OngoingAccountSelections.Append(
new OngoingAccountSelection
{
device = device,
userId = s_AllUsers[userIndex].id,
});
// Make sure we receive a notification for the configuration event.
HookIntoDeviceChange();
// Tell listeners that we started an account selection.
Notify(userIndex, InputUserChange.AccountSelectionInProgress, device);
return true;
}
}
return false;
}
public bool Equals(InputUser other)
{
return m_Id == other.m_Id;
}
public override bool Equals(object obj)
{
if (ReferenceEquals(null, obj))
return false;
return obj is InputUser && Equals((InputUser)obj);
}
public override int GetHashCode()
{
return (int)m_Id;
}
public static bool operator==(InputUser left, InputUser right)
{
return left.m_Id == right.m_Id;
}
public static bool operator!=(InputUser left, InputUser right)
{
return left.m_Id != right.m_Id;
}
/// <summary>
/// Add a new user.
/// </summary>
/// <returns>Index of the newly created user.</returns>
/// <remarks>
/// Adding a user sends a notification with <see cref="InputUserChange.Added"/> through <see cref="onChange"/>.
///
/// The user will start out with no devices and no actions assigned.
///
/// The user is added to <see cref="all"/>.
/// </remarks>
private static int AddUser()
{
var id = ++s_LastUserId;
// Add to list.
var userCount = s_AllUserCount;
ArrayHelpers.AppendWithCapacity(ref s_AllUsers, ref userCount, new InputUser {m_Id = id});
var userIndex = ArrayHelpers.AppendWithCapacity(ref s_AllUserData, ref s_AllUserCount, new UserData());
// Send notification.
Notify(userIndex, InputUserChange.Added, null);
return userIndex;
}