Merge pull request #80 from Psychtoolbox-3/master

PTB BETA RELEASE "Death by a thousand paper cuts"

Release highlights:

Speak() command now supported on all operating systems, and made more flexible. Linux support by MK, MS-Windows support by Vishal Shah.

Improved correctness tests and wokarounds for graphics driver bugs on Intel gpus under Linux, but also improvements to general graphics driver sync tests. Some warning clutter removed.

Make Screen startup more artifact free on Intel gpus on Linux with triple-buffering enabled.

Make Linux Screen() compatible to apitrace utility.

Bugfixes and enhancements to Screen('Resolution') on Linux and Screen('Resolutions') on 64-Bit OSX.

Enhancements to the PsychPortAudio backed Snd() legacy sound command.

Some improvements to DKL color functions by David Brainard.
Merge pull request #83 from Psychtoolbox-3/master

BETA RELEASE "Dancersizing, Grey & Hopeless"

"Dancersizing, Grey & Hopeless" mostly fixes small bugs, improves small details and improves GetChar support on Windows Vista+, matlab -nojvm and octave.

* GetChar, CharAvail, FlushEvents and ListenChar now (ab)use keyboard queue functionality on setups where use of Java based GetChar et al. is ineffective or impossible: This should enable good support for Windows Vista/7/8, matlab in -nojvm mode, and GNU/Octave in CLI and GUI mode.

* Minor fixes and improvements to PsychPortAudio, Screen, IOPort, PsychGPUControl and M-Files.

* CRS OptiCal support by Andreas Widmann.
ResponsePixx: Fix crash if nrButtons != 5

Button queries took number of buttons into account, but setting the
state of the button lights didn't. It always assumed 5 buttons.
Screen: Allow forcing use of camerabin2 in GStreamer video capture.

Setting env variable PSYCH_FORCE_CAMERABIN2 to any value will do the
trick.
ReponsePix: Fix it for good this time.

Passing [] empty default arguments to 'Open' call caused malfunctions.
Improve parameter validation for all subfunctions.
Tested for 4 and 5 button mode with ResponsePixx.
Screen/GStreamer: Make most basic camerabin2 video capture function work.

Attaching a videosource to camerabin2 and detecting its caps
(resolution, fps) works. Videocapture with default video source
settings works.
Changing or validating capture parameters doesn't work.
Capture property change on camera doesn't work.
Videorecording is untested.

Screen for 64-Bit Octave on Linux rebuilt and passed most basic tests.
Screen/GStreamer: Allow basic video mode selection and validation with camerabin2

* Implement proper enumeration and parsing of camerabin2 video caps to
allow auto-selection of "optimal" video resolution, and validation of a
specific, user requested video resolution. Tested with live capture,
but not yet with videorecording. May need to query different caps for
that, or maybe not. Anyway, now we know the trick.

* Allow selection of video resolution and framerate for video capture
by setting a proper caps object on camerabin2, as these settings are
now longer set via properties or signals, but are all included in the
caps object, together with capture flags, color- and imageformat.

Screen for 64-Bit Octave on Linux rebuilt and tested with the Sony Eye
cam, with various resolutions, framerates and in manual or
auto-selected modes. Needs retesting with the old camerabin1 path to
make sure nothing got broken there.

Enumeration/Validation of supported framerates is still a mystery, so
while framerate selection works as expected, we currently can't offer a
diagnostic error message if an unsupported framerate is selected.
PsychHID: Minor optimization of PsychHID('Devices') on 64-Bit OSX.

PsychHID('Devices') is awfully slow on 64-Bit Octave/Matlab on OSX,
taking 1000x the time of 32-Bit Matlab on OSX! The reason is that
apparently the 64-Bit HID Utilities framework is awfully slow, compared
to the older HID utilities used with the 32-Bit OSX build.

This contains a minor optimization, performing bundle loading for the
XML device database only once at PsychHID load time, not at each
'Devices' invocation. However, the speedup is not measurable.

We know which Apple OSX HID utilities functions are slow, but can't do
without them, so we can't easily optimize the speed and have to live
with the fact that PsychHID('Devices') will stay slow on 64-Bit OSX.

Comparison for enumerating 7 HID devices:
32-Bit Matlab: 0.2 msecs.
64-Bit Octave: 140 msecs.
64-Bit Matlab: 210 msecs.

PsychHID for 64-Bit Octave/Matlab on OSX rebuilt & tested.
PsychHID: some whitespace fixes.
DaqAInScan: Reindent/Reformat to fix whitespace errors.

To make successive real merge of changes simpler to review.
DaqAInScan: Fix various M-Lint warnings.

Add labels to warning() statements to allow selective disable.
Improve error detection. Fix some other m-lint warnings.
DaqAInScan: Add HID device enumeration caching for speedup.

This takes enormous amount of time if uncached, so cache it!
DaqAInScan: Change interface detection for the USB 1208-FS.

The old method was making too unflexible assumptions about the order in
which interfaces get enumerated. This broke on OSX 10.6.8 again thanks
to Apple idiocy.

The method is still suboptimal. It matches secondary interfaces to
primary interface by serial number, but the serial number on these
devices consists of the string '*******' which is rather
non-discriminative! Matching by locationID might be better. Checking
for vendorID/productID match could also help somewhat...

Anyway, this version seems to work at least ok in the single device
case.
DaqAInScan: Fix dumb abort criterion in "continue" case.

Only calling ReceiveReports in a while loop while system time is lower
than start time + expected scan duration is dumb, as we don't know how
much time-delay will be between start of scan in DaqAInScanBegin and
continuation in DaqAInScanContinue, as nothing states the calls should
be executed back-to-back.

Now we just perform a single pass on each invocation and throw the
count/freq duration criterion out. This ain't perfect either, but given
the generally horribly fragile way this function was implemented, it
can't make it much worse.

This may or may not fix current problems with 64-Bit runtimes on OSX,
let's see...
PsychHID: Try to make locationId actually dependent on device location.

locationId of a PsychHID('Devices') enumerated device should be unique
to (the location of) a device. On Linux we encode busId + deviceId,
which will hopefully do the trick. Previously we also encoded the
interfaceId which is bad, because that means that different interfaces
of the same physical devices end up with different locationIds.

On Windows we try to create a sort of hash of the containerId of the
device, as parsed from the device path. These container Id's exist in
at least Windows-7 and later and are guaranteed to be unique for each
physical device, but identical across different functions of the same
physical device. While this is not strictly a location, it should do
the trick. Behaviour on earlier Windows OS'es is unclear, currently we
assign the memory pointer address of the device structure, so the value
is at least different for different devices -- better than nothing?

PsychHID for 64-Bit Matlab on Windows rebuilt for testing.
Screen: Build fix for GStreamer support on Windows.

Make the compiler happy.
DaqAInScan: transpose(InterfaceInds) to avoid failure later on.

for d=IndexRange - loop needs a row vector IndexRange instead of a
column vector, so make it so.
DaqAInScan: Try to find matching daq interfaces by product string instead of serialNumber

serialNumber is not discriminative on many DAQ devices because lazy
vendors don't actually give it a unique (or even remotely meaningful)
value. Go by product name string matching instead. This would break if
more than one DAQ box of the same kind would be connected, but then
this was the case with serialNumber as well, and the whole DaqAInScan
mess can't handle more than one DAQ box anyway.
PsychHID/Windows: Potential Windows-8 and locationId fixes.

Change call to DirectInput8Create() to use the mex files DLL module
handle instead of Matlab.exe's module handle by default, fallback to
app module handle on failure, improve error handling. Hope is that this
fixes PsychHID crashes on Windows-8, as it is one thing we did wrong,
although it worked on all previous systems. Other recommendations from
MSDN docu proved ineffective, e.g., there isn't a dinput8.h header file
to include, only dinput.h -- apparently a typo in MS docs. Also
providing a DIRECTINPUT_VERSION > 0x800 causes failure, so 0x800 seems
to be the highest supported version -- another thing where MSDN docu
contradicted itself, but apparently we choose the right interpretation.

Also try to compute locationId during HID device enumeration from the
"ContainerId" hash in the device path string. According to MS docu,
ContainerId should be different for differnt physical devices, but
identical for different sub-devices of a connected physical composite
device -- ie., it should be the unique physical device id we want for
locationId. However, testing on Windows-7 shows the same id for all
connected devices, ie., 2 separate USB keyboards and 2 separate mice
all share the same ContainerId. Nothing else in the devicepath string
proved useful for discriminating either. Apparently we're out of luck
with a meaningful locationId on Windows. One explanation could be that
the containerId is computed from the serialnumber of the device, and
all those devices didn't have a serialnumber. This is sad, as
locationId is unique and consistent for physical devices on Linux and
OSX and would have been a perfect discriminator for composite devices
when used with the DAQ toolbox.

PsychHID for 32/64-Bit Matlab on Windows rebuilt and tested.
Screen: Improve Windows-8 compatibility by improved DWM support.

Windows-8 does not allow to disable the DWM 3D desktop compositor
anymore, so our disable calls are ineffective/no-ops. Otoh the bugs in
the DWM's switching logic seem to have been fixed in current Windows-7
and Windows-8: The DWM disables itself for displays which only show a
fullscreen onscreen window, thereby not interfering with our onscreen
windows if they are fullscreen, decorationless, opaque and unoccluded
-- ie., the common case for stimulus presentation.

Try to take this into account:

* Tone down serious error messages if DWM can't be disabled into
informational debug messages on higher verbosity levels. No point
shouting fire if nothing can be done about it on Windows-8 and nothing
needs to be done in the common case.

* Make warning messages about DWM interference more context sensitive:
We can now detect if the DWM is effectively on or off (but not on which
display!): Only print serious warning messages if we can be pretty sure
it negatively affects our stimulus windows, ie., if the DWM is active
on either a single display setup, or if our onscreen window is not a
fullscreen window, as in both cases DWM interference is guaranteed to
affect us. Print more toned down notice messages if the DWM is active
on some display of a multi-display setup, but our window is fullscreen
and in all likelihood not subject to DWM composition, ie., only non-ptb
windows are affected.

* In the single display DWM active case, try to use global info from
DwmGetCompositionTimingInfo() to do timestamping for redirected
onscreen windows. DwmGetCompositionTimingInfo() can only provide global
info, not specific to our windows, as window specific queries seem to
be a) seriously broken in all shipping Windows versions and b) are
officially deprecated as of Windows-8 and will be completely removed in
Windows-9. Therefore we can only use the global information if we're on
a single display setup, where the global information is guaranteed to
be related to our windows. DirectX timestamping seems to deliver
reasonable results, but this still needs to be tested with measurement
equipment.

* The DWM adds (at least) 1 video frame extra delay when active for a
window, so if  a timed Screen('Flip') is requested on a composited
window, subtract 1 refresh duration from the flipwhen deadline
requested by usercode. This compensates for the 1 frame extra lag and
allows proper stimulus onset scheduling at least for cases where the
onset is > 1 refresh cycle in the future. There ain't nothing we can do
for the 1 flip per refresh case though.

* Try to tune the DWM for deterministic minimal jitter composition
timing by restricting the number of video buffers used to the allowable
minimum of 2. This trick is borrowed from the implementation in
Google's ANGLE framework, which is the foundation of WebGL support for
Firefox and Chrome on Windows.

* Delete lots of dead DWM related code from our earlier failed attempts
to coerce the DWM into reasonable behaviour. Not only didn't it work,
it is guaranteed to not work in the future, as relevant scheduling
calls like DwmPresentParameters() have been declared deprecated as of
Windows-8 -- they will be removed from Windows-9 and later.

-> Basic testing on Windows-7 shows reasonable behaviour wrt. warning
messages, swap scheduling, jitter and consistency of swap timestamps in
the composited case, while scheduling and timestamping for fullscreen
windows works perfectly with the old methods even if DWM is forced on,
due to the auto-unredirection of fullscreen windows. This is good.
However, reliability/precision of timestamps for composited windows on
single display setups remains to be tested. Just because they are
self-consistent doesn't mean they are correct. Testing is tbd.

Screen for 32-Bit and 64-Bit Matlab on Windows rebuilt and tested on
Windows-7.