Psychtoolbox 3.0.17 Beta update “Dynamically High!” was released at 2nd November 2020. As usual, the complete development history can be found in our GitHub repository. The release tag is “3.0.17.0”, with the full tree and commit logs under the URL:

https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/3.0.17.0

If you choose to use Psychtoolbox with Matlab then, at time of release, the most well tested Matlab versions on Linux are now R2014b and R2019a. The most well tested Matlab version on MS-Windows is R2019a, and on macOS R2020b. Other recent versions are expected to work as well, but not tested yet.

The most noteworthy improvements about “Dynamically High!” is that it contains initial support for “High Dynamic Range” displays for visual stimulation (HDR) on Linux and Windows-10, sponsored by VESA, and a new installer and updater for use with Matlab, sponsored by Mathworks, 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.

Stats:

A total of 374 commits have changed 451 files for this release, made with over 6 months of work, changing or adding over 93113 lines of code. This is a big one!

New features and improvements:

All operating systems:

• New meta-feature: Advertisement for the new “community membership with priority support” and other paid services. See PsychPaidSupportAndServices() and our new accompanying website psychtoolbox.net. Paid priority support by default applies to the most recent released PTB Beta, ie. this Psychtoolbox-3.0.17 release at time of writing, and the officially recommended and supported operating system and hardware configurations.

• DownloadPsychtoolbox(), UpdatePsychtoolbox() and PsychtoolboxVersion() on Matlab R2014b or later now use Matlab’s builtin Java-based SVNKit as “no-need-to-install” Subversion client. This should avoid the need to install a separate Subversion client. Especially macOS users should benefit from this, given that Apple both removed Subversion support from the latest macOS and XCode versions and additionally worked hard to sabotage the easy use of 3rd party clients. Thanks Apple! In case of trouble with the new method, DownloadPsychtoolbox() has a new optional ‘downloadmethod’ parameter, which can be set to -1 to request use of the old method based on a 3rd party Subversion client. An optional ‘downloadmethod’ of 1 requests the downloader to just download the raw unversioned Psychtoolbox folder, with all versioning control information stripped. This will prevent the use of UpdatePsychtoolbox() or PsychtoolboxVersion() after such an “export only” download, and you will lose the advantages brought by version control. The advantage is a smaller download and installation size of currently about 300 MB instead of over 600 MB. Choose your poison… This work was sponsored by Mathworks.

• ColorCal-II colorimeter integration into the standard CMCheckInit() / MeasXYZ() based color measurement routines. While the ColorCal-II was supported since years via the ColorCal() function, now it also works with the older and more exhaustive calibration routines, e.g., the ones which so far required PhotoResearch PR devices like PR-650/655/670/705. This is so far only tested on one monitor of dubious color reproduction quality, so viewer discretion is advised! Iow. Trust, but verify!

• New colorspace conversion helper routines: RGBToXYZMatrix(), XYZToRGBMatrix(), and ConvertRGBSourceToRGBTargetColorSpace() for converting RGB image matrices from one color gamut (set of primaries and white-point) to another. These are currently used for the HDR demos. They convert source RGB colorspace -> XYZ space -> target RGB colorspace, with the color spaces defined by their CIE 1931 XYZ chromaticity coordinates of red, green, blue primaries and white-point. Iow. Build a 3x3 CSC matrix and do the matrix by color vector multiply for all pixels.

• Basic OpenEXR image reading support for single-part RGB (.exr) images, by use of the open-source tinyexr library https://github.com/syoyo/tinyexr. Also returns some standard and extended OpenEXR image attributes, e.g., image color gamut and conversion factor from values to nits.

• Improved reading for RLE-RGBE “Radiance” image file (.hdr), with some parsing of some image attributes.

• HDR image reading routines are integrated for convenient use into the improved HDRRead() function.

• OpenGL 4.6 support in our “MOGL” Matlab/Octave OpenGL scripting interface. Ofc. only a subset of functions is supported, which is easily usable from a scripting language and allows for auto-generated interface code. Functions which require C memory pointer double indirections are not supported by default. Some might be supportable by manual writing of suitable wrapper code.

• New and improved PsychTests:
  • VBLSyncTest(), PerceptualVBLSyncTest(), FlipTimingWithRTBoxPhotoDiodeTest() and DatapixxGPUDitherPatternTest() now also support testing with the new Vulkan based display backend.
  • FlipTimingWithRTBoxPhotoDiodeTest() can now also test timing with framebuffer color precisions beyond standard 8 bpc, e.g., 10 bpc and 16 bit floating point.
  • The new VulkanInteropDebug() can help debugging Vulkan display driver bugs.
  • AudioFeedbackLatencyTest() received some makeover to try to fix some file corruption that was present for unknown reasons.
  • The new HDRTest() allows to test the basic luminance response curve and color gamut of HDR display monitors by use of supported colorimeters (tested with ColorCal-II) or manual data entry or external devices.

• Bug fixes, documentation updates, misc. improvements.

• Deprecation / Half removal of BrightSideDisplay support. More code is to be removed, but this is essentially already dysfunctional since the end of life of WindowsXP 32-Bit. Then BrightSide the company doesn’t exist since over 12 years and their products probably all died of old age, so we can let it rest in peace.

• GNU/Octave 6.1 seems to be very close to its first public release, but didn’t quite make it. As soon as Octave 6.1 is released, we will switch the Octave requirements for MS-Windows and macOS from Octave 5.2 to Octave-6.1. This will require all Octave users of Psychtoolbox 3.0.17 to upgrade their Octave installations after the corresponding PTB beta update. If you want to stick to Octave-5.1/5.2 be advised to stick to the old Psychtoolbox-3.0.16, which will be officially unsupported from now on going forward.

Linux and Windows-10 only:

• “High Dynamic Range” (HDR) display support on modern Linux distributions with modern AMD graphics cards, and on Windows-10 with modern AMD and NVidia graphics, when connected to suitable HDR monitors:
  • Most of my (= Mario Kleiner) development work for this big new feature was sponsored by the Video Electronics Standards Association (VESA) under contract with my employer the Medical Innovations Incubator GmbH (MII) in Tuebingen, germany. Big thanks to VESA for this support! If you need similar feature development for Psychtoolbox, please see our services at https://www.psychtoolbox.net.
  • More thanks go to the AMD Linux open-source Vulkan driver team, and AMD Linux display driver team, the MESA Linux Vulkan developers for help with integration of HDR related improvements into the Linux kernel and user-space libraries and helpful technical discussions, and also to some of the folks at the XDC 2020 Linux graphics developer conference for fruitful discussions about future improvements to our HDR and Vulkan support. Without Linux and open-source development, this project would have been almost impossible to finish.
  • See “help PsychHDR” for detailed infos.
  • The HDR-10 standard (BT-2100) with BT-2020 / ITU Rec. 2020 color space, 10 bit per color channel precision and SMPTE ST-2084 PQ “Perceptual Quantizer” EOTF is supported.
  • So far, Linux was successfully tested over both DisplayPort and HDMI video outputs with AMD graphics cards of the Polaris series (Radeon Pro 560 in a MacBookPro 2017, and a discrete Radeon RX-460 graphics, both with DCE-11.2 display engine) and Raven Ridge integrated processor graphics (AMD Ryzen 5 2400G, Raven Ridge IGP, Vega 11 graphics, DCN 1.0 display engine). All modern AMD cards of Polaris and later are expected to work, likely also cards of the earlier Volcanic Islands and Sea Islands gpu families.
  • So far, Windows-10 was successfully tested over both DisplayPort and HDMI video outputs with AMD Raven Ridge processor graphics. Also 3rd party testing of AMD RX-460, and AMD RX 5500 GPU card connected via DisplayPort. Windows-10 was also tested over both DisplayPort and HDMI video outputs with a NVidia GeForce GTX 1650 by myself, and 3rd party testing with GeForce GTX 1080 and GTX 2080.
  • The new HDRTest.m script allows basic testing of correct operation (luminance response curve / linearity, color gamut) with supported colorimeters.
  • The new demos SimpleHDRDemo.m and HDRViewer.m demonstrate basic use of HDR for HDR image display, and basic HDR 2D drawing. Also use of the new HDRRead() and color space conversion functions.
  • MinimalisticOpenGLDemo.m with the new ‘hdr’ parameter and the new HDRMinimalisticOpenGLDemo.m demonstrate HDR display of OpenGL rendered 3D content.
  • PlayMoviesDemo.m has been extended with an optional ‘hdr’ == 1 parameter to demonstrate playback of HDR-10 movies. GStreamer 1.18 is required for automated handling of HDR movies. GStreamer 1.16 will be able to playback HDR content with some manual help of the usercode, at least for PQ and HLG encoded content, as demonstrated in PlayMoviesDemo with the ‘hdr’ parameter set to 2. This allows 4k UHD HDR playback at reasonable framerates, also utilizing HDR static metadata type 1 information for mastering display properties and content light level properties.

• As a by-product of HDR support, movie playback can now playback non-HDR UHD 4k content or Wide color gamut content with improved performance as well if the optional ‘pixelformat’ parameter is set to 11. Pixelformat 11 is automatically seleced when HDR display mode is in use. This does not work on Apple macOS due to Apples deficient OpenGL implementation, or on old graphics cards. GLSL shading language version 1.3 is required as a minimum for optimized movie playback.

• As a by-product of HDR we have basic support of the Khronos Vulkan rendering api as a limited display backend on graphics cards and driver which support OpenGL-Vulkan interop. This is not used by default, but as an opt-in, as it does not yet provide real advantages in most standard dynamic range (SDR) stimulation scenarios. See “help PsychImaging” for the new task ‘UseVulkanDisplay’, as demonstrated in PerceptualVBLSyncTest, VBLSyncTest, FlipTimingWithRTBoxPhotoDiodeTest and AdditiveBlendingForLinearSuperpositionTutorial.
  • Single display visual stimulation is supported on AMD graphics cards and NVidia graphics cards under Linux and Windows-10 with up to date drivers.
  • Fullscreen mode with proper timing is currently somewhat unreliable and hit and miss on Linux with proprietary NVidia graphics, but highly reliable with AMD graphics cards. AMD graphics is strongly recommended!
  • Multi-Display setups can be used, but only one display can be selected and used at a time for a single onscreen window, ie. dual-display stereo onscreen windows do not work.
  • Opening multiple single-display onscreen windows may work, but is not always trouble-free or reliable.
  • Basic visual timing and timestamping works reliably on AMD graphics cards, but not on NVidia graphics cards. AMD graphics is strongly recommended!
  • Only stimulus onset via Screen(‘Flip’) is supported at this time. Async flips via Screen(‘AsyncFlipBegin’)…, frame-sequential stereo modes, and fine-grained timing via HDMI VRR, Displayport adaptive sync or AMD FreeSync are not yet supported. Only Linux with AMD graphics supports FreeSync/DP adaptive sync, and some more fragile and limited support is available for NVidia G-Sync under Linux.
• Use of the Vulkan display backend under Linux with AMD graphics cards of the Polaris gpu family or later models (Vega, AMD Ryzen processor graphics, Navi recommended, but Vega and Navi untested so far) and the AMD developed amdvlk open-source driver with Linux 5.8 or later does allow for a new high precision output mode: Floating point 16 bit output for about ~11.5 bits of precision per color channel on suitable graphics cards and displays. See AdditiveBlendingForLinearSuperpositionTutorial() for one script demonstrating this. This should be able to attain better than 10 bpc output precision on native 12 bpc displays (DisplayPort strongly recommended, HDMI discouraged!) and on 10 bpc displays or 8 bpc displays via use of gpu hardware spatial dithering. This is so far only lightly tested on one native 10 bpc capable HDR monitor, so viewer discretion is advised.

Linux only:

• GStreamer version 1.8 is now required at a minimum.

• Ubuntu 16.04 LTS - or for that matter really anything older than Ubuntu 18.04.5 LTS, is no longer officially supported. Light touch and go testing shows most stuff still works fine, except DrawFormattedText2() in some special cases like text rotation or certain text alignment on Octave 4.0. But no further testing will be performed, and we may make incompatible changes to the 3.0.17 series and later in the future. This should not be a big problem, as Ubuntu 16.04 LTS will reach its official end-of-life in less than six months.

• There is some minimal compatibility fix for the brand-new Ubuntu 20.10 (Groovy Gorilla) for dealing with the upgraded libdc1394.so.25 Firewire and USB-Vision video capture library for IIDC machine vision cameras.

• NOTE: Ubuntu 20.10 is not yet exhaustively tested for compatibility with Psychtoolbox 3.0.17, but may have some problems with sound output via PsychPortAudio(). Stay tuned…

Windows only:

• GStreamer version 1.18.0 64-Bit MSVC or later versions are now required on Windows. Screen() will no longer work with older versions of GStreamer! The current download link is this one: GStreamer 1.18 MSVC

• Windows 7, Windows 8, Windows 8.1, and Windows-10 versions older than the Window-10 November 2019 update (Release 1909) are not tested at all for this release. Upgrading to a 2020 release of Windows-10 is recommended, as future testing of PTB will happen on the latest recommended stable Windows-10 releases, e.g., May 2020 update (Release 2004) or later. While the expectation is that this release still works with Windows-7, this may change at any time for any reason without further warning in a future PTB beta release. Windows-7 has reached end-of-life already at the beginning of 2020, and Windows-8 even long before, so this should not pose any real problems.

macOS only:

• The macOS build system and only somewhat tested and officially supported platform is now macOS 10.15.7 Catalina final. Please note that this is not and endorsement of Catalina, the most awful macOS version ever imposed onto the world. I fully expect the upcoming macOS 11 “Big Sur” to be even worse for neuroscience testing and take the crown from Sierra, stay tuned! You should probably stick to your current system if it works reasonably well for you, because things are guaranteed to get worse when “upgrading” to Catalina. I unfortunatey did not have the choice of sticking to the better working macOS Mojave, because of lack of support for some API’s and features and forced deprecation of functionality by Apple, so here we are. At this point we only have one test machine for frequent testing with Catalina, using AMD graphics (MacBookPro 2017 15 inch), and one machine for very infrequent testing on Intel graphics (macMini 2012), and no other Apple test machines apart from an over 10 years old MacBookPro 2020 with slowly failing hardware and limited usability for testing under macOS 10.13.6 High Sierra.

• GStreamer version 1.8 is now required at a minimum. While GStreamer on macOS is still optional if you don’t need multi-media or video capture/recording functionality, our advanced plugin based text renderer likely will not work, at least not with Matlab (see “help DrawTextPlugin”), only the inferior and officially unsupported Apple CoreText renderer. GStreamer is now the recommended choice for getting our text renderer going, and additional workarounds have been added to deal with macOS being macOS when it comes to text rendering. Previously X11 was recommended, but given that Apple deprecated that technology this doesn’t seem to be the most convenient choice. Octave 5.2 should support our high quality renderer even in the absence of GStreamer though.

• Octave 5.2 from HomeBrew is the only supported GNU/Octave version at this point in time. Our DownloadPsychtoolbox() function will now try to preferentially use the Subversion command line client “svn” provided by HomeBrew for downloads and updates. In case of a missing or dysfunctional (e.g., intentionally sabotaged by Apple) svn client, it will offer to automatically install Subversion from HomeBrew. The same fallback mechanism is available by specifying an optional ‘downloadmethod’ of -1 in DownloadPsychtoolbox() if one tried to install/update on Matlab and the new SVNKit method would fail for some reason.

• We are deprecating libdc1394 Firewire video capture support, Microsoft Kinect support (PsychKinect()), and Oculus VR support (PsychOculusVR) on macOS. The functionality is still available but practically untested and unsupported in case of trouble. If we get aware of actual trouble with this functions, we will remove them for macOS, as the effort is not worth the gain anymore:

  • All Apple Macs since after 2012 do no longer have Firewire ports.
  • The Microsoft Kinect is no longer sold.
  • Oculus does not support any of their consumer VR HMD’s on macOS as they consider Apple hardware and operating systems unsuitable for serious VR application. So does Valve btw.
  • We will keep all this functionality supported indefinitely on Linux and as long as practical on MS-Windows.

Enjoy!

Psychtoolbox 3.0.16 Beta update “Crowning achievement” was released at 10th May 2020. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2020-05-10_V3.0.16”, with the full tree and commit logs under the URL:

https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/PTB_Beta-2020-05-10_V3.0.16

If you choose to use Psychtoolbox with Matlab then the most well tested Matlab versions on Linux are now R2014b and R2019a. The most well tested Matlab version on MS-Windows and macOS is now R2019a. For best results and support, use R2019a. R2019b and R2020a are expected to work as well, but not extensively tested yet.

The most noteworthy thing about “Crowning achievement” is that it contains the highest number of 3rd party contributions (7 if i counted right) ever! Various people contributed new functions and improvements to existing functions. This would be a good trend if it continues. Thanks!

New features and improvements:

All operating systems:

• Add disclaimer to “help PsychContributed” that all code in there is not considered up to the regular quality standards, often only supported by the 3rd party contributors not by us, subject to removal or backwards incompatible changes or breakage for any reason. If you use it, you are mostly on your own!

• Improve some help texts, e.g.,
  • Screen Rect? Screen GlobalRect? : Mention it also works on textures.
  • Help section on display mirroring in PsychImaging() improved to match what works/doesn’t on modern operating systems.

• sca(): No longer recenter the mouse cursor at the display center at invocation of sca(). This is a measure that was needed on old Linux distributions with some desktop environments, but not needed on modern Linux, Windows or macOS. It can trigger some weird crash bugs on some exotic Windows-10 multi-display setups. Problem reported by Diederick.

• Screen: Always print error messages wrt. sync test failure at OpenWindow time, even if level of verbosity is set to zero, to aid debugging the most common reason for OpenWindow failure on Apples trainwrecks and other low-quality systems.

• Add underlining support to Screen(‘DrawText’) (ie. honor the Screen(‘TextStyle’) setting flag 4 = underline) when using the modern standard drawtext plugin. So far underlining was only supported with some of the legacy OS specific text renderers. Now it works in the typical use case. Code for drawtext plugin contributed by Diederick (@dcnieho).

• MinExpEntStair(): Make it compatible with modern Octave versions 4.4 and later, contributed by Diederick.

• Fix ClockRandSeed() for compatibility with recent Matlab versions. Problem reported and solution suggested by Xiangrui Li (@xiangruili)

• MeasureDpi(): Now optionally allows DPI measurement using standard credit cards, as very common calibration objects of well defined size. Measuring with other objects is still possible, by specifying their size, as in the past. Some other minor improvements. Contributed by Miguel García García (@mikelgg93).

• New function HoritaTitler() to control the Horita SCT-50 video titler and compatible devices via serial port (https://horita.com). Contributed by Natasa Ganea from the Goldsmiths Infantlab, University of London.

• New procedural texture shader for sine-wave and square-wave gratings which don’t change brightness, but color between a neutral background color and two different colors at the peaks and valleys of the grating, e.g., red-green or blue-yellow gratings for research wrt. color opponent perception. Also with adjustable smoothness of the transition between the two colors for square-wave gratings, and with a radial aperture of controllable radius. CreateProceduralColorGrating() to create them, ProceduralColorGratingDemo.m to show how it is used. Contributed by Ian Andolina (@iandol).

Linux:

• Add support for Octave 4.4+ 64-Bit, to support the new 64-Bit Octave 5.2 in Ubuntu 20.04-LTS. Mostly by adding an Eyelink mex file built against Octave 5.2 and checking that our set of mex files built against Octave 4.4 for Ubuntu 19.10 still works with Octave 5.2 on Ubuntu 20.04-LTS.

• Improvements to XOrgConfCreator() for Ubuntu 20.04 LTS and modern AMD gpu’s:
  • Fix ddx video driver detection on recent AMD gpu’s with DCN display engine (Ryzen integrated graphics, AMD Navi gpu family of discrete gpu’s).
  • Allow to opt-out of use of modesetting-ddx, instead of only opt-in: The defaults have changed on Ubuntu 20.04 LTS. Modesetting is used by default on Intel and NVidia nouveau, instead of being an optional alternative compared to vendor specific intel-ddx and nouveau-ddx drivers.
  • Make it robust against use under 30 bit color depth for the X-Screen if something is botched in the color depth 30 bit setup. XOrgConfCreator() is part of the troubleshooting procedure, so there shouldn’t be a need to troubleshoot itself first in case of trouble.
• Reduce verbosity of gpu detection and low-level access setup machinery at default verbosity level.

Windows:

• ShowCursor(): Add support for more cursor shapes that are available on Windows by default. Contributed by Diederick.

• “help DrawTextPlugin”: Mention alternate locations for the fontconfig cache, and how to solve trouble there. Problem and solution reported by @sr-brian.

• PsychOculusVR1 driver: Allow printing of debug messages from secondary threads (VR runtime threads) again when running under Octave. As printing of debug messages from secondary threads crashes Matlab since around R2018, this was unconditionally disabled. Now we allow it again when running on Octave, so users could get more help in debugging mysterious problems iff they use Octave for debugging these problems.

macOS:

• Add MacDisplaySettings(), contributed by Denis Pelli (@denispelli) . This is a replacement for AutoBrightness(), which is now a wrapper around MacDisplaySettings() for backwards compatibility. MacDisplaySettings() provides more control over more display settings which get in the way of properly calibrated monitors, e.g., automatic backlight brightness, nightshift, etc. It is also supposed to be more robust and faster than the old code. NOTE: This function is part of the PsychContributed category of functions. As such it is unsupported and not tested at all (not even for security issues or unintended side effects) by the official maintainer. It could fail or break or be changed in a backwards incompatible way in the future for any reason. All support requests will have to go directly to Denis Pelli.

Enjoy!

Psychtoolbox 3.0.16 Beta update “Toiletpaperhamsteridiots” was released at 26th March 2020. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2020-03-26_V3.0.16”, with the full tree and commit logs under the URL:

https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/PTB_Beta-2020-03-26_V3.0.16

If you choose to use Psychtoolbox with Matlab then the most well tested Matlab versions on Linux are now R2014b and R2019a. The most well tested Matlab version on MS-Windows and macOS is now R2019a. For best results and support, use R2019a.

This release brings minor bug fixes and improvements.

New features and improvements:

All operating systems:

• PlayMoviesDemo: Add alpha-blending support for transparent movies.

• Improve help text for Screen Screens?

• PsychPortAudio: Fix start of capture ‘capturetime’ timestamps in certain exotic conditions.

Linux:

• Fix default audio input/capture device selection for certain exotic audio input devices which expose separate logical audio devices for playback vs. capture.

• Cut down on chatter if running on latest generations of AMD gpu’s with DCN display engine, e.g., AMD Ryzen integrated processor graphics (Raven Ridge / Picasso / Renoir / …) and AMD Navi family discrete graphics cards. These latest generation DCN display engines are not supported by our bag of low-level tricks, as there is neither need nor benefit. Spare the user from pointing this out with extra debug clutter.

• Fix detection code for VRR capable displays (HDMI VRR and DisplayPort Adaptive Sync / FreeSync). The detection code only probed the first connected display output, regardless into which output the display is plugged in, therefore falsely disabling VRR capable displays from using VRR.

macOS:

• Fix crash on Screen() reload if GStreamer isn’t installed, but libglib is installed by 3rd party, e.g., from HomeBrew.

• SetMouse: Deal better with Retina displays on macOS: At least if a window handle is provided, this should deal with position scaling on Retina displays if not using native Retina resolution on the trainwreck. Not great, but better than nothing.

Enjoy!