/usr/share/psychtoolbox-3/PsychBasic/KbQueueStart.m is in psychtoolbox-3-common 3.0.11.20131230.dfsg1-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | function KbQueueStart(deviceIndex)
% KbQueueStart([deviceIndex])
%
% The routines KbQueueCreate, KbQueueStart, KbQueueStop, KbQueueCheck
% KbQueueWait, KbQueueFlush and KbQueueRelease provide replacments for
% KbCheck and KbWait, providing the following advantages:
%
% 1) Brief key presses that would be missed by KbCheck or KbWait
% are reliably detected
% 2) The times of key presses are recorded more accurately
% 3) The times of key releases are also recorded
%
% Limitations:
%
% 1) If a key is pressed multiple times before KbQueueCheck is called,
% only the times of the first and last presses and releases of that
% key can be recovered (this has no effect on other keys)
% 2) If many keys are pressed very quickly in succession, it is at least
% theoretically possible for the queue to fill more quickly than
% it can be emptied, losing key events temporarily while filled to
% capacity. The queue holds up to thirty events, and events are
% constantly being removed from the queue and processed, so this is
% unlikely to be a problem in actual use.
%
% Only a single device can be monitored at any given time. The deviceNumber can
% be specified only in the call to KbQueueCreate. The other routines then
% relate to that specified device. If deviceNumber is not specified, the first
% device is the default (like KbCheck). If KbQueueCreate has not been called
% first, the other routines will generate an error message. Likewise, if
% KbQueueRelease has been called more recently than KbQueueCreate, the other
% routines will generate error messages.
%
% It is acceptable to call KbQueueCreate at any time (e.g., to switch to a new
% device or to change the list of queued keys) without calling KbQueueRelease.
%
% KbQueueCreate([deviceNumber, keyList])
% Creates the queue for the specified (or default) device number
% If the device number is less than zero, the default device is used.
% keyList is an optional 256-length vector of doubles (not logicals)
% with each element corresponding to a particular key (use KbName
% to map between keys and their positions). If the double value
% corresponding to a particular key is zero, events for that key
% are not added to the queue and will not be reported.
% No events are delivered to the queue until KbQueueStart or
% KbQueueWait is called.
% KbQueueCreate can be called again at any time
%
% KbQueueStart()
% Starts delivering keyboard events from the specified device to the
% queue.
%
% KbQueueStop()
% Stops delivery of new keyboard events from the specified device to
% the queue.
% Data regarding events already queued is not cleared and can be
% recovered by KbQueueCheck
%
% [pressed, firstPress, firstRelease, lastPress, lastRelease]=
% KbQueueCheck()
% Obtains data about keypresses on the specified device since the
% most recent call to this routine, KbQueueStart, KbQueuWait
% Clears all scored events, but unscored events that are still being
% processsed may remain in the queue
%
% pressed: a boolean indicating whether a key has been pressed
%
% firstPress: an array indicating the time that each key was first
% pressed since the most recent call to KbQueueCheck or KbQueueStart
%
% firstRelease: an array indicating the time that each key was first
% released since the most recent call to KbQueueCheck or KbQueueStart
%
% lastPress: an array indicating the most recent time that each key was
% pressed since the most recent call to KbQueueCheck or KbQueueStart
%
% lastRelease: an array indicating the most recent time that each key
% was released since the most recent call to KbQueueCheck or
% KbQueueStart
%
% For firstPress, firstRelease, lastPress and lastRelease, a time value
% of zero indicates that no event for the corresponding key was
% detected since the most recent call to KbQueueCheck or KbQueueStart
%
% To identify specific keys, use KbName (e.g., KbName(firstPress)) to
% generate a list of the keys for which the events occurred
%
% For compatibility with KbCheck, any key codes stored in
% ptb_kbcheck_disabledKeys (see "help DisableKeysForKbCheck"), will
% not caused pressed to return as true and will be zeroed out in the
% returned arrays. However, a better alternative is to specify a
% keyList arguement to KbQueueCreate.
%
% secs=KbQueueWait()
% Waits for any key to be pressed and returns the time of the press
%
% KbQueueFlush should be called immediately prior to this function
% (unless the queue has just been created and started) to clear any
% prior events.
%
% Note that this command will not respond to any keys that were
% inactivated by using the keyList argument to KbQueueCreate.
%
% Since KbQueueWait is implemented as a looping call to
% KbQueueCheck, it will not respond to any key codes stored in
% the global variable ptb_kbcheck_disabledKeys
% (see "help DisableKeysForKbCheck")
%
% KbQueueFlush()
% Removes all unprocessed events from the queue and zeros out any
% already scored events.
%
% KbQueueRelease()
% Releases queue-associated resources; once called, KbQueueCreate
% must be invoked before using any of the other routines
%
% This routine is called automatically at clean-up (e.g., when
% 'clear mex' is invoked and can be omitted expense of keeping
% memory allocated and an additional thread running unnecesarily
%
% Note that any keyboard typing used to invoke KbQueue commands will be
% recorded. This would include the release of the carriage return used
% to execute KbQueueStart and the keys pressed and released to invoke
% KbQueueCheck
% _________________________________________________________________________
%
% See also: KbQueueCreate, KbQueueStart, KbQueueStop, KbQueueCheck,
% KbQueueWait, KbQueueFlush, KbQueueRelease
% 8/19/07 rpw Wrote it.
% 8/23/07 rpw Modifications to add KbQueueFlush
if nargin < 1
deviceIndex = [];
end
% Try to check if keyboard queue for 'deviceIndex' is reserved for our exclusive use:
if ~KbQueueReserve(3, 2, deviceIndex) && KbQueueReserve(3, 1, deviceIndex)
error('Keyboard queue for device %i already in use by GetChar() et al. Use of GetChar and keyboard queues is mutually exclusive!', deviceIndex);
end
if nargin == 0
PsychHID('KbQueueStart');
elseif nargin > 0
PsychHID('KbQueueStart', deviceIndex);
end
|