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
|
function secs = KbTriggerWait(keyCode, deviceNumber)
% secs = KbTriggerWait(keyCode, [deviceNumber])
%
% Waits until one or more trigger keys have been pressed and returns the
% time of the first key press in seconds. The keyCode argument can be a
% vector of key indices. For example, to check for the 't' key as the
% trigger use KbTriggerWait(KbName('t')), to check for 't' and the escape
% key, use KbTriggerWait([KbName('t'), KbName('ESCAPE')]).
%
% You cannot use KbTriggerWait while a queue created by KbQueueCreate
% exists. To shut down such a queue, use KbQueueRelease.
%
% On Matlab versions older than R2007a on MS-Windows, this function simply
% serves as a convenient substitute for using KbCheck to detect the
% trigger of interest.
%
% This function should allow triggers to be reliably detected from devices
% that only briefly report that the key is down. KbCheck is not reliable
% with such devices because it may not poll often enough to detect the
% key down state.
%
% KbTriggerWait uses the PsychHID function, a general purpose function for
% reading from the Human Interface Device (HID) class of USB devices.
% Unlike KbCheck, it starts a queue that receives keyboard events
% regarding the trigger key (and no other keys) and then polls this queue
% (rather than the current key status) periodically. In theory, this
% should also provide more accurate reporting of the time of the
% triggering keypress. However, if multiple trigger events have occurred
% since last polled, it is possible that the timestamp of the earliest
% of these will have already rotated out of the limited capacity (eight
% events) queue. In this case, the time of the earliest event remaining
% in the queue is reported. Since the polling frequency is the same as
% KbCheck, it should be more accurate on average with regard to timing,
% even when the timestamps of the earliest events have been lost due to
% queue overflow.
%
% KbTriggerWait tests the first USB-HID keyboard device by default.
% Optionally, you can pass in a 'deviceNumber' to test a different keyboard
% if multiple keyboards are connected to your machine. The function also
% allows to wait for button presses on keypads, mice or other HID devices
% with buttons or keys.
%
% Passing a deviceNumber of -1 will NOT cause all keyboards to be detected
%
% One disadvantage of this function is that it renders Matlab relatively
% unresponsive to Ctrl-C interrupts. KbQueueWait is a better option in
% this regard, but more complicated to use.
% _________________________________________________________________________
%
% See also: KbQueueWait KbCheck, KbWait, GetChar, CharAvail, KbDemo.
% 8/10/07 rpw Wrote it.
% 8/21/07 rpw Added comments about KbQueueWait as alternative
% 8/23/07 rpw Added warning about incompatibility with KbQueueCreate, et al.
% 5/14/12 mk Add new OSX path, MS-Windows pre R2007a path, other
% tweaks.
persistent macosxrecent;
if isempty(macosxrecent)
macosxrecent = IsOSX;
LoadPsychHID;
end
% OSX? We no longer use PsychHID('KbTriggerWait'). Instead we emulate via
% the KbQueueXXX interface. This has two advantages:
% a) It works on 64-Bit OSX despite the incompatibilities and additional
% brain-damage added to the low-level interface by our friendly iPhone
% company.
% b) It allows to wait for multiple keys, just as on Linux and Windows.
%
% Timestamp precision won't suffer, as past improvements to PsychHID's
% KbQueue routines now query timestamps from the OS itself for high
% precision.
%
if macosxrecent
if nargin==2
% Nothing to do.
elseif nargin == 1
deviceNumber = [];
elseif nargin == 0
error('Trigger key code(s) must be specified in KbTriggerWait');
elseif nargin > 2
error('Too many arguments supplied to KbTriggerWait');
end
% Emulate KbTriggerWait via KbQueueWait:
keyCodes = zeros(1, 256);
keyCodes(keyCode) = 1;
KbQueueCreate(deviceNumber, keyCodes);
secs = KbQueueWait(deviceNumber);
KbQueueStop(deviceNumber);
KbQueueRelease(deviceNumber);
return;
end
if nargin < 2
deviceNumber = [];
end
% Try to reserve keyboard queue for 'deviceNumber' for our exclusive use:
if ~KbQueueReserve(1, 2, deviceNumber)
if isempty(deviceNumber)
deviceNumber = NaN;
end
error('Keyboard queue for device %i already in use by GetChar() et al. Use of GetChar and keyboard queues is mutually exclusive!', deviceNumber);
end
if nargin==2
[secs]= PsychHID('KbTriggerWait', keyCode, deviceNumber);
elseif nargin == 1
[secs]= PsychHID('KbTriggerWait', keyCode);
elseif nargin == 0
error('Trigger key code must be specified in KbTriggerWait');
elseif nargin > 2
error('Too many arguments supplied to KbTriggerWait');
end
% Try to release keyboard queue for 'deviceIndex' from our exclusive use:
KbQueueReserve(2, 2, deviceNumber);
|
