PsychPortAudio[DataPixx]TimingTest: Add triggerLevel option.

Add optional 'triggerLevel' parameter to control the threshold for
Datapixx detection of audio onset. Practice shows this needs tweaking
on many setups, so make it easy to tweak without hacking the code or
guessing reasons for failures or hangs.
GStreamer help: Clarify the need to install all components for full functionality.
InitializePsychSound: Stress the ASIO card requirement on MS-Windows.

There is no if, or maybe: ASIO is a must for any decent work on
MS-Windows.
BitsPlusIdentityClutTest: Some help text updates wrt. DataPixx.

Explain how to use it with Datapixx.
bvlWaitForInput: Fix mouse button mapping for Linux.

Mapping of button ids to middle/right mouse button was wrong. Caused
misassignment in DisplayUndistortionBVL on Linux.
IOPort: Don't return fully zero-filled datum on read timeout in reader thread.

If the os read timeout was reached in the async reader thread, we used
to return an empty item, zero-filled with readGranularity Bytes and a
timestamp. This is ok for short-reads, you get what you get, and then
some zero-padding. It is troublesome in the case of zero read bytes,
e.g., because we start the data reception in our script, but the sender
of data, e.g., a fMRI scanner isn't started yet.

Change this: A read of zero bytes, due to timeout reached, will be
skipped, just retrying for another timeout period, or until stop of
async background read. The higher level read code can handle timeout
properly by detecting it and returning an empty matrix to the calling
usercode.

The specific, hard to debug, failure case was this one, which caused so
much fun at the scanner:

This caused serious pain when trying to receive one-byte scanner
triggers, and it timed out due to scan not yet started and the valid
scanner trigger bytes are value==zero bytes, indistinguishable by
usercode from timeout. This injected "ghost triggers" from the
usercodes perspective, very bad!

IOPort for OSX (64-Bit Octave/Matlab, 32-Bit Matlab) rebuilt for
testing.
Screen/Windows: Fix HideCursor once more.

PsychHideCursor() should only replace the cursor by an invisible cursor
image if it hasn't done it already, otherwise PsychShowCursor() won't
be able to unhide the cursor anymore. This error case happens if
HideCursor() is called more than once in succession.

Fixed in code, not recompiled or tested.
Screen/Linux: Remove apitrace hack, solve it properly.

José Fonseca pointed out the proper solution to provide apitrace
compatibility. We use the same trick GLEW uses to define our own symbol
__glXGetSwapIntervalMESA and #define glXGetSwapIntervalMESA
__glXGetSwapIntervalMESA. This way it can't happen that our global
symbol gets overriden by apitrace's LD_PRELOAD'ed library.

Now apitrace works without need for any special tricks :)

Screen for 32-Bit Octave on Linux rebuilt and tested.
Implement GetChar() et al. on some non-Linux setups via KbQueues.

Octave and matlab -nojvm on OS/X, as well as matlab -nojvm
on Windows and any Matlab on Windows Vista or later have trouble
with the current GetChar implementation, iow. GetChar sucks on them:

1. "matlab -nojvm" and Octave in general don't support Java based
   GetChar. The low-level Unix style fallback in Linux works fine
   in those cases, providing reliable GetChar operation. The same
   Unix fallback on OSX fails miserably, apparently due to the way
   the windowing system dispatches key events on OSX, as does the
   MS-Windows low-level equivalent.

2. On Windows Vista and later, the graphics systems keyboard focus
   policy interferes and makes even Java based GetChar unuseable
   in conjunction with Screen() windows.

-> We need a new solution for those combos.

This reimplements ListenChar, FlushEvents, CharAvail and GetChar
on top of PsychHID keyboard queues, as those are in principle not
affected by the mess above. Those functions create and start a
keyboard queue for the default keyboard device, then use KbEventBuffer
mechanism to collect and dequeue key presses, cooked to ASCII codes.

On OS/X this will restrict GetChar et al. to the default keyboard.
On Windows, we can only access one keyboard, which is a virtual
system keyboard - the union of all real connected keyboards. But this
is what we ideally want, so one Windows design flaw turns into an
advantage for us at least once ;)

The problem here is that we only have one queue per keyboard, so
the queue handling the default keyboard can be either used by
GetChar et al., or by regular usercode via the KbQueueXXX and
KbEventXXX functions. A new locking mechanism arbitrates between
both on a first-come-first-served bases.

This commit is incomplete, as it needs more extensions to PsychHID,
and especially to PsychHID on OSX. But it implements the support
code in the M-Files and the arbitration.

PsychHID needs to somehow return a count of valid keypresses,
not only a total count, otherwise we can't implement CharAvail()
properly.

The keycode to ASCII code mapping on OSX is currently broken.

This also adds a new helper function IsVista() to check if the
system is a MS-Windows Vista or later system.
PsychHID: Add ability to only count mappable keystrokes in event buffer.

This is to make the KbQueue based GetChar() / CharAvail()
implementation work.
The 'KbQueueFlush' function now supports a flushType setting of & 4. If
used, the function will not return the full count of queued events for
a KbEvent buffer, but only the count of key down events with a
successfully mapped CookedKey field, ie. translated to valid
ASCII/Unicode character key strokes. This is basically what CharAvail()
needs to function properly.

PsychHID for MS-Windows 32/64-Bit Matlab rebuilt and tested.
PsychHID for OSX 64-Bit rebuilt for basic testing, but char mapping
doesn't yet work.
Finalize M-File portion of new GetChar implementation.

This one is successfully tested on MS-Windows-7 with 32/64-Bit Matlab
with JVM enabled. That combo does use the new implementation, so it
works with Win-Vista et al. sick way of window keyboard focus handling.
Additionally it uses the old Java based GetChar in parallel, so
character suppression via ListenChar(2) works.

Minus possible bugs, the M-File part should be good to go.
IOPort: Rebuild for MS-Windows, 32-Bit/64-Bit Matlab.

To incorporate async background reader thread fixes from a few
commits ago.
GetChar et al.: Add quirk handling for Octave on OSX.

Needs the KbQueueCreate->Release->Create quirk to work on Octave on
OSX, just as when using KbQueueCreate directly.
PsychHID/OSX: Implement proper keycode -> CookedKey mapping.

This finally makes the event.CookedKey field of events retrieved from
KbQueues event buffers meaningful. Now keycodes are properly mapped to
Unicode/ASCII characters, for consumption by GetChar.m. The
implementation handles the ALT and SHIFT modifier keys properly,
ignores other modifiers. This enables our GetChar() fallback for Octave
and matlab -nojvm on OSX properly. However, 32-Bit Matlab in -nojvm
mode is not supported, as the minimum OS version for this is 10.5
Leopard, which is only required by 64-Bit PTB on OSX, so we have to
exclude the legacy 32-Bit variant.

PsychHID for 64-Bit Octave and Matlab on OSX rebuilt and tested.
PsychHID: Allow query of deviceIndex of default kbQueue keyboard.

PsychHID('Devices', -1); returns the deviceIndex of the keyboard device
that gets used as default keyboard device for kbQueues. Needed by new
GetChar() implementation based on KbQueues. Add detection code to OSX
version, which was so far missing.

Tested on OSX and Linux so far.
Screen('GetMouseHelper'): Improve low-level tty magic code on Unix.

On Linux and OSX, this code allows successfull suppression of keystroke
input to Octave or matlab -nojvm, ie., when running in a terminal
without Java based GUI.
This works with some low-level Unix layer tty magic. Basically it
disables character echo'ing on the controlling tty and detaches stdin
from the tty, reattaches it temporarily to /dev/zero for "no input".
This implements ListenChar(2). On ListenChar (<2), this is undone by
reattaching stdin to the controlling tty and restoring echo state of
the terminal. If character collection via tty is requested, still
canonical input processing and input buffering is disabled.

Character suppression is only available on Linux and OSX in combination
with the keyboard queue GetChar method. It won't work on MS-Windows +
matlab -nojvm as the tty magic is non-portable to Windows.

Character collection via tty+stdin is only available as a last-resort
fallback path on Linux if the default keyboards keyboard queue is
already in use by usercode. It never worked reliably on OSX or Windows.

Remaining problem: Character suppression does not get disabled on error
or return to Matlab/Octave command prompt or input, leaving a dead
keyboard behind, with the need to kill octave (Matlab kills itself on
return to input in this case, probably due to EOF read or stdin stream
error when reading from /dev/zero).

Tested on OSX and Linux with Octave and matlab -nojvm.
GetCharTest: Test timestamping as well at the end.

Works now on most setups, so test it.
GetChar et al.: Fix bugs and glitches in M-Files.

To make it actually work. Scheme for the whole thing:

1. On Octave, or matlab -nojvm: Use Keyboard queues for GetChar by
default. On Linux, fallback to tty+stdin method if queue occupied. On
Linux and OSX suppress characters via tty magic, on Windows (matlab
-nojvm) let it spill.

2. With Matlab in Java GUI mode: Use Java-GetChar on all systems for
character suppression. Use Java-GetChar on OSX and Linux and WindowsXP.
Use keyboard queue on Windows Vista and later, as Java is unreliable
there.

Use of the default keyboards keyboard queue and GetChar et al. in
kb-queue mode is mutually exclusive. Locking takes care of this. On OSX
there's only one kb-queue, so any use of kb-queues is mutex. with
Octave or matlab -nojvm + GetChar.

The best strategy is still to generally avoid GetChar and friends and
use Keyboard queues KbXXX etc. directly if possible.
Disable GetChar et al. on 32-Bit matlab -nojvm on OSX.

Due to lack of support of keycode mapping in 32-Bit PsychHID for OSX,
we can't support kbqueue based GetChar() in 32-Bit Matlab on OSX, so
-nojvm mode is no-go. Jave based GetChar continues to work.

Check for this combo and error() out if somebody tries.
Screen: Disable stdin+tty magic keystroke suppression on error/sca et al.

Disable tty keyboard suppression (if enabled) at
Screen('CloseAll')/error/clear etc. This will also revert to normal
mode if any other mex files detects an error, as they all call sca;
Same goes for try-catch-sca error handling.

Tested on OSX for now.