Psychtoolbox

PTB Beta update 3.0.17.11 "Hope to the hopeless", another tribute to Apples low quality operating systems.

General

- DrawFormattedText2(): Fix handling of UTF-8 unicode for Octave 6, contributed by Github user qx1147.
- Help text improvements - spelling fixes for some PsychMunsell color conversion routines - by Danny Garside.
- Some internal minor improvements.

macOS

- Fix FlushEvents() and ListenChar() and GetCharTest for use with Octave cli on OSX, similar to the fixes of CharAvail() and GetChar() from PTB 3.0.17.10.
- Improve diagnostics and add troubleshooting help of PsychHID for the latest Apple macOS 10.15 and 11 screwups. PsychHID now detects at startup if Apples broken security workflow blocks use of HID "Input Monitoring" - which makes PsychHID unusable. If so, it reports it to the user, provides troubleshooting guidance, and shuts down. A better error handling behavior than just random mysterious failure to enumerate input devices, failure to create KbQueues or to detect keyboard input in KbCheck et al. Unfortunately we can't auto-fix macOS brokeness, just hopefully give users a hand in navigating this byzantine labyrinth of broken UX, brought to you by Apple.

Windows

- Mex files for 64-Bit Octave rebuilt: Now we support/recommend Octave-6.2, although Octave 6.1 should continue to work.

Highlights: Experimental Vulkan/Metal display backend support for macOS (mostly a failed experiment though), Octave 6 fixes for macOS, AMD Vega DCE-12 support for Linux, and various smaller improvments and bug fixes.

General

- MeasureLuminancePrecision now works with all photometers supported by PTB, not only with ColorCal2. ColorCal2 is the default choice if no photometer type is specified.
- Octave 6.2 on Windows and macOS is now no longer warned against, as light testing suggests it works.
- Various minor fixes and improvements.
- Help text and documentation improvements.

Linux

- AMD Vega / DCE-12 low-level support for Linux, so now it is actually finally verified to be working, as tested with a Datapixx3 wrt. identity pixel passthrough and timestamping.
- Fixes to LoadIdentityClut AMD fallback path.
- Fixes to SetMouse in windowed mode (ie. non-fullscreen windows).
- Fixes to GraphicsDisplaySyncAcrossDualHeadsLinux() - added a bug in the last release.
- PsychLinuxConfiguration now also calls AssertOpenGL to allow builtin libdc1394 compatibility fixups for Ubuntu 20.10+ for Screen when installing matlab-psychtoolbox-3 from NeuroDebian.
- Some improvements ot the RaspberryPi build process.

macOS

- Basic, **highly experimental, highly deficient / unreliable / low performance, and therefore not supported in case of problems** Vulkan (== Metal) display backend support for macOS. This requires at least macOS 10.15.4 and installation of the 3rd party Khronos MoltenVK open-source Vulkan icd driver and Vulkan runtime. MoltenVK implements the Vulkan portability subset on top of the proprietary Apple macOS Metal graphics api. It allows to now also use our Vulkan display backend on macOS for the really desperate and masochistic. Effectively this is a Metal display backend, which was intended to be a replacement for cases where the standard OpenGL backend doesn't work well. As a by-product, it provides basic HDR support on macOS, on machines where this is supported - utilizing Metal EDR functionality to implement Apples peculiar opinion about HDR. The HDR support is **way more limited in performance, reliability, accuracy and flexibility** compared to Windows-10 and even more limited compared to Linux, but may be of some use for people desperately clinging to the iToys. Unfortunately, at least as testing on macOS 10.15.7 with both AMD and Intel graphics on a MacBookPro 2017 went, Apple Metal is even more broken and unreliable wrt. visual stimulus onset timing and timestamping than OpenGL! After spending over 160 hours of work, trying to beat this thing into submission, i conclude this to be mostly a failure, due to bugs in Apples proprietary Metal api, only fixable by Apple, with all workarounds on our side exhausted. But who knows, maybe it will work better on macOS 11? I can't test macOS 11 at the moment due to unrelated showstopper bugs in macOS 11 which would make installing macOS 11 on my test machine too high a risk of bricking the machine. This experimental Vulkan/Metal display backend work was [sponsored by Mathworks](https://www.mathworks.com/solutions/neuroscience.html).

- Fixes for Octave 6 on macOS 10.15, so the octave GUI no longer hangs infinitely at exit if Screen() was used in a session. The workaround we had to invent for severe Apple macOS 10.11 logger bugs, started to work against us at some point, causing problems instead of fixing them. Apparently either macOS was fixed at some point, or Octave got a workaround for Apple macOS bugs. Anyway, now it seems that Octave 6.2 when launched in ``octave --gui`` mode now works ok, at least as tested under macOS 10.15.7 Catalina final. We keep the workaround active for macOS 10.13 and earlier, as we don't know when it turned from helping into hurting.

- Fixes for GetChar / CharAvail on macOS, when used with Octave or Matlab in command line (non-gui) mode. ListenChar works with Octave in gui mode, and Matlab in gui and commandline mode, but is still a big troublemaker for Octave in commandline mode under macOS, so now running ``octave --gui`` is recommended as the only way for ``ListenChar`` to work.
- Octave mex files on macOS rebuilt against Octave 6.2 from HomeBrew.

Windows

- Robustness improvements by Diederick to GetGITPath and GetGITInfo for Windows.

A minor PTB beta update, mostly featuring small bug fixes, doc updates and refinements.

General:

- Add Denis Pelli's MeasureLuminancePrecision.m as baseline to PsychAlpha/ . The script is already useful as it is, and received quite a bit of cleanup by myself wrt. Denis original. However, currently it is needlessly restricted to use of the ColorCal-II, and needs more refinement. We add it to the PsychAlpha alpha-quality folder for the time being, so it can have some use while it gets refined over time.

- PsychtoolboxPostInstallRoutine(): Improve diagnostics slightly for textrenderer setup failures on MS-Windows or macOS.

- Many minor fixes to demos and tests for Matlab R2020b compatibility. Various cleanups. Also many old and obsolete tests and demos deleted, which don't have much use anymore in the year 2021. This cleanup and R2020b compatibiity work was [sponsored by Mathworks](https://www.mathworks.com/solutions/neuroscience.html).

macOS:

- Fix MacModelName() for macOS Catalina. By Denis Pelli and Darshan Thapa.
- DriftTexturePrecisionTest: Make compatible with macOS Retina displays.

Linux:

- Minor help text updates in SetResolution() and Screen('Resolution') wrt. multi-display setups.

A minor PTB beta update, mostly featuring small bug fixes, doc updates and refinements. And a new start screen.

General:

- PsychRTBox: Robustness fix during box open. Sometimes the first query for the box id data delivers partial trash for unknown reasons. If that's the case, requery.
- BasicSoundInputDemo: Add missing setup for unified KbName. Otherwise the ESCAPE key is not recognized for mapping on
Windows and we get error abort.
- Update our Welcome splash to Celia's latest and more eye-catching artwork.
- Replace range() with psychrange() in internal test and demo scripts. Will either call range() if available, or use a drop-in implementation itself. This so one does not need the Matlab statistics toolbox just for running some basic tests and demos.

Linux:

- KbCheck: Add workaround for missing ESCape key on touchbar MacBook Pro's without functioning touchbar. Map ~ key left to 1 key also to ESCAPE. Mostly for testing with Linux development kernels which do not yet have the Apple touchbar dkms drivers updated for use with them.
- XOrgConfCreator: Use of intel-ddx implies DRI3/Present from now on. This is needed, because the intel-ddx does not choose the modern iris OpenGL driver on modern Intel chips, but still old-school i965 classic DRI driver, which is a mismatch to the desktop GUI and other clients choosing iris in such a scenario. Switching DRI3 on will make this a non-issue. Or in other words: No login failure when enabling color depth 30 bit / 10 bpc color precision mode on modern Intel graphics chips of Gen 8 and later on modern Linux distributions.
- MultiTouchMinimalDemo / MultiTouchDemo: Add a small potential performance optimization.
- "help RaspberryPiSetup": Update to account for Raspbian bug fix.

Windows:

- Screen/Windows: Add new visual diagnostic for DWM compositor interference. If Screen('Preference', 'VisualDebugLevel', 6) is set and we run on Windows-8 or later, and a fullscreen window is opened - which shouldn't be subject to DWM composition - then create the onscreen window with DWM redirection surface disabled. This will cause any DWM composited windows client area to not display at all, but instead just show transparent. This is a clear visual indicator that a window is subject to unwanted DWM composition, iow. if the DWM is the root cause for visual timing and timestamping problems.

A minor PTB beta update, mostly featuring christmas work:

All systems:

- OffsetRect(): Allow single rect as both row and column vector, instead of only as row vector.

Linux:

- Add support for the RaspberryPi 4 and 400 on 32-Bit Raspbian/RaspberryPi OS: Also some setup instructions and feature descriptions in the new help file "help RaspberryPiSetup".
The new Pi is in quite good shape, only sound output with PsychPortAudio over HDMI video output does not currently work, but that can be worked around, via the builtin soundchip and headphone jack, or - in the case of the RaspberryPi 400 without headphone jack - by plugging an external USB soundcard. The RPi 4 sports faster processor and graphics, more RAM, dual-display output, well working Wifi, and substantially improved graphics support, e.g., for high precision floating point textures and framebuffers, advanced shaders, and hardware accelerated video playback for some formats like H264.

The most noteworthy improvements about "Dynamically High!" are that it contains initial support for "High Dynamic Range" displays for visual stimulation (HDR) on Linux and Windows-10, sponsored by [VESA](https://vesa.org) ([Read the press release by clicking this link)](https://vesa.org/featured-articles/vesa-funds-development-of-new-video-compression-test-tool-for-high-dynamic-range-displays/), and a new installer and updater for use with Matlab, [sponsored by Mathworks](https://www.mathworks.com/solutions/neuroscience.html), which should hopefully especially help the less fortunate - people who are forced to use Apple macOS. This is also the first release supported under our new business model, and the first release built and at least somewhat tested under macOS Catalina 10.15.7 final.

SP6 is a release with bug fixes, workarounds for Apples broken macOS Catalina operating system, and smaller incremental improvements. [See the previous release announcements for the 3.0.17 series for the major features.](https://github.com/Psychtoolbox-3/Psychtoolbox-3/releases/tag/3.0.17.4)

The most interesting improvement in SP6 is basic support for stereo HDR stimulation on dual HDR display monitor setups under Linux.

All systems

- Fixes and improvements to the Python support, contributed by Alex Forrence (GitHub users aforren1) - Thanks!
- DLL runtime libraries misplaced on Windows after package restructuring.
- NumPy now gets installed automatically in a suitable version, as it was added as dependency.

- More code cleanup and deletion of obsolete/long dead and unused code and functionality.

- All Octave mex files will now be stripped of the most verbose debug symbols. This drastically reduces the size of many Octave mex files, so this Psychtoolbox should shrink considerably in download size / disk space despite new functionality. Some other big binaries related to the no longer supported Ubuntu 14.04/16.04 LTS were deleted for further space savings.

- Quite many Docs and help text updates.

- Various minor improvements to HDR support on Linux and Windows:
- SimpleHDRDemo: Hide distracting mouse cursor.
- ImagingStereoMoviePlayer: Fix text drawing and add basic HDR stereo movie playback support.
- PerceptualVBLSynctest: Add another way to visually check for dual-display video refresh sync, e.g., for stereo setups.
- HDRViewer: Fix initial mouse cursor positioning on multi-display HDR setups.

- Performance enhancements to drawing of our startup Welcome Screen. The logo can now also be automatically scaled down when running on low-resolution displays.

Linux

- Make PsychHID on Linux robust against touchscreens that claim to be keyboards on the MS Surface Pro 6 tablet (ipts touchscreen!). GetKeyboardIndices() will no longer enumerate such touch screens as *dysfunctional* keyboards. PsychHID will reject similar weird devices in the future, even if they don't get filtered out by GetKeyboardIndices() iow. future proofing.

- Have special format handling for Video4Linux2 devices which provide video in MJPEG format.

- Fix rejection of AMD DCN-2 / Navi gpu family gpu's for low-level mmio access.

- Rebuilt the drawtext plugin for 32-Bit ARMv7l architecture, ie. the RaspberryPi, to add so far missing support for underlined text drawing.

- XOrgConfSelector: Recommand CTRL+ALT+F3 instead of CTRL+ALT+F1 in case of display server startup failure, as Ubuntu 20.04-LTS uses the VT1 (F1) for the login manager / lock screen, so VT3 (F3) is a better choice for a text console if troubleshooting is needed.

- XOrgConfCreator: Provide improved setup instructions for 10 bpc / depth 30 deep color support: Update to cover the fact that AMD Navi+, Raven Ridge+ and other 2018+ gpu's with DCN display engine are no longer supported by our low-level MMIO hacks for 10 bpc+ framebuffer precision, but instead the standard xorg.conf depth 30 setup should be used to the same effect with higher performance, just as on Intel and NVidia graphics cards. The low-level hacks could be implemented on more modern gpu's but there isn't any practical need or benefit for that anymore, at least not as of PTB 3.0.17.

- PsychVulkan now supports improved visual stimulus onset timing and timestamping via Vulkan driver native support on suitable drivers. This makes use of the VK_GOOGLE_DISPLAY_TIMING extension when available.

- PsychVulkan can now also optimally work with Intel graphics chips on Linux, as has been tested with a prototype Mesa branch for OpenGL+Vulkan interop. This is not yet available as part of standard Linux distributions, but when they are ready, we are ready! Vulkan is not yet supported in a usable way for us on MS-Windows.

- Add new experimental PsychImaging task for HDR: ``PsychImaging('AddTask', 'General', 'UseStaticHDRHack');`` enables use of a new hack that only works on Linux with classic X11 X-Display X-Server, not on Linux+Wayland and not on other operating systems. This allows dual-display stereo presentation of HDR-10 stimuli, ie. with stereomode 4 or 5 "Dual display stereo", also single-display or multi-display use of this mode, e.g., for frame-sequential stereo presentation of HDR stimuli, or "display wall" multi-HDR-monitor setups. Normally our HDR display support is currently restricted to one HDR monitor per onscreen window, no multi-monitor HDR stereo setups. This hacks makes this work in a limited fashion, as described in the PsychImaging help.
- A new SimpleHDRLinuxStereoDemo.m shows stereoscopic HDR stimulus display on a dual-HDR-monitor setup.
- ImagingStereoMoviePlayer shows stereoscopic HDR movie playback as a new optional playback mode.
- For performance benchmarking of HDR playback, the option to select this hack was also added to PlayMoviesDemo.

Windows

- Special case handling for Microsoft Surface tablet's builtin video cameras.

- Support new mfvideosrc "Multimedia Foundation" capture plugin.

- Minor video capture improvement: Use device monitors / device providers.

macOS

- SetupPsychtoolbox: Handle latest Apple macOS Catalina+ brain-damage. Apples Catalina trainwreck needs special treatment. If Psychtoolbox has been downloaded via a webbrowser as a zip file or tgz file and then extracted, then all binary executable files like .dylib's and .mexmaci64 mex files will have the com.apple.quarantine attribute set to prevent them from working in any meaningfully user fixable way - Thanks Apple! Use the xattr command to remove the quarantine flag.

- Delete memcpuCudaOpenGL for macOS. It's dead since Apple decided to drop support for NVidia gpu's - and thereby CUDA - from their "Most advanced operating system in the world".

- PsychtoolboxPostInstallRounte: Deal with another Apple macOS Catalina SDK screwup: Since we are now building Screen() for macOS against 10.15 Catalina with the Catalina SDK we hit a new bug in Apples low-quality software. Apparently when built against the Catalina SDK, but running on older macOS versions than Catalina, then OpenGL rendering into a hidden window (via Preference ‘WindowShieldingLevel’ -1) is broken and triggers GL_INVALID_FRAMEBUFFER_OPERATION_EXT errors. The same works perfectly fine - as expected and tested before release - on Catalina itself. This caused error abort in the fontconfig cache rebuilt code which opens a hidden onscreen window when run under < Catalina. The bug is known to happen at least on 10.14 Mojave, 10.13 High Sierra, and 10.12 Sierra, so probably going back through all older macOS versions. Work around it by suppressing OpenGL error checking during this OpenWindow sequence, as we do not actually need rendering to work here.
Work time spent to diagnose and workaround this bug which is again like almost all macOS issues fully Apples fault: 5 hours. Thanks Apple!

- Note in help GStreamer that movie playback and high quality text rendering on macOS now also needs GStreamer 1.18 at a minimum, 1.18.2 is recommended.

- Refine reporting of OS support status in Screen() startup and Screen('Computer'): Report everything before Catalina as untested and unsupported. Report everything beyond Catalina, ie. macOS 11+, as not yet tested or supported. As of now, i very rarely and infrequently spot-check stuff on my old 10.13.6 High Sierra system under some Matlab version. Given 10.13's end of life and age of that machine, this won't happen often anymore. Also testing Octave 6.1 on 10.13 is just too painful going forward, now that HomeBrew no longer provides Octave bottles for 10.13 and source build just takes way too long -- like a dozen hours!