Merge pull request #43 from Psychtoolbox-3/master

Merge pull request #192 from kleinerm/master

Resync with "goto fail" public release.
Bump version number to 3.0.12, add detection code for supported OS releases.

Bump module version number and Psychtoolbox version and date.
A new function PsychSupported() returns a string which describes the
status of official support for given operating system release.
Screen(‘computer’) returns this as new subfield ‘supported’, as does
the startup info of Screen(). Linux is fully supported. OSX 10.9 is
fully supported. Windows-7 is fully supported, Windows 8.x is partially
supported, Windows Vista and XP are unsupported.

-> Screen for 64-Bit Octave on OSX rebuilt and tested.
Screen/OSX: Disable VBLIrq/CoreVideo timestamping fallback by default.

Use VBLTimestampingmode 0 by default for the 3.0.12+ series, instead of
mode 1.
This disables use of VBL-IRQ/Shmem fallback on OSX 10.6 Snow Leopard,
as we can’t test it for proper functioning anymore. Might still work
ok, but who knows?
This disables use of Apple’s broken CoreVideo/CVDisplayLink
timestamping on 10.7+. It was unreliable at best, but also causes
random crashes on some setups. This is not fixable by us and i’m sick
of seeing bug reports for it, so disable by default.

Also change recommendation messages to only recommend installation of
the PsychtoolboxKernelDriver for proper timestamping if we are not
running on a Intel GPU, where the kernel driver is disabled for
security reasons.

-> Screen for 64-Bit Octave on OSX rebuilt and tested with
PTKD/non-PTBKD, Nvidia vs. Intel.
-> help texts updated.
Screen/OSX: Improve switchback logic on window close.

Match against MATLAB and Octave. Works better on Octave and Matlab.

Screen for 64-Bit Octave and Matlab on OSX rebuilt and tested.
PsychGPUTestAndTweakGammaTables: Make more robust against buggy graphics drivers.

Move start y-pos of encoder test bar form 10 to 8, so 10-scanlines high
bar goes from -2 to 8. If a graphics driver (e.g., a buggy MS-Windows
driver) has a off-by-one or off-by-two y-pos bug, this should prevent
a black line on top of the screen and make this robust.

Also remove try-catch protection around Screen('LoadNormalizedGammaTable').
Was meant to protect against Windows gamma table upload failure but doesn't,
as Screen will close the window on such an error and code will continue to
run and spill out hundreds of misleading error messages.
ResolutionTest, NearestResolution: Handle multiple outputs per screen on Linux.
SetResolution: Make useable on Linux + single-output x-screen at least.

SetResolution can't handle multiple video outputs per screen
in a reasonable manner, as possible on Linux, where one x-screen
can have multiple outputs.

Make it distinguish 1 vs. multi-output setups and provide
proper behavior on single-output screens. On multi-output
screens on Linux, warn user about limited functionality and
do the best it can.
Screen/OSX: Match refresh rate more lenient for Screen('Resolution').

Our current Screen('Resolution(s)') API only operates with integral
values for refresh rate in Hz, but the underlying OSX functions since
our switch to the 10.6+ SDK return fractional double values. Take
this into account by matching values with a tolerance of up to 1 Hz.

Both Windows and Linux only operate at 1 Hz granularity for setting
nominal Hz, so probably doesn't make much sense to make our API
resolve fractional values.

-> Might fix the "fail to set 120 hz refresh rate" problem experienced
   when testing latest beta on OSX with a 120 Hz video projector.

-> Recompile and test on OSX pending.
Screen/OSX: Fix Screen('Computer') busfreq, cpufreq, usermem reporting.

sysctl() doesn’t report proper values for these properties but simply
makes shit up as 32 Bit values for “backwards compatibility” [quoting
Apple kernel docs]. WTF?!?
sysctlbyname() for the same properties otoh. reports proper values
inside 64-Bit integers. Apparently fixing both system calls going
forward was asked too much from the kernel engineers of the company
that pays insane amounts of attention to detail.

-> Fix this latest crap by Apple.
-> Screen for 64-Bit Octave and Matlab on OSX rebuilt and tested.
Enable Eyelink() support for 64-Bit Matlab on Windows.

Enable build support for 64-Bit Eyelink mex file for Matlab on Windows.
Use pre-release 64-Bit Eyelink SDK for Windows from SR-Research.
-> windowsmakeit64_twisty.m updated with build support.
-> Eyelink.mexw32 32-Bit rebuilt for testing.
-> Eyelink.mexw64 64-Bit for Matlab on Windows initial build.
-> Builds correctly. Don’t know if it really works due to lack of
Eyelink tracker.
Screen('Computer') Add some missing fields to Windows/Linux.

‘gstreamer’ and ‘supported’ support was missing.
Also remove some dead code.
Make all mex files reentrant - But only apply to test build of Screen for now.

Make it possible for a PTB mex file / module to call itself
recursively, e.g., Screen() as part of imaging pipeline processing
calling into M-Functions or the interpreter which themselves call
Screen(), e.g., to query some properties.

So far this was impossible because some of the state in
PsychScriptingGlue, mostly for communicating with the scripting
environment, was global state to the file, stored on the heap or bss,
not on the function call stack. A function calling itself recursively
would have overwritten its own scripting glue state from a lower
recursion level and caused bad data corruption and trouble.

Now we implement our own mini-stack for those few variables (nlhs,
nrhs, plhs, pros, etc.) which need to be global to the file and not
just local to mexFunction(), with our own stack pointer variable
‘recLevel’ to index. recLevel is incremented and checked during entry
to the main dispatch mexFunction, decremented during regular exit from
mexFunction at return to the environment, as well as during error exits
before mexErrorMsgTxt(). Debugging output can be enabled via
setenv(‘PSYCH_RECURSION_DEBUG’,’1’); before first invocation of a
module. The stack depths and thereby max recursion level is #define’d
as MAX_RECURSIONLEVEL to a maximum of 5. I can’t think of any situation
where we’d need more than 2 or maybe 3 levels, so this should be plenty.

Tested via Screen’s imaging pipeline, both for regular completion and
error cases, both with and without async flips. Seems to perform
correctly.

-> Screen for 64-Bit Octave and Matlab on OSX rebuilt and tested. Works
on Octave and Matlab.
-> This currently has no benefit for modules other than Screen(),
because only Screen() can possibly call itself via its imaging pipeline.
-> Currently none of PTB’s code makes use of this feature, but it would
have been beneficial a couple of times in the past to simplify code or
make it more robust.
Core: Rename PsychScriptingGlue.cc -> .c for pure C build.

Changing PsychScriptingGlue's suffix from .cc to .c will
treat it as a C language file instead of a C++ language
file and thereby compile it as C instead of C++.

In the past, over 5 years ago, we needed this file to be
compiled as C++ for Octave compatibility, but we don't
need this any longer. A C build will do just fine. A C
build also avoids occassional trouble with C++ compilers
and C++ header files. C++ build was a recurring source
of build trouble with new compiler/framework/octave versions.

-> Renamed file.
-> Updated all make files and cleaned them up a bit in the process.
-> Test rebuild many mex files for many platforms.
Octave/Linux: Fix build for Octave 3.8.1 on Linux.

mkoctfile was implemented since forever as a well working
bash shell script. Somebody got bored and didn't like a
well working solution, so decided to throw it away and
rewrite mkoctfile as a compiled C++ executable with
less functionality for Octave 3.8 - Yay! :(

mkoctfile thereby lost the ability of wildcard expansion
of filenames like Common/Base/*.c and now screws up.

Reimplement wildcard expansion inside our linuxmakeitoctave3.m
make script by providing our own private override implementation
of Octave's mex.m inside our build script. This mex() function
is identical to Octave's, except it uses glob() to expand
filename wildcards like *.c into a list of all glob'bed files.
Then it passes those to mkoctfile.

-> linuxmakeitoctave3.m fixed.

-> Test rebuild of mex files under Octave 3.8.1 + Linux successfull.

-> Net result: Building PTB on Octave 3.8+ under Linux works again :)
               Another 24 hours of my life lost for no good purpose,
               just because somebody was bored and decided to make
               my life exciting.
PsychTweak: Make GstDumpFilterGraph more robust.

Strip trailing fileseparator, if any, because otherwise
GStreamer apparently ignores the directory, so dumping
of playback won't work.
Screen/Linux: Refine nouveau-kms broken pageflip event workaround.

Use video refresh interval * 0.8 if refresh interval is known post
refresh calibration. Use 7 msecs as in the past if refresh interval
not yet known, ie., during calibration itself. This is more adaptive
to true refresh rate.

Also blacklist all kernels >= 3.13 for now. We know 3.13 and 3.14
are definitely broken on nouveau-kms, but we don't know yet when
the fix will land - 3.15? 3.16? Later? Better play it safe and
assume all future kernels are broken until we know in which kernel
release the bug was finally fixed.
Screen/Linux: Expose more info in Screen('Computer')

Kernel, Hardware, Hostname, ...

-> Closer to OSX output.
Screen: Allow display of audio output device for GStreamer movie playback.

At 'Verbosity' > 3, print out the audio device (audio sink) used for
audio output during movie playback. This to help problems like "no sound"
during movie playback, e.g., due to misrouting of sound to wrong output.

-> Screen for 64-Bit Octave on Linux rebuilt and tested.
Screen/GStreamer: Allow selection of audio-sink during movie playback.

Introduce a new optional parameter 'movieOptions' to Screen('OpenMovie',...);
This allows to pass in an option string with key=value pairs of additional
playback options.

The only currently supported option is 'AudioSink=<sinkspec>', where
<sinkspec> must be a gst-launch style description of an audio-sink
plugin and parameter, e.g., 'AudioSink=pulseaudiosink device=Foo'
would use the pulseaudiosink plugin for audio output during movie
playback, and ask for output to audio device 'Foo'. This allows
in theory to control audio output routing if a system has more than
one soundcard or more than one output per soundcard.

Screen verbosity level 4 now also reports which audio device was
actually used during playback, to help debug audio routing problems,
e.g., because audio is routed to the HDMI output of the graphics card,
instead of the speakers, and one just wonders why there isn't any sound?

In practice, at least on KDE + PulseAudio on Linux i wasn't able to
override the selected order of preferences for audio outputs on my
MacbookPro. If i set the preferred audio output to DisplayPort/HDMI in
the KDE sound setup control panel, but asked PTB to play out over regular
speakers, the system ignored my wishes. Audio routing was properly set
at start of playback to the PTB spec, but immediately after start of
playback, the PulseAudio server reverted the audio sink to HDMI, ie.
overriding my settings. Soo, this new feature may be of limited utility
at least on some setups :(

-> Screen.mex for 64-Bit Octave on Linux rebuilt and tested -
   with limited success.

-> Another rather unfunny insight is that delivery of GStreamer bus
   messages doesn't work if Octave-3.8.1 is used with its GUI, at
   least for the GStreamer 0.10.36 installation of Ubuntu 14.04 LTS.
   It works with Octave 3.8.1 in command line mode, and with Matlab
   R2012a in GUI mode though. So something fishy is going on here with
   Octave GUI.

   Without proper bus message delivery, error handling is impaired,
   e.g., doesn't report why opening a movie file failed. Also looped
   video playback at default settings doesnt'w work, because the
   required EOS messages aren't received from the bus. Only method 64
   works, as it doesn't need the bus.

-> Another bad day in the life of our hero :(
Screen: Silence various compiler warnings.

The compiler found one real bug in Screen('GetImage'), although
one that was likely benign and never triggered.

There were various false positives about use of uninitialized
variables, mostly due to PsychErrorExitMsg() not being recognized
as the equivalent of a return() statement. This is just too convoluted
for the compiler to prove. Added some dummy assignments to silence
this noise and similar stuff that the compiler can't know is right.