Psychtoolbox News

Psychtoolbox beta updated


Psychtoolbox 3.0.14 “Kalsarikännit” was released at 11th June 2017. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2017-06-11_V3.0.14”, with the full tree and commit logs under the URL:

This release mostly contains bug-fixes, small improvements and minor new features.

Btw. I’ve observed on some MS-Windows systems that UpdatePsychtoolbox - or more accurately the underlying svn Subversion command line tool - didn’t do anything. It claimed a successfull update, but didn’t update anything. This was also reported once in our Issue tracker. I don’t know if this is a Windows specific svn bug, or something more widespread. Anyway, if UpdatePsychtoolbox doesn’t upgrade/change about 60 files then something went wrong, and you’ll need to use DownloadPsychtoolbox for a completely fresh download. Let us know if this happens on other systems than Windows.

New features and improvements:

All operating systems:

  • Fix PsychImaging ‘EnableCLUTRemapping’ task. Did only work in scripts, not functions, due to a bug introduced in last beta. Also had off-by-one indexing errors for > 256 slot LUTs. CLUTMappingBugTest.m allows to test for proper functioning of this now, ie. verifies the bug-fix.

  • Fix use of Screen(‘PutImage’) when Psychimaging NormalizedHighRescolorRange task is used. PutImageTest.m verifies the bug fix.

  • Improve Screen(‘LoadNormalizedGammatable’) compatibility with functions that expect return values for loadOnNextFlip setting 2 – where those return arguments are meaningless, but return them anyway with faked values to simplify user scripts.

  • NetStation() go back to January 2017 version, as the version from the latest beta contains show-stopper bugs curtesy of myself and Justin Ales. This needs more work before a proper update to NTP synced synching is possible.

  • Remove all traces (and users) of the long dead SerialComm() serial port driver for 32-Bit Matlab on OSX. This wasn’t used by default by anything, and everything has higher quality IOPort based implementations.

  • Final fixes and prep work for the ready-for-release, but unreleased, new OculusVR1 driver for Oculus HMD’s which need the 1.x runtime.

  • Add compat code to the general VR handling routines like PsychVRHMD, and add some compat routines for functions freshly exposed on the Oculus-1 driver.

  • Pimp some VR related demos a bit.


  • Provide anti-aliased round dots on RaspberryPi via Screen(‘DrawDots’). Raspian can do this now with its current Mesa vc4 driver version.

  • Update “help SyncTrouble” and “help HybridGraphics”, as well as some flip warning messages, to reflect our current knowledge about this stuff on Linux.

  • Fix NVidia Optimus detection on Linux with the proprietary NVidia driver. Turns out our detection code only worked by chance on the NVidia 840M laptop by chance. Increasing hardware samples to n=2 with the Razer Blade 2016 showed it was broken. Now works (hopefully) on all such laptops.

  • XOrgConfCreator: Add automatic setup code for 30 bit native framebuffers (Intel, NVidia, amdgpu-pro), and setup for special 16 bpc framebuffer experimental code on Linux + AMD Sea Islands gpus.


  • Make ColorCal2() driver work on Windows by use of virtual COM port, by a dedicated code path.

Psychtoolbox beta updated


Psychtoolbox 3.0.14 “Spooling up the spinner!” was released at 12th May 2017. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2017-05-12_V3.0.14”, with the full tree and commit logs under the URL:

This release contains the accumulated work of 4 months, 200 separate improvements in 176 files, changing about 27000 lines of code. Major work was done under the hood for Linux improvements and prep work for VR HMD support improvements.

Btw. I’ve observed on some MS-Windows systems that UpdatePsychtoolbox - or more accurately the underlying svn Subversion command line tool - didn’t do anything. It claimed a successfull update, but didn’t update anything. This was also reported once in our Issue tracker. I don’t know if this is a Windows specific svn bug, or something more widespread. Anyway, if UpdatePsychtoolbox doesn’t upgrade about 176 files then something went wrong, and you’ll need to use DownloadPsychtoolbox for a completely fresh download. Let us know if this happens on other systems than Windows.

New features and improvements:

All operating systems:

  • New function Screen(‘ConstrainCursor’); for Linux/X11 and MS-Windows: Allows to constrain cursor movements to subareas of an onscreen window. Not supportable on OSX due to lack of OS facilities.

  • DrawFormattedText: Optionally return per-word bounding boxes to define AOI’s, e.g., for text perception + eye tracking studies.

  • Brand-new DrawFormattedText2() function and DrawFormattedText2Demo by Diederick Niehorster. More flexible in its formatting and text transformation options than DrawFormattedText. This is considered beta quality for now, bugs may linger in this large new piece of code. I added the ability to return per-word bounding boxes, like in DrawFormattedText, but that code has the limitation that it doesn’t yet work with complex compound transforms.

  • VideoIPWebcamCaptureDemo: Add sample mode for screencasting. Setup code and example gst-launch lines for live screen-casting from Linux X11 (tested) or Windows (untested) to PTB’s videocapture, so random windows from the desktop can be live-displayed into a PTB fullscreen onscreen window.

  • Screen(‘GetImage’) can now automatically handle multi-sample anti-aliased drawbuffers without need for manual intermediate steps for readback of such buffers as MSAA resolved images.

  • PsychImaging ‘PseudoGray’ task can now also boost 10 bpc and 12 bpc framebuffers by up to 2.8 bits in grayscale precision in principle, although this is only very lightly and incompletely tested due to lack of suitable native 10/12 bpc display devices.

  • New PsychImaging ‘UseSubpixelDrive task to allow to drive special medical imaging high precision grayscale displays with high precision, e.g., the “Eizo RadiForce GS-521”.

  • New GetSecs subfunction [getSecsClock, wallClock, syncErrorSecs] = GetSecs(‘AllClocks’); returns not only regular GetSecs() timestamp as ‘getSecsClock’, but also a wall clock timestamp ‘wallClock’ in UTC world time. This ‘wallClock’ time can be OS synchronized to external time references, e.g., via NTP, to synchronize it with the clocks of other computers. Measures seconds since some reference point, 1.1.1970 00:00:00 UTC on Linux and OSX with microsecond resolution, seconds since 1.1.1601 00:00:00 UTC on MS-Windows with millisecond resolution. This may come in handy for interoperation with EGI Netstation EEG systems.

  • Some improvements to PsychColorCal routines by the Brainard lab.

  • Various fixes and small improvements.

  • Large amount of under the hood infrastructure prep work for supporting new VR HMD devices, but no support for new devices yet. Check for potential regressions if you use Psychtoolbox Oculus Rift DK1/DK2 support!


  • help PsychtoolboxKernelDriver: Update setup instructions / help text for OSX 10.11+.

  • Document 10/11 bpc framebuffer mode behaviour on OSX 10.11/10.12, improve setup code. Thanks to Denis Pelli and Hoermet Yiltiz for testing on their machines.

  • Some fixes for MacBookPro 2016’s brokeness.


  • Screen(): Disable the magic “@” master abort key.

  • Better support for compose/compound/dead keys handling for GetChar / KbEventGet by Diederick.

  • PsychRTBox: Fix box serial port probing for Octave on Windows. Although Xiangrui Li found an even better solution, which is not part of this update yet.

  • Fix Optical() brokeness due to compatibility bugs introduced by MS into Windows-7. Credit: Andreas Widmann.


  • Improved hybrid graphics laptop support: Detail work and improved setup documentation for hybrid graphics with the open-source drivers (Intel + AMD, Intel + NVidia), and verified that NVidia Optimus (Intel + NVidia) also works ok with NVidia proprietary drivers, as tested on Ubuntu 17.04 “Zesty Zappus”. Add extra setup instructions specifically for NVidia + Ubuntu 17.04. Tested on two separate Optimus laptops, a Lenovo Ideapad Z50-70, and a Razer Blade 2016 with GeForce Pascal.

  • Improved compatibility with amdgpu-pro hybrid graphics driver, for the very few cases where that driver is beneficial over the standard AMD open-source drivers, e.g., certain 144/165/240 Hz refresh rate displays.

  • Improved 11 bpc / 16 bpc native framebuffer support for AMD gpu’s, and better setup instructions.

  • NVidia NVision 3d stereo emitter support for NVidia stereo goggles on regular consumer class GeForce gpu’s, AMD gpu’s and Intel gpu’s should now work with more emitter models, especially - as tested - with some NVision-2 emitters, whereas before only original NVision-1 emitters worked.

  • GetMouseWheel() now also works on Linux.

  • Improve GetMouse() coordinate handling on multi-x-screen.

  • Make PR-670 photometer work out of the box on Linux by adding workarounds for that devices broken firmware. Note: PR-670 remains broken on OSX 10.11, but seems to work on OSX 10.12.

  • Improve default keyboard selection if exotic or broken keyboard like devices are connected.

  • Various improvements, bug fixes, too many to mention.

Psychtoolbox beta updated


Psychtoolbox 3.0.14 “Standby FTL!” SP1 was released at 3rd January 2017. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2017-01-03_V3.0.14”, with the full tree and commit logs under the URL:

This is the initial v3.0.14 release. It drops all support for MacOSX 10.10 Yosemite. Psychtoolbox will not work at all anymore on OSX 10.10. Going forward only 10.11 El Capitan and 10.12 Sierra are expected to work, but only 10.12 Sierra is officially supported.

This release also cancels support for 64-Bit Octave 4.0 on OSX and Windows and introduces support for 64-Bit Octave 4.2.0 on OSX and Windows.

New features and improvements:

All operating systems:

  • Various help text updates, some refinements to some demos.


  • Terminate support for OSX 10.10 “Yosemite”. Psychtoolbox will no longer work at all with 10.10.
  • Without OSX 10.10 our own kernel driver based 10 bit framebuffers on AMD graphics cards won’t work anymore, as Apple sabotaged this functionality on 10.11 and later. Therefore remove our own 10 bpc support code.
  • Introduce support for OSX 10.11.4+ native 10 bit framebuffers on supported Apple hardware. This is untested due to lack of suitable hardware, but Apple docs claim it should work “under some conditions” on the 2013 MacPro with “suitable displays” and on the late 2014 and late 2015 iMac 27 inch Retina 5k models.
  • OSX 10.12 “Sierra” is now the only officially supported and lightly tested Apple OS, although PTB should continue to work on 10.11.
  • Implement a workaround for the MacBook”Pro” 2016 touchbar brain-damage. This will probably make KbCheck and KbQueues work again, but while the problem has been diagnosed, the fix is so far untested.
  • Some new workarounds for OSX sync failures on some iMac Retina 5k models, likely only minimally effective.
  • Terminate support for 64-Bit Octave 4.0.
  • Introduce support for 64-Bit Octave 4.2. Octave 4.2 is currently available via the HomeBrew and MacPorts package managers. Psychtoolbox has been only tested with Octave-4.0.0 from HomeBrew. You need to install/compile Octave from source if you want functional audioread/audiowrite functions for reading and writing wav audio files, e.g., via

    brew install -s octave –with-docs –with-java –with-sndfile



  • Some compatibility fixes to XOrgConfCreator on Linux + Matlab + NVidia by Ian Andolina.

Psychtoolbox beta updated


Psychtoolbox 3.0.13 “Jump Prep!” was released at 6th December 2016. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-12-06_V3.0.13”, with the full tree and commit logs under the URL:


New features and improvements:

All operating systems:

  • Download/Setup/UpdatePsychtoolbox: Be more lenient on unsupported platforms, to allow downloading of old PTB versions.
  • Fix compatibility of MOGL low-level OpenGL for Matlab support with Matlab R2015b and later versions.
  • MOGL: Fix glClearNamedFramebufferfi().
  • Improvements to DaqAInScan(), some by user jsdpag. New option options.nodiscard. Robustness improvements if multiple DAQ’s are connected. Fixes for Matlab’s brokeness since R2013b.
  • Improvements to ple and PsychEyelinkDispatchCallback by iandol.
  • Fix getting Psychtoolbox root folder in scripts with nested functions, by zacklb.
  • NetStation: Fixed bug for less than 4 arguments for an event and improved argument handling for events. By Justin Ales.
  • VBLSyncTest: Only abort via ESC key, truncate plots/analysis on short (aborted by ESC) runs.
  • Fixes to text rendering plugin for textHeight return argument of Screen(‘TextBounds’) by Diederick.
  • Misc other fixes and lots of low level compatibility/maintenance work, e.g. upgrade of Screen() and moglcore() to GLEW-2.0, which is now the minimum required GLEW version.


  • Screen: New workarounds for the deficient Apple OS, to avoid some crashes of Matlab/Octave after a ‘clear all’ and then running a PTB script using Screen() again.
  • PsychtoolboxKernelDriver: Add support for AMD Polaris and Nvidia Pascal gpu families. Support for OSX 10.12 “Sierra”.
  • LoadIdentityClut: Intel HD gfx needs type 2 lut on OSX. At least on current Intel HD chips.


  • Fix potential ‘deviceIndex’ breakage for KbCheck on Windows.
  • IOPort on Windows: Allow specification of COM port numbers > 9, e.g., COM10.


  • Linux: Disable loading of ‘lp’ parallel port line-printer module harder, to simplify use of parallel ports for digital i/o.
  • Various improvements related to use of hybrid graphics/switchable graphics/Enduro/Optimus Laptops under Linux.
  • Linux: Add docu, config files and modified modesetting ddx for some use of NVidia Optimus Laptops under Linux with the proprietary NVidia driver under X-Server 1.19. See “help HybridGraphics”.

Psychtoolbox beta updated


Psychtoolbox 3.0.13 “Boldly go where no one has gone before!” was released at 10th September 2016. As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-09-10_V3.0.13”, with the full tree and commit logs under the URL:


New features and improvements:

  • Initial hybrid graphics laptop support for Linux (prime renderoffload) “help HybridGraphics”. Describes setup to get the majority of hybrid graphics laptops to work between “useable” and “really well” under Linux.

  • PsychLinuxConfiguration: Automate setup of AMD deep color support, e.g., for DisplayPort deep color and HDMI deep color.

  • Some improvements to XOrgConfCreator.

  • Provide basic compatibility with the Windows-10 “Windows subsystem for Linux”. With a X-Server like XMing installed, allows to run some basic “PTB for Linux” functionality in Windows-10’s new Linux emulation layer. However, no sound, no PsychHID functionality/KeyboardQueus/DAQ, very bad timing, visual tearing artifacts. This more for geek cred than for any even remotely research grade use.

  • New demo VideoIPWebcamCaptureDemo.m - Capture streaming video from Android IPWebcam app.

  • GetGamePadIndices: Make as capable as GetKeyboardIndices.

  • CreateProceduralGabor: Add optional ‘validModulationRange’ parameter. Suggested by Taylor Hanayik.

  • DownloadLegacyPsychtoolbox: It’s dead, Jim! Download of legacy toolbox versions < 3.0.10 is currently broken.

  • SeparateAlphaTextureShader.vert.txt: Add additional (dx2,dy2) offsets. This allows for off-center rotation of sampled texture images. A usage example would be the one described in PTB forum message 20926. Shaders are created via MakeTextureDrawShader(‘SeparateAlphaChannel’), cfe. DriftDemo6.m

  • KbWait: reorganized and simplified input checking a bit. KbQueueFlush minor improvements. From Diederick.

  • KbQueueWait now gained forWhat and untilTime, like KbWait. From Diederick.

  • DrawFormattedText’s ‘flipVertical’ fixed for new text renderer. From Diederick.

  • PsychPortaudio: Give better error feedback if trying to open same device multiple times.

  • Daq: Update help texts wrt. USB 1024-LS. Now verified to work well.

  • Minor other stuff here and there.

Psychtoolbox-3.0.13 released


Psychtoolbox 3.0.13 “Set condition 1!” has been released. This is the first release of the 3.0.13 series.

3.0.13 no longer supports:

  • 32-Bit Octave-4 for MS-Windows.
  • 64-Bit Octave-3.8 for OSX.
  • Mac OSX 10.8 “Mountain Lion” and OSX 10.9 “Mavericks”.

It only works on:

  • 64-Bit Octave-4 for Linux, Windows and OSX. 64-Bit Octave 3.8 on Linux.

  • 64-Bit Matlab on all operating systems, R2012a or later is recommended, earlier versions may or may not continue to work, but are no longer tested or supported in case of trouble.

  • OSX 10.10 Yosemite and OSX 10.11 El Crapitan. Only El Crapitan is tested and somewhat supported in case of trouble.

  • On Linux we no longer provide mex files for 32-Bit Octave for Intel machines for direct download from us. However, NeuroDebian / Debian upstream / Ubuntu upstream will continue to provide these mex files in a convenient fashion in their “app-stores”, so this is not really a drawback, just something to be aware of.

  • I will probably allow inclusion of M-Files into future betas which may use object oriented programming (aka classdef) if those files have been shown to work flawlessly on Octave-4 and don’t touch widely used core functionality. Octave-4 has limited support for classdef programming, so not all object oriented code will work. We continue to support Octave-3.8 during the life-time of Ubuntu Linux 14.04-LTS, and Octave-3 does not support classdef programming, so such M-Files should be limited to functionality that isn’t essential to the use of PTB by the majority of users.

Users who wish to stick to Psychtoolbox 3.0.12 because they want to continue use of a future unsupported platform can redownload Psychtoolbox via:

DownloadPsychtoolbox([targetdirectory], ‘Psychtoolbox-3.0.12’);

Obviously keep backup copies before deleting/redownloading. Alternatively simply refrain from ever executing UpdatePsychtoolbox again.

New features and improvements:

  • New function UniqueCell and improvements to SortCell by Diederick Niehorster.

  • Some bug fixes to XOrgConfCreator by zacklb.

  • Some improvements to color functions by David Brainard.

  • Improved RaspberryPi support. Psychtoolbox is pretty ready for the Pi! New mex file RPiGPIOMex to control the Pi’s GPIO pins and a demo RaspberryPiGPIODemo to demonstrate basic GPIO control of the 2 status LED’s on the RPi 2B.

  • Improvements and bug fixes to validation code for high precision display devices like VPixx Datapixx/Viewpixx/Propixx and the Cambridge Research Systems Bits+ and Bits#.

  • Various bug fixes and minor improvements in 313 files.


Psychtoolbox user survey 2016


As of 6th July we got 356 responses in 22 days - Good, but we need more! Keep them coming!!

We are currently conducting a user survey for Psychtoolbox. Please participate, the sooner the better! We need one person per lab to respond, ideally one with sufficient insight into the operation of the lab, the labs needs, and the labs ability to contribute funding to PTB. In other words, the PI of the lab, or maybe a lab manager might be best suitable to fill out the survey.

The outcome of this survey may help to secure some short-term, time-limited bridge funding for Psychtoolbox development, maintenance and support. It will also influence decisions on how to fund future development, as well as priorities in development wrt. supporting new functionality or hardware.

The survey has a mandatory part of six questions, important for funding decisions and PTB’s future, and an optional longer part of optional questions, mostly to determine how you use PTB, what your needs and wishes are, what hardware/software you use.

Click on this link to the survey form if you want to participate



Psychtoolbox-3.0.12 final released


Psychtoolbox 3.0.12 final has been branched. This is the final release of 3.0.12. I may or may not backport trivial fixes in M-Files for serious bugs to it for a while, but you can mostly consider it done and unsupported from now on.

3.0.12 was the last version to support:

  • 32-Bit Octave-4 for MS-Windows.
  • 64-Bit Octave-3.8 for OSX.

  • Mac OSX 10.8 “Mountain Lion” and OSX 10.9 “Mavericks”.

Future beta releases will only support/work on:

  • 64-Bit Octave-4 for Windows and OSX.

  • 64-Bit Matlab on all operating systems, R2012a or later is recommended, earlier versions may or may not continue to work, but are no longer tested or supported in case of trouble.

  • OSX 10.10 Yosemite and 10.11 El Crapitan. Only El Crapitan is tested and somewhat supported in case of trouble.

  • On Linux i will no longer provide mex files for 32-Bit Octave for Intel machines for direct download from us. However, NeuroDebian / Debian upstream / Ubuntu upstream will continue to provide these mex files in a convenient fashion in their “app-stores”, so this is not really a drawback, just something to be aware of.

  • I will probably allow inclusion of M-Files into future betas which may use object oriented programming (aka classdef) if those files have been shown to work flawlessly on Octave-4 and don’t touch widely used core functionality. Octave-4 has limited support for classdef programming, so not all object oriented code will work. We continue to support Octave-3.8 during the life-time of Ubuntu Linux 14.04-LTS, and Octave-3 does not support classdef programming, so such M-Files should be limited to functionality that isn’t essential to the use of PTB by the majority of users.

Users who wish to stick to Psychtoolbox 3.0.12 because they want to continue use of a future unsupported platform can redownload Psychtoolbox via:

DownloadPsychtoolbox([targetdirectory], ‘Psychtoolbox-3.0.12’);

Obviously keep backup copies before deleting/redownloading. Alternatively simply refrain from ever executing UpdatePsychtoolbox again.


PTB BETA "Bring in the cat! (+SP5)" released


The new BETA “Bring in the cat!” and its Service Pack 2-5 update was released at 14th May 2016.

As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-05-14_V3.0.12”, with the full tree and commit logs under the URL:


New features:

  • TurnTableDemo: Fix for compatibility with Matlab R2015b and later.
  • BitsPlusPlus: Add new subfunction ‘UseFE1StereoGoggles’ to automatically drive those CRS goggles.
  • BitsStereoDemo: Make use of modern PTB features like UseFE1StereoGoggles.
  • Some file permission cleanups by Yaroslav.
  • Fixed some typo in ComputeCIEConeFundamentals() help text by git user spitschan.
  • Screen(‘DrawTextures’) speed improvements, only for 64-Bit Screen for Matlab and Octave on Linux for now.
  • Screen, PsychHID for RaspberryPi updated.
  • XOrgConfCreator now can also setup xf86-video-modesetting, the generic video driver for Linux.
  • PsychGPUControl now can deal with Compiz single-x-screen multi-display setups for Ubuntu’s standard “Unity” GUI.
  • rpath fixes for mex files on Octave-3/4 for 64-Bit OSX to make PTB for Octave on OSX work with different Octave versions.
  • VC4 DRI3/Present Mesa 11.2 workaround for Screen() on RaspberryPi.
  • Allow normal users PTB low-level access to modern AMD gpu’s, e.g., the R9 380 Tahiti Pro.
  • Additional performance improvements to Screen(‘AsyncFlipBegin/End/…’) - So far only for 64-Bit Linux.
  • Performance improvements to PsychProPixx.
  • KDE-5 multi-x-screen “pointer gets stuck” workaround for KDE-5 Plasma on KUbuntu 16.04.0-LTS.
  • Minor fixes and improvements to various M-Files.

PTB BETA "Bring in the cat! (+SP1)" released


The new BETA “Bring in the cat!” and its Service Pack 1 update was released at 14th April 2016.

As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-04-14_V3.0.12”, with the full tree and commit logs under the URL:


New features:

  • Add (almost) complete support for 64-Bit Octave-4.0.1 on MS-Windows. (Datapixx does not work yet.)
  • Add good support for Griffin PowerMate USB on Linux, limited/deficient support for Windows and OSX.
  • DrawFormatttedText: Add new horizontal alignment option ‘centerblock’. Always use ‘yPositionIsBaseline’ for vertical text positioning for consistency.
  • New demo TurnTableDemo to show off PsychPowerMate() function and some PsychPortAudio live stream updates on Linux. Works not so great with PowerMate on OSX.
  • PR670 photometer code robustness improvements by David Brainard.
  • Maintenance work and small fixes and improvements here and there.

PTB BETA "Nothing but the rain SP1" released


The new BETA “Nothing but the rain” and its Service Pack 1 update was released at 15th March 2016.

As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-03-15_V3.0.12”, with the full tree and commit logs under the URL:



New experimental features:

  • Basic alpha-quality support for Psychtoolbox on the Raspberry Pi model 2B. This requires the brand-new experimental/alpha-quality open-source OpenGL graphics/display drivers written by Eric Anholt for the Pi’s VideoCore-4 gpu on Broadcom’s SoC. These drivers are now backported to the February 2016 update of Raspbian, the Debian GNU/Linux variant for Raspberry Pi. This is more of a sneak preview to work in progress than production quality for neuro-science applications atm. See for current driver status.

Text drawing improvements:

  • Screen(‘TextTransform’) allows application of a 2D affine transform only to drawn text strings. Currently supported on the standard FTGL drawtext text renderer with high performance and good quality, and on the unsupported/deprecated legacy Apple OSX Coretext text renderer at the cost of a drastic performance loss and almost completely useless Screen(‘TextBounds’) bounding box results. Screen TextTransform? explains some of the gotchas and traps you will run into if you really think you want to use this function.

  • Screen(‘DrawText’) now returns more accurate/useful new text cursor position and a new optional ‘textHeight’ for “newline” vertical spacing. These enhancements only with the standard FTGL drawtext plugin renderer, not on the legacy renderers.

  • Support for sub-pixel anti-aliasing (“LCD filtering”) on the legacy Apple CoreText renderer 0, if that renderer is manually selected, and ‘TextAntialiasing’ preference setting 2 is selected and preference ‘TextAlphaBlending’ is enabled via setting 1 and a solid opaque ‘TextBackgroundColor’ is selected. Sub-pixel anti-aliasing only works on OSX under those special conditions. In all other cases, only regular per-pixel anti-aliasing is used, as in the past.

  • Fix memory leak in legacy OSX CoreText renderer and other OSX text renderer bugs.

  • Other small text quality improvements.

  • “help DrawTextPlugin” Update for latest OSX + Matlab trouble.

Small improvements:

  • Replace ‘clear all’ in many demos with a more harmless clear; Probably also not great, but better than that other disaster. Also replace some calls to GetChar/CharAvail, as we don’t want to give too many bad examples.

  • Add option ListenChar(-1): This only disables spilling of typed characters into the Matlab/Octave command window (like ListenChar(2)) but without enabling keyboard listening (GetChar et al.). This allows to use character suppression in parallel to use of Keyboard queues.

  • Add replacements psychwavread/psychwavwrite for wavread/wavwrite which were removed in Matlab R2015b. Used in our audio demos to provide a less brain-dead approach to basic backward compatibility than Mathworks.

  • Robustness improvements and/or bug fixes and/or help text updates to AutoBrightness, GazeContingentDemo/BubbleDemo, HighColorPrecisionDrawingTest, MeasureDpi, Kbqueues, BitsPlusIdentityClutTest, KbCheck, Screen(‘CopyWindow’), OSX legacy CoreText renderer, FrameSequentialStereoTest, GetEchoString, GetKbChar, DrawFormattedText, PsychHIDTest…

  • Windows: Allow Screen(‘LoadNormalizedgammatable’) to load > 256 slots gamma tables to devices like CRS Bits# or VPixx Datapixx. GPU hw gamma tables are still limited to 256 slots due to OS restrictions.

  • GetEchoString and AutoBrightness: Cosmetic and help text fixes.

  • XOrgConfCreator: Slightly more robust error handling against broken graphics setups.

  • Screen(‘DrawDots’): Make shader-based path more friendly to gpu drivers.

  • Add udev rule for potentially simplified use of Griffin Powermate on Linux.

  • Some improvements by the Brainard lab to PsychColorimetric utility routines.

  • Other small improvements here and there.

PTB BETA "Into Darkness" released


The new BETA “Into Darkness” was released at 25th January 2016.

As usual, the complete development history can be found in our GitHub repository. The release tag is “PTB_Beta-2016-01-25_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:

  • FTGL Drawtext plugin support for MS-Windows. Used as default textrenderer 1 on Windows, with fallback to the GDI legacy renderer if it is unsupported. Requires use of Octave-4 on Windows, or in case of Matlab on Windows that GStreamer is installed. We now have a consistent high quality text renderer on all platforms. This should also fix HiDPI display issues with text rendering on Windows, give much better anti-aliased text quality, and better text positioning. On GitHub issues: Fixes #282 Fixes #254

  • The default text renderer 1 is now always the (originally Linux only) FTGL renderer. Screen(‘Preference’,’TextRenderer’, 0) allows to select the OS specific legacy renderer (GDI on Windows, Apple CoreText on OSX). The legacy renderer is also used as fallback if the FTGL plugin fails for some reason. Note that use of the legacy renderer is from now on completely unsupported by us if you should run into any problems with it. It is on “life support” and may be removed completely in a future version of Psychtoolbox.

  • Use same font (“Arial” or something close to it), text size (24 pixels), style (normal) by default on all operating systems instead of OS specific settings, now that we use the same text renderer by default on all OSes, so one size should fit all.

  • Screen(‘DrawDots/DrawLines’): Add size limit queries and lenient flag. These functions now optionally return the min/max size of normal or anti-aliased dots and lines for the given graphics card/driver, as those differ across gpu’s, drivers and operating systems.

  • Minor other improvements.

Bug fixes:

  • Fix fast offscreen window support on use of PsychImaging ‘UseRetinaDisplay’. Was accidentally falling back to the old more limited legacy implementation if Retina support was requested.
  • Screen(‘GetImage’) - Make sure ‘rect’ is inside the source window.
  • Textbounds() - Accept optional ‘yPositionIsBaseline’ flag and make more robust. Contributed by Denis Pelli.
  • OffsetRect: Resolve ambiguity for 4x4 ‘oldrect’ matrix. Contributed by GitHub user mscain.
  • Snd(): Make more robust against failing InitializePsychSound().

PTB BETA "Puking Rainbow Unicorn SP1" released


The new BETA “Puking Rainbow Unicorn SP1” was released at 7th December 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-12-07_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:

  • Fix AMD GPU DCE-8+ display engine handling on Linux and OSX. Latest generation AMD gaphics cards are now fully supported.
  • Fix OSX PsychtoolboxKernelDriver multi-display handling bugs introduced by the “Puking Rainbow Unicorn” beta.
  • Improve 10 bpc pixelformat selection for OSX for native 10 bit framebuffer support. Untested due to lack of iMac 5k hardware.
  • Minor bug fixes and documentation updates in various places.
  • OSX: Maybe improve detection and handling of USB-DAQ devices. PsychHID for OSX may now support USB device selection by HID interfaceID, which might improve robustness of USB-DAQ detection and DaqAInScan functionality. Completely untested due to lack of hardware.
  • Windows: Improve visual stimulus timing on Windows-10, and maybe on Windows 8/8.1 (untested). On a Windows-10 test system with a 5 year old AMD Radeon HD-5770 this makes visual stimulation timing and timestamping work ok, despite the DWM being permanently enabled. More tests are needed, but this might allow at least basic use of Windows-10.

PTB BETA "Puking Rainbow Unicorn" released


The new BETA “Puking Rainbow Unicorn” was released at 5th November 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-11-05_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:

  • Introducing 32-Bit Octave-4 support for MS-Windows. Psychtoolbox should now work with 32-Bit Octave-4.0.0 as provided by the following official MXE Setup.exe installer provided by the Octave developers:

    Light testing shows that Psychtoolbox should work well with Octave-4 for Windows, except for video capture and video recording. Trying to use video capture will cause an immediate termination of Octave for currently unknown reasons. 32-Bit Octave-4 is only supported because the Octave upstream developers currently do not provide a 64-Bit build and installer for Octave. As soon as upstream would provide a 64-Bit Octave-4 installer, we would immediately switch to 64-Bit Octave support and cancel support for 32-Bit Octave, so do not rely on reintroduced 32-Bit support being around for too long on Windows.

  • 64-Bit Octave-4 suppport for Linux, as Ubuntu 15.10 and Debian testing now ship Octave-4. 32-Bit Octave-4 is not supported by us, but the NeuroDebian project will provide 32-Bit Octave-4 support soon for those few still using a 32-Bit system.

  • Experimental NVidia USB NVision emitter/stereo goggles support for 64-Bit Linux. This is untested due to lack of suitable hardware so far. It should allow to use any graphics card under Linux in frame sequential stereo mode with such NVidia stereo goggles, driven via the USB connection.

  • AMD Volcanic Islands gpu family low-level support for Linux and OSX. This covers the latest graphics cards from AMD.

  • Auto-detection of display head assignments for Linux and OSX on AMD gpus. Instead of using a heuristic, as for NVidia gpus, this should automatically find the correct setup for AMD gpus. A side effect of the auto- detection is a short flicker of all displays when the Screen mex file gets loaded on OSX or when the first onscreen window opens on Linux.

  • XOrgConfCreator + XOrgConfSelector assistants for Linux: XOrgConfCreator is a little setup assistant that automatically creates a xorg.conf display server configuration file by looking at the systems display setup and asking a few questions to the user. This should simplify setup of high performance multi-display setups on Linux. XOrgConfSelector allows to easily apply such config files on the given setup, switching between multiple different configs depending on experimental needs or regular desktop use.

  • PsychLinuxConfiguration improvements for Linux. New tweaks for performance tuning.

  • Screen(‘DrawDots’) shader based smooth point rendering support. On graphics drivers which don’t support drawing of smooth dots this will implement smooth dots via use of a GLSL shader. Use of shader based drawing of smooth dots can also be triggered via the new ‘dot_type’ flags 3 and 4. Using shader based dot drawing can be useful to enhance drawing performance on all gpu’s if one wants to draw lots of dots of variable size, as the GLSL shader based drawing code can draw dots of varying size faster than the standard code by use of some special shader features.

  • Improvements to Shuffle(), contributed by GitHub user NxNiki.

  • Add new kPsychGfxCapVCGood flag for ConserveVRAM settings to work around gpu texture sampling precision issues on some gpus with some graphics drivers, e.g., AMD gpus on OSX 10.11. You can use HighColorPrecisionDrawingTest with test blocks 3, 4 and 5 to test for these problems. The test will tell you to use this flag as one measure to improve precision if needed.

  • Add HiDPI detection code for MS-Windows, with hopefully useful troubleshooting messages. On Windows-7 and earlier Windows versions, Psychtoolbox can prevent timing issues caused by HiDPI/Retina high pixel density displays by disabling the DWM desktop compositor for fullscreen onscreen windows. On Windows-8 and later, PTB can’t prevent such issues, so it has to rely on the given Matlab or Octave host application being DPI aware, so MS-Windows does not need to enable DWM based DPI virtualization and rescaling. PTB can now detect problematic behaviour of Matlab and provide some hints on how to avoid DPI related trouble, but it can’t fix it, as that is not technically possible on MS-Windows.

  • PR655Init() tweaks for improved robustness on OSX.

  • Various bug fixes and minor improvements in various places.

PTB BETA "Immersator" SP2 released


The new BETA “Immersator” SP2 was released at 12th October 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-10-12_V3.0.12”, with the full tree and commit logs under the URL:

From now on, OSX versions before 10.11 El Capitan are no longer tested or officially supported. OSX 10.8 - 10.10 should continue to work, but no problems relating to these versions will be handled and no bugs will be fixed. Only OSX 10.11 El Capitan will receive basic testing, bug fixes and support.

New features and improvements:

  • Allow H264 profile selection for movie writing. Demo this in ImagingStereoDemo by choosing Profile=2, the “Main Profile”, something that even works with deficient movie players like Apples Quicktime.

  • Fixes for El Capitan, Apples latest goddamn awful “masterpiece”.

    • No longer completely hang and deadlock Octave-3/4 in GUI mode due to El Capitan bugs.
    • Avoid initial sync failure, caused by new El Capitan bugs, via some dirty hack.
    • Reduce frequency of white flashes when there shouldn’t be any, caused by El Capitan bugs. Dirty hack.
    • Make frozen/black screen hangs at end of a session slightly less frequent via a new hack.
    • Auto fallback from stereomode 1 to stereomode 11 on OSX if mode 1 is unsupported, as is the case on El Capitan, where Apple decided that their users do no longer need professional stereo display support.
    • Rebuilt all OSX mex files against XCode 7 and OSX 10.11 SDK’s.
    • Change support status on OSX: 10.11 El Capitan now supported, support for OSX 10.10 Yosemite cancelled.

PTB BETA "Immersator" (+SP1) released


The new BETA “Immersator” and its SP1 were released at 5th October 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-10-05_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:


  • General Virtual Reality HMD support infrastructure, with a driver specifically for the Oculus Rift DK1 and DK2.

    Look at “help OculusVR” and “help PsychVRHMD” for general setup and usage instructions.

    Look at the demos MovingLineDemo, VRHMDDemo, VRHMDDemo1, SuperShapeDemo, ImagingStereoDemo(103), MorphDemo on how to use this.

    The Horde3DForPsychtoolbox repository has been updated as well to provide support for such VR headsets when used with the Horde3D graphics engine in combination with Psychtoolbox. Support is available for 64-Bit Linux, OSX and Windows. Horde3D support for 32-Bit systems has been dropped. Find the repo, together with a demo named “HordeVRHMDDemo1” under the following link:

General improvements:

  • Support for use with 64-Bit Octave-4 on OSX via HomeBrew.
  • HighColorPrecisionDrawingTest: Robustness improvements to deal with the latest brokenness of OSX 10.11
  • Eyelink: Optionally prevent opening of existing EDF files to protect against accidental overwriting of data files.
  • LoadGLSLProgramFromFiles/LoadShader: Improve debugging output. Contributed by Diederick.
  • ImagingStereoDemo and others: Compatibility fixes for Matlab R2014a
  • KbQueueReserve: Check for invalid deviceIndex with more than one element.
  • GetMouseIndices: Add option ‘slavePointers’ for simpler use of KbQueues with mice on Linux.
  • Fixes and improvements to Quest by Denis Pelli.
  • Some small fixups for HomeBrew, and VRHMDDemo1.m

PTB BETA "Tediousness overdrive SP1/SP2" released


The new BETA “Tediousness overdrive” SP1 and SP2 were relased at 21st August 2015.

New features and improvements:

  • Datapixx on Octave OSX fixes.
  • PsychHID robustness improvements in HID device enumeration for OSX. Removes failure of PsychHID if special devices like, e.g., Oculus VR Rift, are connected.
  • AutoBrightness fix from Denis. Now probably works on both OSX 10.10 and 10.9.
  • QuestUpdate improvement from Denis: Make sure “intensity” is real, not complex.
  • DrawFormattedText: Fix bug for Unicode text introduced when improving single-line text centering.
  • Some fixes for text drawing provided or suggested by Diederick: – Screen: Fix returned alpha value in Text(Background)Color. – Screen(‘DrawText’): Remove the escaping of ampersand from DrawFormattedText()
  • Fix Var2Str: failed when infinity imaginary component in variable. Provided by Diederick.
  • Unit Tests: make use of capturing exception info in the catch instead of lasterr. By Diederick.
  • Fixes and improvements to color handling routines by David.
  • OSX mex file fixes for Octave: Drop Octave 3.8.1 support for OSX HomeBrew, add 3.8.2_2 support instead.
  • Some new tests and other minor improvements, e.g., to demos.
  • New test: DatapixxGPUDitherpatternTest - Test GPU dithering via Datapixx.

PTB BETA "Tediousness overdrive" released


The new BETA “Tediousness overdrive” was relased at 25th July 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-07-25_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:

  • KbWait: Fix treatment of empty forWhat argument.
  • Screen: Fix PTB-2 emulation mode a bit.
  • Screen/Linux: Dis/Enable DPMS while onscreen windows are open.
  • Screen/Linux: Detect use of DRI3/Present.
  • Screen/OSX: Fix color handling of OS X native text renderer.
  • Improve help text of GetGamepad/Keyboard/KeypadIndices
  • Add Screen(‘DrawText’) color precision test case to HighColorPrecisionDrawingTest.
  • DrawFormattedText: Improve bounding box precision for single-line case.
  • DaqAInScan: Make it potentially a bit faster for USB 1608-FS.
  • Screen/OSX: Remove hybrid graphics workaround for MBP 2010
  • DaqALoadQueue: More fixes for Octave compatibility and basic sanity.
  • Screen/Linux: Use old-style override_redirect on multi-x-screen KDE.
  • Screen/Linux/X11: Prevent crash at Screen reload on multi-x-screen with buggy Mesa.
  • Screen/Linux/X11: Restrict workaround for Mesa mapi bug to Mesa < 10.5.2
  • White-list Mesa versions >= 10.5.9 and >= 10.6.2 for XCloseDisplay()
  • NetStation: Improve and consolidate various improvements. - Gergely Csibra
  • Screen: Add new optional ‘ignoreErrors’ flag to ‘LoadNormalizedGammaTable’
  • Screen: Make FTGL plugin the default text renderer on OSX.
  • BasicSoundScheduleDemo: Remove redundant ‘RunMode’ 1 assignment.
  • Screen/OSX: Try to make modesetting Retina compatible.
  • VideoCaptureDemo, VideoDelayLoopMiniDemo: Use default ROI by default.
  • Snd(): Some fixes for corner use case.
  • PsychVideoDelayLoop: Cleanup textures at end of each session.
  • Update “help DrawTextPlugin” for new default FTGL renderer on OSX.
  • Screen: Improve Screen(‘Close’, window);
  • Screen/OSX: Fix cursor movement lag after SetMouse()
  • Screen/OSX: Return OS reported mouse delta movement in GetMouse() valuators.
  • Screen: Add ‘detachFromMouse’ support to SetMouse().
  • Screen: Fix CopyWindow to use windows clientRect instead of rect for Retina/HiDPI compatibility
  • Screen/OSX: Fix hostname display in Screen(‘Computer’)
  • DrawFormattedText: Remove 250 chars linebreak on OSX. - Diederick Niehorster
  • Screen: CopyWindow update help text.
  • Screen/Linux: Make ext_buffer_age warning less chatty.
  • Speak: Fix use with apostrophes in text string. - elladawu
  • ImageUndistortionDemo: Minor improvements.
  • ImagingVideoCaptureDemo: Add a (disabled) test line for CSV geometrycorrection.
  • CreateDisplayWarp: Bug fix and enhancement for CSV method.
  • New prototype quality display correction method: DisplayUndistortionLabRiggerMouseStim.m
  • PsychImaging: Update help text for task ‘UseRetinaResolution’
  • Update and extend conversions between degrees and mm of retina - David Brainard.

PTB BETA "Gifts for the gifted" SP1 released


The new BETA “Gifts for the gifted” SP1 was relased at 19th April 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-04-19_V3.0.12”, with the full tree and commit logs under the URL:

New features and improvements:

  • SetMouse multi-screen improvements for Windows. Allow positioning relative to screen origin, as the screenNumber is now also honored on Windows.
  • CMUBox doc updates for Windows. Describe how FIFO size must be set on Windows COM ports for good timing.
  • KbQueue fixes for OSX. Avoid hang of scripts in KbQueueRelease on some OSX setups.
  • PsychPortAudio improvement for Linux. Try to avoid selecting HDMI/DP audio on video outputs of graphics cards as default sound card. Prefer regular sound cards over graphics cards with sound output if possible.
  • Handle Intel ddx DRI2 triple-buffering on Linux, so visual timing works on Intel graphics chips without need for special xorg.conf settings or ddx drivers. It is now possible to even take advantage of triple-buffering with properly adapted scripts.
  • General improvements to timing checks on advanced operating systems which support OS native timestamping mode 4.
  • Documentation updates.
  • Fixes and refinements to demos.
  • New function CenterRectArrayOnPoint() contributed by Natalia Zaretskaya.
  • QuestQuantile() improvements by Denis Pelli.
  • Some improvements to color calibration routines by David Brainard.
  • Improvements for efficiency of clut updates and of error handling on VPixx devices.
  • Some compatibility updates to joystick configuration files for current Linux distributions.

PTB BETA "Gifts for the gifted" released


The new BETA “Gifts for the gifted” was relased at 16th March 2015.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2015-03-16_V3.0.12”, with the full tree and commit logs under the URL:

Major new features and improvements:

  • Experimental Wayland backend for Linux - disabled at compile time. Used for development and testing of Wayland 1.7/Weston 1.7, useable on those setups for simple tasks, but not ready for prime-time.

  • Many videocapture improvements for increased robustness on certain cameras, and for handling USB-3 USBVision IIDC compliant cameras, especially tested with PointGrey Flea, and for handling custom GStreamer sources like network streaming IP cameras.

  • Initial enablement work for using tracker plugins also under GStreamer.

  • ProPixx fast 4x / 12x mode, initial experimental support.

  • Many cleanups, small improvements and bug fixes.

  • Linux/X11 specific ddx video driver for nouveau dropped, as it is now part of the Ubuntu 14.04.2-LTS hardware enablement stack, so we don’t need our own binary anymore.

  • Linux/X11 specific ddx video driver for intel on XOrg 1.15 dropped, as Ubuntu 14.04.2-LTS HWE ships with XOrg 1.16 like Ubuntu 14.10, so we only need one driver for XOrg 1.16 on both 14.04.2-LTS and 14.10

  • Imaging pipeline compatibility fixes for Intel gpus. Avoid creating FBO’s with RGB > 8 bpc color attachments, as Intel HD series can’t handle those.

  • JavaSwingCleanup() cleanup code improved to make Matlab R2014b happy.

  • Retina support improved to also handle windowed windows, not only fullscreen on OSX.

  • VBLSyncTest improved to avoid/reduce effects of clock skew with Datapixx, new PerceptualVBLSyncTestFlipInfo2.

  • PsychHID on Linux can blacklist more non-keyboards automatically.

  • PsychHID on OSX may be more robust wrt. keyboard queues.

  • Additional pageflipping checks for AMD graphics cards under Linux and on OSX with PsychtoolboxKernelDriver.

Psychtoolbox 3.0.12 released


The first BETA “Random acts of kindness” was relased at 5th October 2014 and started the new Psychtoolbox 3.0.12 series. Now, one month later, after some stabilization and tweaking and some minor updates, and without any user complaints so far, it is about time to announce it.

As usual, the complete develoment history can be found in our GitHub repository. The release tag is “PTB_Beta-2014-11-06_V3.0.12”, with the full tree and commit logs under the URL:

Changes with respect to version 3.0.11:

System and software requirements

  • MS-Windows: Only 64-Bit Windows-7 is officially supported. PTB only gets (infrequently and lightly) tested with Windows-7. It should also work with 64-Bit Windows-8 and later and with 64-Bit Windows Vista and 64-Bit Windows-XP, but if you run into problems with those earlier or later systems you are on your own. Especially support for Windows-XP is expected to degrade due to lack of future testing and bug fixing. No care will be taken to prevent future development from breaking support for Windows XP or Vista.

    32-Bit versions of Windows will no longer work with Psychtoolbox 3.0.12.

  • Apple OSX: 64-Bit OSX version 10.8 “Mountain Lion” and later is needed for PTB to work at all, but only OSX 10.10 “Yosemite” is officially supported. No future testing, bug fixing or troubleshooting will be performed for any version but 10.10 “Yosemite”.

  • GNU/Linux: All reasonably modern versions of 32-Bit and 64-Bit Linux should work. Primary development and testing is done on Ubuntu 14.04-LTS and 14.10, and compatible flavors, e.g, KUbuntu 14.04-LTS and KUbuntu 14.10. These are the officially supported Linux distributions. GNU/Debian version 7 and upcoming version 8 are tested by the NeuroDebian team.

  • Matlab: 64-Bit Matlab on Linux, OSX and Windows. Current development and testing happens with R2012a but will probably be soon completely shifted to R2014b.

    32-Bit versions of Matlab are no longer working with Psychtoolbox 3.0.12.

  • GNU/Octave: On Linux, our “DownloadPsychtoolbox” installable version supports 32-Bit and 64-Bit Octave version 3.8.x for Debian and Ubuntu. On OSX, our “DownloadPsychtoolbox” installable version supports Octave 3.8.0 - 3.8.2.

    If you get your Psychtoolbox for GNU/Debian or Ubuntu from NeuroDebian’s repository then it will support whatever 32-Bit or 64-Bit version of Octave is officially shipping with your distribution - usually some Octave version between 3.4.0 and 3.8.x, depending on the age of your distribution.

    We do recommend upgrading your Linux distro to a release from the year 2014, as those will usually ship Octave 3.8 out of the box. Octve 3.8 features a Matlab like GUI for a higher level of convenience.

  • GStreamer: GStreamer-0.10.x is no longer supported. You must install GStreamer version 1.4.0 or later on Windows or OSX, GStreamer version 1.0.0 or later on Linux if you want to use any multi-media functionality like Video capture, Video recording, movie writing or movie playback.

  • PsychKinect support: Support for the Kinect now requires libfreenect version 0.5 or later on Linux and OSX. Suitable versions of libfreenect will be automatically provided by NeuroDebian if you install Psychtoolbox for Linux from their repository. On OSX you can get a sufficiently recent version of libfreenect from HomeBrew.

Major new features and improvements:

All operating systems:

  • GStreamer 1.0 as new multi-media backend. Apart from fixing some bugs of GStreamer-0.10, this should make Psychtoolbox multi-media handling more future-proof, as GStreamer-1.x is in active development and supported, whereas GStreamer-0.10.x no longer receives and maintenance, support or bug fixes from its developers. GStreamer-1 supports more video codecs, support for deep color video formats and more efficient multi-threaded video decoding for popular formats like H264. The latter should provide performance gains on multi-core Mac OSX and Windows machines, so performance on those legacy operating systems should come a bit closer to what Linux users are enjoying since many years.

    Caveats: Video capture and recording is currently unsupported on MS-Windows due to missing video capture plugins in the current GStreamer-1.4 distribution for Windows. This will start working again when the GStreamer developers provide suitable plugins. Video capture on OSX is limited to what Apples AVFoundation and QuicktimeKit support. Specifically capture from DV camcorder cameras didn’t work at all when testing under OSX 10.9. Audio-Video sync for video recording with USB webcams under OSX 10.9 wasn’t great at all. The best video capture and recording experience is expected under Linux, just as in the past. Movie playback with some video codecs on Microsoft Windows with some Matlab versions can cause random crashes of Matlab. This has been infrequently observed during playback of H264 video, e.g., with Psychtoolbox SimpleMovieDemo. These don’t happen always and are likely due to some incompatibility between some Matlab versions and GStreamer. There are no known problems wit any movie playback on OSX or Linux.

  • The PsychKinect driver now supports the XBOX Kinects and the original Kinect 1 for Windows - on Linux and OSX. Kinect for Windows is not supported on MS-Windows. Kinect 2 is not supported at all at the moment. The driver can handle multiple simultaneous Kinects.

  • Stereo crosstalk reduction support, especially for frame sequential stereo modes by Diederick. Useful, e.g., to reduce crosstalk on NVidia’s NVision shutter glasses. See help of PsychImaging.

  • Our MOGL OpenGL for Matlab and Octave low-level support now supports a large subset of OpenGL 4.5 functionality. Functionality of OpenGL versions more recent than version 2.1 is supported via OpenGL extensions as in the past, but our support is now more complete wrt. the latest OpenGL 4.5 spec. E.g., Geometry Shaders do work now.

  • The Datapixx mex files for VPixx devices like Datapixx, Viewpixx and Propixx is now available with identical full feature set on all operating systems and supported Matlab and Octave versions. PsychImaging will now take care of especially large VBLANK intervals as used by those devices in frame sequential stereo modes.

  • Improvements and bug fixes to the NetStation() driver for EGI Netstation EEG systems.

  • Bug fixes and enhancements to DrawFormattedText.

  • The RemapMouse function can now also handle display rotation by Psychtoolbox panel fitter, ie., rotation generated by the PsychImaging functions UseDisplayRotation and UsePanelFitter can now be properly handled wrt. mouse input, as demonstrated in PanelFitterDemo.

  • Many bug fixes and improvements to demos, help texts or other documentation.

GNU Linux

  • Support for Ubuntu 14.10 and compatible/derived flavors - tested with 64-Bit KUbuntu 14.10. help SyncTrouble points to a new set of example xorg.conf configuration files and explains how to install those in your system to optimize it for best visual stimulus onset timing and timestamping precision. This release has been tested on Ubuntu 14.04 and KUbuntu 14.04 and KUbuntu 14.10 with X-Servers XOrg-1.15 and 1.16, Linux kernels 3.13, 3.16 and later kernels on open-source radeon, nouveau and intel graphics drivers with multiple Radeon graphics cards, NVidia graphics cards and Intel graphics cards and shows excellent visual timing behaviour on all tested systems. Especially on Apple systems, the tested Linux distros outperformed OSX wrt. timing precision and reliability by large margins, sometimes up to 300x more precise.

  • Improved deep color 10 bpc framebuffer support on Linux. New 11 bpc and (up to) 16 bpc framebuffer support for AMD graphics cards when using the open-source graphics driver on a deep color capable HDMI or DisplayPort display device. Details of setup, limitations and capabilities for different systems are explained in the help text of PsychImaging.

Apple OSX

  • Support for Mac OSX 10.10 “Yosemite”. However, initial testing on two machines and user feedback suggests that 10.10 seems to be even more buggy and unsuitable for neuro-science applications than 10.9 and 10.8 were. None of the bugs present in OSX and known to me have been fixed by Apple, as far as initial testing goes. Visual timing and timestamping precision has degraded even further. Expect many new “Sync failures”, as all attempts to workaround OSX flaws have failed. The PsychtoolboxKernelDriver is now even more important for precise visual timing, but no longer works by default on Intel GPUs. Forcing its use on Intel gpu’s is possible but can cause serious system malfunctions on some Macintosh computers, with a small but non-zero probability of making your machine unbootable without the help of an Apple repair technician. In order to load the driver at all on OSX 10.10 for the supported NVidia and AMD gpus, you will need to disable kernel module verification in Apples OS. See “help PsychtoolboxKernelDriver” for instructions to do so at the downside of reducing system resilience against hackers and computer viruses.

  • Improved PsychHID for OSX: Now supports multiple parallel simultaneous keyboard queues, catching up a bit to the superior PsychHID for Linux. Now can cope with Apples broken HID keyboard handling on MacbookAir 2013 and later, making keyboard queues working again on the MacbookAir.

  • Support for Apple Retina displays. Visual stimulus onset timing and timestamping should work better now with such non-standard HiDPI display devices. Psychtoolbox will use its panel fitter by default to create backwards compatible behaviour to version 3.0.11, but with hopefully fixed visual onset timing, working around Apples Retina display hacks. A new PsychImaging task UseRetinaResolution allows to make use of the full resolution of Retina displays (typically twice the horizontal and vertical video resolution for 4 times more pixels), at the performance impact caused by the much higher GPU rendering load.

  • Many new awful workarounds for broken Apple operating systems.

PTB BETA "goto fail"


“goto fail” is an hommage to Apple’s fine software engineering skills and well known insane attention to detail and perfection.

“goto fail” is the final release of the 3.0.11 series. The next release will start the 3.0.12 series. It contains the following more notable improvements:

  • Our experimental 10 bit framebuffer support for Linux and OSX for AMD Radeon graphics cards is now also available (but untested so far) for Radeon HD-5000 and later graphics cards. In the past this was restricted to X1000 - HD-3000, now it should covers all currently shipping cards since X1000. Along this line goes more fine-grained control of dithering on digital display outputs via new parameters to PsychImaging’s EnableNative10BitFramebuffer functions and a new Screen('ConfigureDisplay', 'Dithering') subfunction; It is important to stress here that while 10 bpc output is known to work reasonably well for analog VGA connected CRT monitors, 10 bpc output to digital display devices will not work on OSX at all, and is unlikely to work over DVI or HDMI on Linux. We are currently looking into ways to enable > 8 bpc support on Linux. What you will get if you enable a 10 bpc framebuffer on such a display setup is a 10 bpc framebuffer which gets reduced to 8 bpc via dithering on the digital video output. Iow., you get simulated 10 bit precision via dithering, which may work reasonably well for some stimuli, or go horribly wrong for other stimuli.

  • Screen('Textfont') now allows atomic setting of font family and and font style with a single Screen('TextFont', window, fontName, fontStyle); call. This to resolve some problems encountered when on tries to use exotic fonts.

  • Eyelink bug fixes and improvements contributed by Li Jie of SR-Research and me. Eyelink('ImageTransfer') should work now, Drawing of targets in PsychEyelinkCallback should work on less capable graphics hardware, Various octave compatibility fixes to SR-Research demos. Eyelink('Command') robustness improvements against some input.

  • Fix Octave + PsychDataPixx long standing compatibility bug for timestamping, remove workaround from and cleanup VBLSyncTest.

  • Workarounds for nouveau-kms bugs in Linux 3.13/3.14 for the upcoming Ubuntu 14.04 LTS release. These bugs shouldn’t have made it into a release but did, because i wasted way too much time fixing Apple’s latest screw-ups, using up most of the testing time i planned to allocate for Linux + Ubuntu 14.04 testing. Anyway, this means that the open-source nouveau graphics driver for NVidia gpu’s will probably be of limited use for vision science until we get the required bug fixes into a post-release update. The proprietary NVidia driver should work just fine though. I will try to not let this happen again. Fixing any problems caused by Apple will have the lowest priority from now on.

  • Workarounds for OSX 10.8 dual-display stereo graphics driver bugs and various 10.8/10.9 graphics bugs. As it turned out during trying to resolve other OSX bugs, at least OSX 10.8 has a hilarious bug when used with two or more open fullscreen onscreen windows, e.g., for dual-display stereoscopic stimulation in stereomode 10. As soon as a 2nd onscreen window opens on a screen, the first previously opened onscreen window will be switched from page flipping for stimulus updated (good for timing and performance) to desktop composition. This is really bad for performance, visual stimulus onset timing and various other things, e.g., 10 bpc framebuffer support. It is also almost completely undetectable by software tests, so will have a good chance of silently corrupted presentation timing in such scenarios. The current PTB will enable a workaround for OSX 10.8 and later which fixed the problem at least on the one tested setup with AMD graphics. It is unclear if this would introduce any new subtle bugs. According to Apple docs it shouldn’t, but of course this is Apple talking about its own products and we know how well that goes in practice. I also realized when testing on my MacBookPro with 10.9.2 and NVidia graphics that 10.9’s swap scheduling on NVidia gpu’s seems to be utterly broken as well. PTB has a new visual test script OSXCompositorIdiocyTest() which you should run on your setups and dual display setups. If that test doesn’t show expected results then you can consider your setup being mostly unuseable for frame accurate visual presentation timing. There are no known workarounds for these issues. I don’t consider “modern” OSX systems trustworthy for frame-accurate visual presentation anymore.

    Bugs not fixed on OSX 10.9: Sometimes you will be left with a blank screen at the end of a session after PTB closed its windows. A mouse click, keyboard press gives you your GUI back. This bug brought to you by Apple. The only known workaround is to use Screen('Preference','ConserveVRAM', 16384); which will likely reduce performance and visual timing accuracy - or possibly make visual timing untrustworthy. I can’t test this because my only remaining Mac test machine has a NVidia graphics card with broken graphics drivers, so timing on my only test machine is always untrustworthy.

    Keyboard queues apparently don’t work at all on recent MacBookAir’s on at least 10.9, because Apple completely broke backwards compatibility in the relevant bits of the OSX HID subsystem.

  • Ability to disable crashy CVDisplayLink timestamping on OSX: PsychTweak('DisableCVDisplayLink'); now allows to disable CoreVideo timestamping as a workaround for timing. If you care about timing you should always install the PsychtoolboxKernelDriver on OSX. CoreVideo timestamping was used as a workaround for setups where this couldn’t be used, e.g., on all Intel graphics cards. The method has proven unreliable due to Apple CoreVideo bugs not fixed since years, but additionally its use causes random crashes at the end of experiment sessions on some setups for some users.

  • PsychImaging - add convenience setup function for dual-display stereo mode 10. See ImagingStereoDemo for the simplified setup for stereomode 10.

  • PsychImaging - Improve 10 bpc framebuffer setup: Do not disable dithering on digital output by default, but leave decision to OS, with option to override.

  • Screen('ConfigureDisplay', 'Dithering') allow low-level control of AMD dither control registers.

  • Various help text updates.

  • Various updates to color calibration/color handling routines by David Brainard.

  • Misc other fixes.

  • PsychtoolboxKernelDriver updates. Different drivers for legacy 10.7 and earlier vs. 10.8+. Apple removed the necessary sdk’s from its latest XCode to build the PsychtoolboxKernelDriver for OSX versions earlier than 10.8. Therefore we now have a for OSX 10.8 and 10.9, which contains bug fixes and improvements. Then a legacy set of 64-Bit and 32-Bit kernel drivers for OSX 10.7 and earlier. These legacy drivers are no longer maintained and contain known bugs and limitation.

  • The OSX Psychtoolbox now requires Octave 3.8.0 or later. It will not work with Octave 3.6 and earlier anymore. It could be made working by manually setting a symbolic link in the file system if somebody wants to stick to 3.6. But upgrading to 3.8 is a good thing, as it now provides a useable GUI and other improvements relevant for PTB.

End of support for Windows XP...


A gentle reminder that the end of life for Microsoft Windows XP is approaching quickly:

What a lucky coincidence that April 2014 is not only the month of the scheduled demise of Windows XP, but also the month of arrival of the next Ubuntu Linux long term support release Ubuntu 14.04-LTS.

Starting with the next PTB beta release and start of the ptb 3.0.12 series, people can consider Windows XP and Vista unsupported at least by me. While i expect ptb to continue to work ok on WinXP, and i won’t sabotage it intentionally, i will not perform any testing, bug fixing or support for that system in any way for probems only related to WinXP or Vista. The very little bit of tuning and development that happens for the MS os’es at all will focus on Windows-7 and later.

“If you discover you are riding a dead horse, the best strategy is to dismount.”

PTB BETA RELEASE "Sex, Lies and Video"


  • OSX 10.9 Mavericks compatibility fixes. E.g., for AppNap protection, visual timing fixes, other brokeness fixes.
  • Rewrite of OSX FontInfo and DrawText renderer for higher startup speed and compatibility and future proofing.
  • Add new supported GPU’s from AMD.
  • Minor bug fixes for OSX, Windows, Linux, e.g., IOPort, Eyelink, PsychHID KbQueues.
  • General improvements to video capture and video recording, e.g., for DV cameras.
  • DC1394 based Firewire video recording support, high bit depths capture support, various other bells and whistles.
  • DC1394 based Firewire multi-camera synchronized video capture/recording.
  • Staircase procedure improvements by Diederick Niehorster.
  • PsychColorimetric routines improved by David Brainard.

PTB BETA "Hammertime!" - SP4 "Deadlock"


This beta release fixes some ugly regression introduced into the PTB for Linux in the last beta. The regression could cause a crash of Octave or Matlab when quitting the application or clearing the Screen function on some setups with some scripts.

It makes DaqDeviceIndex mildly more robust on 64-Bit OSX by applying a new set of horrifiying hacks.

Fixes some small bugs in IsomerizationIn[Eye/Dish]Demo and makes them work on Octave again, after some regression was introduced this summer.

PTB BETA FlowerPower released


This one is just a bug fix for the FlowerPower beta 3 days ago.

It fixes some locking bugs introduced into the Linux PTB by the last release, which only affect use of FOSS graphics drivers with frame-sequential stereo or async flips. Those fixes could have caused a deadlock in those use cases.

This release was successfully tested against the upcoming Ubuntu 13.10 “Saucy Salamander” release.

PTB BETA RELEASE "Hammertime!" SP2 - "Flowerpower"


  • Cool new SuperShapeDemo by Joana Leitao.
  • Display rotation support in PanelFitter, as shown by PanelFitterDemo.
  • Make DrawText on Linux multi-x-screen capable and even faster than before.
  • Make BitsPlusImagingPipelineTest a little bit more lenient.
  • Improve display locking on Linux, and various micro-optimizations.
  • Remove beamposition timestamping support for Intel gpu’s on OSX and Linux.
  • Small improvements to Daq toolbox and other stuff.
  • Disable mex files for OSX versions before 10.6 Snow Leopard.

Stop! PTB BETA RELEASE "Hammertime!"


Stop! It’s time for Hammertime :)

Hammertime contains mostly bug fixes, but also a few neat improvements: Break it down!

Change of software requirements:

  • Go with the flow! Psychtoolbox for 32-Bit Matlab on MS-Windows now uses and requires the GStreamer SDK, instead of the rather old GStreamer runtime from the OSSBuilds project. If you want to use multi-media functions, you will need to uninstall your old OSSBuilds GStreamer and install the 32-Bit GStreamer SDK. help GStreamer contains updated instructions.

If you want to stick to the old SDK, you can DownloadPsychtoolbox() with flavor Psychtoolbox-3.0.11-PreWinGStreamerSDK. This will download and lock your Psychtoolbox permanently to the “Stadtmusikanten” release from last week, the last PTB to support OSSBuilds GStreamer.

Bug fixes: Just for a minute let’s all do the bump, bump, bump

  • Bugfix for GStreamer OpenGL bugs on Windows for movie playback with special pixelformat >= 6. Thanks to Matthew Edmundson for help in debugging this.

  • Bugfix for Linux + PsychHID: A bug in HIDAPI, the FOSS library we use as backend for low-level USB-HID device access, caused the failures described by Ian Mackenzie in forum message #16555. After use of a PsychHID low-level function, Octave and Matlab stopped parsing decimal numbers iff the system number formatting (“Country and language settings”) was setup to use “,” instead of “.” as a decimal point. E.g., german number formatting would do this. An update of PsychHID to a bug fixed HIDAPI solved this.

  • Bugfix for OSX crash at window close due to Apple OSX CVDisplayLink bugs on Matlab R2013b, as reported by Keith Schneider in forum msg #16553. Hopefully…

Improvements and new functions: Fresh new kicks advance!

  • OpenGL context sharing support between “windowed” non-fullscreen windows and fullscreen windows on OSX is now sometimes possible, at least on OSX 10.7 and later with NVidia cards, maybe also with other cards or an earlier OSX version. This means that the scenario desired in forum message #16114 may now work at least on some OSX setups. This enhancement was possible because we dropped support for OSX 10.5 and i could cleanup and rewrite our window and OpenGL context setup code to take advantage of some post-10.5 features.

  • Improved GUI window support. GUI windows now click better with some users.

  • Low-level support for latest and upcoming AMD GPU’s on Linux and with OSX PsychtoolboxKernelDriver. Beamposition timestamping and other special goodies should work with those new gpus.

  • You can’t touch this! WinTabMex for touch screens and digitizer tablets with WinTab api is now also available for 64-Bit Matlab on Windows, thanks to some enhancements contributed by Jason Friedman.

  • At the end of the day, stop a bit for some hammertime in PlayMoviesDemo’s cool video section, and bust a few moves.

PTB BETA "Stadtmusikanten"


  • ECVP2013 demos and tutorial slides PDF file added.
  • New function PsychDefaultSetup for normalized color range by default.
  • Some new demos, e.g., SimpleSoundScheduleDemo.
  • PsychColorimetric improvements by David Brainard.
  • Minor fixes and improvements here and there.

PTB BETA RELEASE "Blue skies and empty brains" - SP2


Mostly bug fixes and minor improvements, most interesting is probably the Eyelink() stuff.

  • Fix download failure for legacy v3.0.10 in DownloadPsychtoolbox() on 32-Bit Matlab for OSX.

  • Fix mex file load errors on 64-Bit Octave for OSX with Octave installed via Fink package manager and for other versions of Octave than 3.6.1 with HomeBrew.

  • New function Eyelink('SetAddress') for setting tracker computer target IP address, to allow selection of non-default IP address.

  • Enable raw sample data access for Eyelink on Linux. This requires the latest Eyelink packages for Linux, Windows, OSX. For entertainment value, SR-Research provides up to date 32-Bit packages for Debian/Ubuntu Linux via automatic software update, but delivers outdated and incompatible 64-Bit packages via software update, despite matching version numbers and release dates! However, downloading and manually installing the .tar archive for 64-Bit from their Linux support area works fine. Great release engineering guys, i had so much fun with this!

  • Updated help for PsychVideoSwitcher by Xiangrui Li to clarify how the toggle between Luminance and RGB mode works.

  • Update some other help texts, e.g., DisplayOutputMappings, to describe multi GPU support/issues/workarounds.

  • Add new text rendering mode 0 on OSX for new-style ATSU rendering of problematic exotic fonts. Screen('Preference', 'TextRenderer', mode) still defaults to 1 on OSX, but a setting of 0 uses a different layout strategy which handles some fonts better, e.g., Denis Pelli’s “Kuenstler LT”, while breaking layout for other fonts, e.g., Japanese Kanji. Great work Apple, you rule! The best solution is actually to use mode 2, which uses the (ported) Linux text renderer instead of the Apple text renderer on OSX. That renderer handles all known fonts at same or better quality and flexibility with much higher performance. However, we stick to classic mode 1 on OSX for reason of consistency, so modes 0 and 2 are opt-in.

  • Add GstX264Enc video encoding profile for fast camerabin2 video recording with GStreamer SDK. This makes VideoRecording work reasonably well with the GStreamer-SDK on 64-Bit Windows.

  • Some new demos and improvements from David Brainard in area of color calibration or simulation, e.g., IsomerizationInDishDemo.

  • New function GetGITPath from Ben Heasley.

PTB BETA "Rainbows, Droids & Compute Hippies!" SP12 released


The last update to the latest beta. Some feature improvements for use of the GStreamer SDK, especially on Windows. Upgrading to the 2013.6 SDK is recommended. Some minor other improvements and some bug fixes.

Bug fixes have been applied to the Psychtoolbox-3.0.10 flavor as well, but functional improvements are no longer applied to 3.0.10 aka 32-Bit OSX.

Users which want to stick to ancient OSX 10.4 or 10.5, or want to continue to use PTB with 32-Bit Matlab on OSX are advised to switch to the Psychtoolbox-3.0.10 flavor immediately by use of the DownloadPsychtoolbox() function with the flavor parameter set to Psychtoolbox-3.0.10. The next PTB beta update, whenever that will happen, will remove all support for those ancient configurations without further warning.

  • Make drawtext plugin on Linux and OSX more robust against weird fonts (non 8bpp fonts). This fixes the bug on Gentoo Linux reported in msg #15827.

  • Improve window focus handling for GUI windows on Linux. Don’t steal window focus.

  • Enable video capture and recording with GStreamer SDK. Video capture works on OSX with the SDK. Video recording works, but so far has very low performance with the SDK. Functionality should work on 64-Bit Matlab on Windows, but is so far mostly untested.

  • Enable movie writing with GStreamer SDK 2013.6. Works ok on OSX. On MS-Windows, it currently manages to write a valid movie file, but often hangs Matlab at the end of the writing session, so this is of limited use on Windows…

  • Enable delay loading of GStreamer SDK dll’s for 64-Bit Matlab on Windows to make installation of the SDK optional. Screen() will work without the SDK being installed, as long as no video capture/recording, movie writing or movie playback is used. This is now consistent with the behaviour on 32-Bit Matlab for Windows and should simplify installation of the Windows PTB a bit.

  • Fix regression in BubbleDemo, which was introduced in a previous beta release.

  • Allow sending arbitrary data types in NetStation() to the EEG system, not only 32-Bit integers. Contributed by Matt Mollison, University of Colorado Boulder, Department of Psychology and Neuroscience.

  • Performance improvements for DaqAInScan et al., contributed by Daniel Braun, University of Birmingham.

  • Fix GLU toolkit NURBS functions regression, so they can be actually used.

  • Movie demo cleanups for pure GStreamer operation and no more Quicktime.

  • Improvements to radiometric functions by David Brainard.

PTB BETA RELEASE "Rainbows, Droids & Compute Hippies!" SP8 - Final


Final 3.0.10 series release update:

  • Reduce verbosity of PsychHID’s libusb debug output to “silence” on Linux by default.
  • Add proper psychtoolbox udev rules for MCC DAQ operations on Linux without root.
  • Verify Daq toolbox works mostly with MCC USB-DAQ 1408FS, disable obsolete warnings.
  • Try to make DaqAInScan work with 1408FS on 64-Bit OSX – unsuccesfull.
  • Small fixes & improvements to Daq toolbox.
  • Screen for 32-Bit Matlab on OSX final recompile to sync up with beta.

This is the branch point for the 3.0.10 branch.

PTB BETA RELEASE "Rainbows, Droids & Compute Hippies!" SP4, SP5, SP6, SP7



PTB BETA RELEASE “Rainbows, Droids & Compute Hippies!” SP7

  • moglcore build fix for NeuroDebian et al.


PTB BETA RELEASE “Rainbows, Droids & Compute Hippies!” SP6

  • A fix provided by zacklb for a regression introduced in new Java setup code.


PTB BETA RELEASE “Rainbows, Droids & Compute Hippies!” SP5

  • Fix octave short-circuit operator warnings by fixing all M-Files.
  • Factor out Java classpath Matlab setup into one function.
  • Update a few Datapixx mex files.
  • Fix a PR-705 toolbox bug (zacklb).
  • Tiny other stuff.


PTB BETA “Rainbows, Droids & Compute Hippies” SP-4

Fixes to DAQ toolbox, PR-xxx toolboxes, Screen(), online documentation and help, display calibration and other small bits.

End of life for 32-Bit PTB for OS X, and OS X 10.4, 10.5


A little reminder that I will suspend development & support for:

  • All 32-Bit versions of PTB for Mac OS X, aka 32-Bit Matlab.
  • All versions of PTB for OS X 10.4 “Tiger” and 10.5 “Leopard”.
  • All classic Apple Quicktime support.
  • The PsychtoolboxKernelDriver for 32-Bit OS X Kernels.

… before end of May 2013. The latest beta release from yesterday may be the last one for those platforms. Maybe I’ll do some “service pack” releases to fix post-release bugs common to all platforms or such within the next few days or weeks, but no significant new features or improvements or bug fixes will be added anymore until the quickly approaching end of life. At end of life time, a new unsupported branch will be created for those who want to stick to the old version.

PTB beta “Rainbows, Droids & Compute Hippies!” release 2013-04-20


Git tag: PTB_Beta-2013-04-20_V3.0.10

This release contains a couple of new features and improvements, some rather experimental by now, but also the usual amount of small improvements and bug fixes.

All systems:

  • Basic GPGPU compute support:

    A first sketchy implementation of (G)eneral (P)urpose computation on (G)raphics (P)rocessing (U)nits support. We already supported (ab)use of GPUs for other tasks than rendering since the beginning of 2007, with our built-in imaging pipeline and various plugins to accelerate common image processing and stimulus post-processing operations. However, so far all functionality was implemented by reformulating computation tasks as graphics rendering tasks and executing them as a mixture of fixed-function OpenGL rendering and programmable vertex- and fragment-shading via the GLSL OpenGL shading language. This works very well for many visual processing problems, but can become awkward or inefficient for non-graphics compute problems. Technology progressed and nowadays most modern GPUs support GPGPU in a more straightforward and efficient way by use of NVidia’s CUDA API (for NVidia GPUs only) and OpenCL for pretty much all GPUs on the market, including NVidia’s, so it’s time to look into what can be done better with those APIs for stimulus creation. This beta release contains basic support for utilizing NVidia CUDA capable GPU’s under 64-Bit Matlab by use of a high-level open-source toolbox called “GPUmat”, which can be downloaded for Linux and Windows from here: GPUmat toolbox download link

    GPUmat allows to implement computational methods in familiar Matlab language, as it extends Matlab with new GPU data types GPUsingle and GPUdouble. If vectors and arrays are created with this datatype, then the data is stored on the GPU and processed in parallel by the GPU. Psychtoolbox initial implementation provides builtin functionality to detect if GPUmat is installed and to initialize it, if so. It also provides an interface for efficient data transfer and synchronization between GPUmat and Screen/OpenGL. Screen’s floating point framebuffers, offscreen windows and textures can be efficiently passed to GPUmat as GPUsingle matrices to do computations on them and resulting matrices can be converted back into PTB’s representation for post-processing, rendering and display. In this initial release, I focused on getting the high-level setup code right to hopefully allow future painless extensions, and to optimize data transfer between PTB/OpenGL and GPUmat/CUDA.

    Benchmarking showed that the current data transfer works with > 90% of the theoretical peak performance of the tested GPU under Linux, with about 30-40% efficiency on Windows, and IIRC in the 1-2% range on OS X. Profiling showed that the OS X implementation essentially performs data exchange with the speed of a slow software fall-back path and unsurprisingly the deficiency seems to be in the OS X graphics subsystem - another area where the most advanced operating system in the world falls way short of its competitors. This means that if you like to use this functionality, you can gain an almost 100x performance boost for some tasks by running you Mac under Linux instead of OS X.

    There are currently three demos in the PsychDemos/GPGPUDemos subfolder, all showing fast application of a 2D-FFT and inverse FFT to GPU accelerated image filtering by replacing convolution with a point-wise multiply in frequency space.

    Current restrictions: Only 64-Bit Matlab supported, as GPUmat needs object oriented programming support v2 (“classdef” OOP) which is not yet available in stable releases of GNU/Octave. However, octave’s classdef support has made quite a bit of progress, so I’m optimistic this will work for stable octave in the not too far future. Only 64-Bit because I’m too lazy to maintain this for 32-Bit as well. There are not technical reasons, just that people should move to 64-Bit if they want to do this style of computing efficiently. Only NVidia CUDA capable GPU’s for now, as GPUmat is based on CUDA. The long-term goal would be to primarily support OpenCL, as it is cross-platform, cross-vendor and also supports non-GPU compute accelerators. Only Linux and Windows as of today, because GPUmat is not yet available for OS X. I ported it to 64-Bit OS X, but haven’t submitted it upstream for inclusion into the official distro yet, that’s a todo.

    Setup instructions under help PsychGPGPU, demos under help GPGPUDemos.

  • RenderDemo shows a new way to use our imaging pipeline and new plugins to perform GPU accelerated color space conversion and calibration. New functions of the imaging pipeline allow to convert from the XYZ tristimulus color space to calibrated RGB output, taking the calibration data from our color calibration routines into account.

    Wikipedia’s definition of XYZ color space

    The advantage is that all the color calibration can now get easily integrated into our stimulus post processing pipeline, and of course speed. The demo also shows a new plugin to convert from xyY color space to XYZ color space. It should be noted that this is only lightly tested. While light testing of a few sample values showed proper behaviour, David Brainard wants to write more exhaustive unit tests at some point in the future. Of course patches for tests are welcome.

  • CRS Bits# support: The display subsystem of the Cambridge Research Systems Bits# device is now fully integrated for convenient and efficient use. The I/O system is todo. Demos and tests have been updated to take advantage of new Bits# functionality like improved diagnostic and troubleshooting.

  • PR-705 photometer support contributed by Zachary Lindbloom-Brown.

  • The ColorCal2 driver now also works with GNU/Octave, thanks to the donation of a ColorCal-II by CRS. The driver seems to work very well on Linux, is a hit and miss on OS X, apparently due to funny new OS X bugs or incompatibilities, and was a no-go for me so far on Windows. The current driver uses USB-HID protocol to communicate with the device, which seems to be flaky on non-Linux. It might make sense to switch it over to good old Serial-over-USB protocol which is probably more trouble-free on the other OS’es.

  • OptiCal support, contributed by Andreas Widmann, although it could be this

  • Various smaller fixes and improvements, e.g., updates to demos, DrawFormattedText now accepts arbitrary ’rect’angles for layout of text, not only the bounding rectangle of the target window or texture, OS specific fixes, …


  • Linux Google Nexus-7 / ARM support:

    Included in this release is experimental support for the Google Nexus-7 tablet when run under Ubuntu Linux 13.04 “Raring Ringtail”, 32-Bit ARM edition. This won’t work under the normal Android OS on the tablet, but you will need a tablet edition of Ubuntu desktop Linux, either as only operating system, or as dual-boot setup in parallel to your Android OS. Psychtoolbox seems to work reasonably well on the tablet, with a certain amount of tweaking.

    What works? GetSecs/WaitSecs with usual precision, real time scheduling, sound (PsychPortAudio and 3D OpenAL), keyboard and mouse I/O — touch input as mouse input, IOPort and PsychHID stuff is so far untested, but expected to work normally if you have an OTG adapter cable, Screen() and MOGL 3D OpenGL mostly works, i.e., all the basics work. What doesn’t work is functionality that requires programmable shading support, as we currently only support OpenGL-ES1.1 fixed function rendering, not OpenGL-ES2.0 programmable shading.

    Simple installation instructions for Ubuntu Linux on the Nexus-7 under this link.

    This would wipe your Android OS and data from your device, so no more “Cut the rope” or “Angry Birds” for you, but all the fun of drifting gabor patches and movie playback.

    I chose a dual-boot setup, which preserves Android and its goodness, but requires serious tinkering, and averaging installation instructions over multiple partially incomplete or mutually contradictory howtos, e.g., this howto.

    Anyway, this is mostly a test setup for now to see how much interest there is in Psychtoolbox for mobile devices and what the challenges are. I chose the Nexus-7 because it is the reference device for porting and testing Ubuntu Linux and it is also rather good price/performance at 200$/Euros.

  • Linux highly experimental multiple display and rendering backend support: Not really interesting for now, but this is to test next generation display system support for the Linux PTB, ie., non-X11 display setups, EGL, Wayland, raw framebuffer, Android and OpenGL-ES / OpenGL-3/4/…


  • More fixes for OS X Retina and LCD timestamping brokeness and other OS X bugs. I now recommend to always install the PsychtoolboxKernelDriver if you use OS X 10.7 or later and want precise stimulus onset timing or timestamping. The level of OS X brokenness has reached the point where our own implementation is almost always better than what Apples OS has to offer. E.g., OS X beamposition queries are only supported anymore on NVidia GPU’s and scheduled by Apple for complete removal in a future OS X release. Even on NVidia the mechanism is slightly broken and inaccurate on all modern GPUs and totally broken as of OS X 10.8 for any kind of digital flat panel / LCD / DVI-D etc. - it only sort of works for classic analog VGA connected CRT monitors.

PTB beta “The fun in dysfunction” SP2 release 2013-1-14


Git tag: PTB_Beta-2013-01-14_V3.0.10

This update is dedicated to Aaron Swartz (R.I.P.) and others who fight for freedom of information and the internet. It contains some improvements to M-Files.

All systems:

  • Full panelfitter high-level setup support via PsychImaging('AddTask', 'General', 'UsePanelFitter'): Selection of common scaling/fitting modes. Fully compatible with all stereo display modes, high-precision display modes and other PsychImaging tasks. Also now fully compatible with RemapMouse().

  • Cleanups to BeampositionTest by Ian A.

  • Robustness improvements to GStreamer-SDK detection on 64-Bit Windows.

  • Fix PsychImaging display mirroring when only fixed-function pipeline is active.

  • Tiny fixes in moglmorpher() and LoadOBJFile().

  • Minor tweaks to some demos.

PTB beta “The fun in dysfunction” SP1 release 2013-1-8


Git tag: PTB_Beta-2013-01-08_V3.0.10

More fun with dysfunction:

  • Minor bug fixes to PsychDataPixx on some setups.

  • Improved interaction of panelfitter with new side-by-side stereo mode.

  • Documentation updates regarding installation of Psychtoolbox kernel driver on OSX.

  • Improved support for Retina Mac Book Pro.

  • Support for Geforce 600 Kepler GPU’s on OSX.

  • Experimental support for 4 display heads on Kepler GPU’s for OSX and Linux.

PTB beta “The fun in dysfunction” release 2013-01-04


Psychtoolbox-3/Psychtoolbox-3@89ac3a06 at GitHub tag: PTB_Beta-2013-01-04\_V3.0.10

All systems:

  • Support for GStreamer camerabin2 video capture & recording: Once a future release of the GStreamer-SDK catches up in functionality, this will enable video capture and recording on 64-Bit OSX and for 64-Bit Matlab on MS-Windows. Currently it only works on Linux, or for 32-Bit Matlab on Windows or for OSX either with 32-Bit Matlab or with a self-compiled GStreamer installation from Homebrew.

  • Support for a new builtin imaging pipeline panel fitter: This allows to open onscreen windows whose drawing area size is bigger or smaller than the area of the screen occupied by the window. A new optional parameter clientRect for Screen('Openwindow',...); allows to specify the “virtual size” of the window, whereas the old rect parameter still specifies the true size of the window on the screen. Psychtoolbox will pretend your window is only the size of clientRect, but at Screen('Flip') time it will upscale or downscale your stimulus image to the true size of the window, applying linear or better filtering for this zoom.

    Why would you want to do that?

    Typical flat panels and projectors only work optimally at their native resolution. All other resolutions usually cause at least funny timing problems or sometimes visual artifacts with dynamic stimuli. This option allows you to transfer a script written for visual stimulation on, e.g., a CRT monitor or a panel on a certain resolution, to a different experimental setup which has a different native display resolution with minimal modifications to the script in case your script made assumptions about the display resolution in use. It would be especially useful if you worked in a place where some equipment is badly maintained and tends to break down in the middle of data collection, so it needs to be swapped with incompatible equipment of different native resolution. This release still misses the high-level setup code in PsychImaging() to access and configure this feature in convenient ways, so the panel fitter may not work well or need some tinkering when used together with some advanced features, e.g., some stereo display modes or high precision display modes which use a unusual display geometry themselves. This will be fixed in a future release. For standard bread & butter rescaling it works well. Of course it is still better to choose your resolutions wisely or write your code resolution independent if possible, as the scaling comes at some cost of another millisecond or two spent on rescaling in the gpu.

  • Small fixes to PsychKinectCore and to PsychHID.

  • Various other fixes for small documentation and PTB bugs.

  • Potential multi-threaded decoding improvements for GStreamer movie playback. The multi-threaded high performance playback mode introduced in the previous beta is so far only effective on Linux and on the GStreamer packages provided by the Homebrew package manager on OSX, but not with the GStreamer-SDK on OSX or Windows. This beta prepares higher performance playback with a future version of the GStreamer-SDK.

  • Support for a popular HDMI stereo frame packing format, side-by-side horizontally compressed stereo. PsychImaging() has a function to enable this, ImagingStereoDemo(102) demonstrates it.

  • Datapixx and Eyelink improvements.

  • Use of multisample anti-aliasing MSAA with imaging pipeline enabled should now work better on deficient OSX graphics drivers, especially in 3d rendering mode due to addition of new/improved error handling and fallback path.


  • Improved Linux support for timestamping, graphics problem detection and desktop compositor handling. This further increases the advantage Linux users already had over OSX and Windows users wrt. timing precision. This beta has been tested with different common desktop GUI’s for Linux wrt. to correct stimulus display, proper timing and timestamping and display synchronization across dual-display setups, e.g., for stereoscopic presentation, with a NVidia GeForce 8800 card under Ubuntu Linux 12.04.1-LTS, the latest NVidia binary drivers and a Datapixx for external measurement of stimulus onset timing and timestamping. It works perfectly well on single-display and on dual-display setups under KDE-4 with KWin desktop manager, GNOME-3/Gnome-Shell with Mutter dektop manager, LXDE with OpenBox, GNOME-2 classic without desktop compositor, and XFCE-4 with/without compositor. It works perfectly well on single display setups, but not on multi-display setups with desktop GUI’s based on Compiz: Unity and GNOME-2 work well single display but not dual-display. This must be a bug in Compiz introduced by the latest software updates to Ubuntu 12.04 LTS sometime December 2012. Canonical applied some optimizations to improve video game performance, which worked out well on single display setups, but apparently went wrong for dual-display setups. It doesn’t work well at all with the Unity-2D desktop, something is broken there. If you run data collection i would recommend running a desktop GUI without compositor, e.g., by creating a separate “experiment” user account on your machine where data collection is run and a pure 2d desktop is installed, e.g., XFCE-4 with desktop composition turned off, or LXDE+OpenBox. This gives you that extra piece of mind that even if there would be compositor related bugs in Psychtoolbox or your system, no compositor could interfere, because something that doesn’t exist can’t interfere. It may also give you a few percent extra performance. However, the desktop GUIs mentioned above are well behaved even if a compositor is active, as PTB can temporarily turn off the compositor, or the compositors switch themselves to standby during an experiment session. It’s a tradeoff you have to make between paranoia vs. convenience and bling.

  • Improved workarounds for handling of slightly broken Intel-DDX graphics drivers on Linux (pre 2.20.16 series). Intel video drivers before version 2.20.16 but after June 2011 have a bug in their swap scheduling. Psychtoolbox will detect this bug and enable a workaround for such drivers since the previous beta. The detection code has been improved. Of course it is best to update to a fixed driver (v2.20.16 or later) asap.


  • Improved support for handling of MS-Windows-8 dektop compositor: Psychtoolbox is better at detecting if a desktop compositor on Windows Vista/7/8 interferes with timing and can warn you in most cases. However, Windows-8 does no longer allow to disable the compositor, neither manually by you, nor automatically by us. This means you have to completely rely on the compositor disabling itself for fullscreen window displays, something that didn’t work well at all in the past. Testing with an up to date Windows-7 system showed that the compositor now auto-disables for fullscreen windows on single-display setups, but fails miserably on multi-display setups. I didn’t test with Windows-8 as we don’t have or use that os. Maybe Windows-8 behaves better than Windows-7. If it doesn’t then it is completely unuseable for timed stimulus presentation an anything but a single display setup, with no second monitor even connected.


  • Bugfixes / Workarounds for some MS-Windows bugs and many new MacOSX 10.7+ operating system bugs. If i had to describe Apples latest operating systems in one word it would be “Dysfunctional”. Especially many fixes are related to use of high-precision display devices like Datapixx/Viewpixx/Propixx/Bits+/Bits# etc.

PTB beta “Dancersizing, Grey & Hopeless” release 2012-11-11


Psychtoolbox-3/Psychtoolbox-3@9b5c6901 at GitHub tag: PTB_Beta-

This is mostly a bug-fix release, but it also improves GetChar support on some platforms.

All systems:

  • 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 useable support for Windows Vista, Windows-7, Windows-8 (untested), Matlab in -nojvm mode, and for GNU/Octave in its standard terminal command line interface mode, and the GUI which will be part of the next major Octave release. Now this mode will use keyboard queue functionality, which means it doesn’t work if your code already makes use of keyboard queues. More specifically: On Linux it will block access to the keyboard queue of the default keyboard, all other queues will work. On Windows it will block access to all keyboard queues, but allow use of the “keyboard queues” to query mice, joysticks and other non-keyboard devices. On OSX it will block all use of keyboard queues, because there is only 1 queue, as opposed to Linux/Windows which can have many parallel queues. Otoh, code that explicitely uses keyboard queues will have a more flexible and powerful interface to keyboards anyway. GetChar et al. are just for simple and convenient keyboard access, and mostly to keep old code working, so this shouldn’t be much of a limitation.

  • CRS OptiCal support by Andreas Widmann, Uni Leipzig. The OptiCal() function allows reading measurements from a CRS OptiCAL luminance meter connecte to a serial port.

  • Various other small improvements.

  • PsychPortAudio: Now reports ElapsedOutSamples more precise, even in some corner-cases where that count could be off by up to a millisecond in the past.

  • Some audio demos have been improved, ie., cleaned up, to show best practices for the current driver instead of the stuff that was considered optimal 2 years ago. The old code of course still works perfectly with the current driver, but sometimes did unneccessary complex stuff that is no longer needed for the current driver. PsychPortAudioTimingTest now also adapts a bit better to the kind of large latencies required to make shoddy MS-Windows setups work.

  • IOPort: If async background data reception is used, e.g., to automatically receive and timestamp trigger bytes from a serial port, and a read timeout occurs, e.g., the trigger source hasn’t been started within the max 25 secs timeout, then the driver will return an empty [] packet, instead of one that is filled with zeros. The old behaviour was confusing, this one now behaves in async mode as it would behave in sync mode.


  • PsychGPUControl: Can now also automatically disable 3D desktop composition on Ubuntu Linux 12.10, at least when the Unity interface is active. So far it was incompatible with 12.10 and did nothing. However, the general recommendation is still to manually disable any kind of 3D desktop compositor on experiment machines, regardless what OS you use. It avoids possible confusion if the automatic fails - which can happen on both Linux and Windows under some circumstances without PTB noticing this, and helps performance in any case, because even a compositor on standby will use more valuable graphics resources and cpu/memory than a disabled compositor.


  • Screen: Videocapture should now also work with 64-Bit Octave on OSX, not only with Matlab.

PTB beta “Death by a thousand paper cuts” release 2012-10-09


Psychtoolbox-3/Psychtoolbox-3@759f023b at GitHub tag: PTB_Beta-

This is mostly a bug-fix release to deal with various operating system and graphics driver bugs discovered after the last release.

Release Highlights:

All systems:

  • The Speak() command is now supported on all operating systems, and made more flexible. Very flexible Linux support via speech dispatcher service added. Basic MS-Windows support added by Vishal Shah from the Pelli lab at NYU. Mac OS support made slightly more flexible.

  • Improvements to general graphics driver sync tests to catch some interesting potential future bugs. Some warning clutter removed where it was redundant.

  • Enhancements to the PsychPortAudio backed Snd() legacy sound command: Snd() uses PsychPortAudio internally for higher robustness. However, this means that use of Snd() is incompatible with simultaneous use of PsychPortAudio() within the same script. Snd() now notifies you of this, and also falls back to the old Matlab / Octave sound() function, if PsychPortAudio is already in use.

  • Some improvements to DKL color functions by David Brainard.

  • Make Screen startup more artifact free on setups with OpenGL triple-buffering enabled. So far you have to disable triple-buffering on any graphics driver on any operating system to get PTB to work correctly timing-wise. Or more specifically, you have to refrain from enabling triple-buffering, as triple-buffering is off on almost all graphics drivers and operating systems by default. However, i’ve just submitted patches with improvements to the Intel and Nouveau drivers for Linux. Once the improved drivers will be released, you will be able to use the drivers with triple-buffering enabled on Intel and NVidia graphics cards , and then it will be nice to have a good looking, artifact free start screen.

  • Fix for NVidia graphics driver bug on all platforms, which caused output of many errors when using GL_TEXTURE_2D textures in some demos, e.g., BlurredMipMapDemo.


  • Fix pnet() data reception on 64-Bit Matlab. Certain parameters for data reception could cause it to crash due to a 64-Bit compatibility bug.

  • Fix ShowCursor() and HideCursor() on some MS-Windows setups. HideCursor() wasn’t hiding the cursor anymore on some setups for no conceivable reasons, whereas it worked flawlessly on others, without any change of code on our side.


  • Improved correctness tests and wokarounds for a graphics driver bug on Intel graphics cards under Linux. A bug was introduced into the Intel drivers released after July 2011, which slipped through (my) code review. This could cause too early stimulus onset, earlier than requested via the when parameter of Screen('Flip') - basically the parameter was ignored and flip always happened at start of the next video refresh cycle. Psychtoolbox automatic correctness tests didn’t test for this, so it slipped through ptb’s tests as well :-(. However, the problem was easily detectable by checking the timestamps returned by Screen('Flip'), or in the case of long interstimulus intervals or animations by visual inspection. Psychtoolbox now checks for this type of bugs as well, warns the user and switches to a fallback path to workaround the problem until a graphics driver update fixes the bug for good. A bugfix for the graphics driver has been submitted for inclusion into future Intel graphics driver releases.

  • Make Linux Screen() compatible to apitrace utility. apitrace is a tracer for OpenGL applications. Very useful for debugging bugs in OpenGL code. Calling setenv('PSYCH_ALLOW_APITRACE', '1') makes it possible to trace Psychtoolbox execution of OpenGL commands for debugging of hairy bugs in OpenGL code.

  • Bugfixes and enhancements to Screen('Resolution') on Linux. It could return stale information after a display resolution switch in some cases.


  • Bugfix for Screen(‘Resolutions’) on 64-Bit OSX. It crashed 64-Bit Matlab/Octave on OSX when called.

  • Catch errors during HID device enumeration and handle them more gracefully by output of a useful error message instead of crashing hard later. This to work around bugs in Apple’s 64-Bit HID Utilities framework (shoddy error handling), and potentially in some OSX HID drivers, e.g., for certain Wacom tablets. A specific tablet model could crash PsychHID by messing with device enumeration, as reported in Issue#62 on Psychtoolbox-3 at GitHub.

PTB beta “Broken Windows” release 2012-09-15


Psychtoolbox-3/Psychtoolbox-3@fde2c3f5 at GitHub

Most importantly this release adds 64-Bit Matlab support for MS-Windows and removes Octave support and Quicktime support for MS-Windows.

Release Highlights:


  • The runtime library requirements have changed: Now our mex files require the MSVC-2010 runtime libraries. Installers for these are contained in the Psychtoolbox/PsychContributed folders (vcredist.exe, vcredist_x64.exe).

  • The prehistoric PsychSerial() command has been removed. Use IOPort for serial i/o.

  • GNU/Octave support for MS-Windows completely removed. After over 3 years of availability on Windows, only about 117 of over 22000 MS-Windows users gave Octave a try - that’s only 0.5%, so i consider this a failure and declare defeat. If you want to continue using Octave 3.2.4 with Psychtoolbox on Windows, you must refrain from updating PTB 3.0.10 any further, or stick to PTB 3.0.9, otherwise the update will delete your Octave mex files. DownloadLegacyPsychtoolbox() always allows to downgrade to the unsupported v3.0.9 and then stick to that.

  • Apple Quicktime support for Windows finally completely removed. Now GStreamer is mandatory for multi-media functionality on Windows (Movie playback, movie creation, video capture, video recording). help GStreamer will tell you how to install it.

  • 64-Bit Matlab support for MS-Windows added. Limitations: At the moment, on 64-Bit Matlab, GStreamer must be installed for Screen() to work at all, even if you don’t use any multi-media functions. Eyelink() is unsupported with 64-Bit Matlab, as SR-Research doesn’t support 64-Bit Windows yet afaict. Datapixx support is missing, but will probably get added soon.

  • A new PsychTweak() command allows to control some parameters on how clocks are handled on MS-Windows. This allows to change the way broken clock hardware on MS-Windows is detected and handled. The defaults have been changed to be a bit more lenient to tolerate some brokeness in the latest processors on Windows.


  • 32-Bit Octave support on OSX removed, 64-Bit Octave 3.6 support added. Should work with Octave installed via the “HomeBrew” package manager.

  • Optional GStreamer support for 32-Bit Matlab on OSX added. Now you can use it on 10.6 Snow Leopard and later. Apple Quicktime is still the default on 32-Bit Matlab for OSX, the Screen('Preference') switches allow you to use GStreamer instead.

  • The PsychtoolboxKernelDriver on OSX now supports Intel integrated graphics cards as well.

I consider the 32-Bit PTB for OSX now on “live support”. I have one machine left for maintaining it. As long as that machine keeps working and is not getting upgraded to 64-Bit, i’ll keep the 32-Bit PTB for OSX alive.


  • Windowed window support and GUI window support now shows same level of functionality and behaviour as on OSX, e.g., PsychDebugWindowConfiguration is now fully useable.

All systems:

  • Movie playback performance and functionality improvements for GStreamer based movie playback engine. Some perf. improvements for videocapture engine, and basic GeniCam/GigE video capture support. The default behaviour and performance is the same, but some optional switches now allow to enable multi-threaded video decoding for some codecs, e.g., H264 and use of optimized texture upload methods for some movie formats. This can speed up playback of high framerate and high resolution videos considerably on high end machines with many cores and modern gpus. PlayMoviesDemo() has some new optional parameters pixelFormat and maxThreads which allow to enable these optimizations, e.g., on H264 video. E.g., a pixelFormat = 6 and maxThreads = 0 will use as many processor cores as available for video decoding. On Linux and OSX this can provide over six-fold speedup, on Windows the multi-threading seems to be mostly ineffective at the moment, probably due to some codec bugs on Windows.

  • Support for GL_TEXTURE_2D textures as render targets (e.g., Offscreen windows and use with TransformTexture) – For improved OpenGL interop with 3rd party OpenGL code like Horde3D. Non-power-of-two texture support. Mipmap filtering support and demos for efficient blurring via gpu accelerated resolution pyramids. The new BlurredMipmapDemo employs/demonstrates OpenGL mip-map filtering to use image resolution pyramids for fast blurring of images, e.g., for certain types of gaze contingent displays.

  • MOGL OpenGL support updated to support most new OpenGL-2.1 extensions up to the ones added in August 2012.

  • Various other improvements, cleanups and bug fixes i can’t remember.

PTB beta “Rotten Apples” release 2012-06-01 (Start of Psychtoolbox 3.0.10)


Psychtoolbox-3/Psychtoolbox-3@92809a33 at GitHub

“Rotten Apples” starts the new Psychtoolbox Version 3.0.10 series.

The almost only new feature in this release is support for 64-Bit Matlab under Apple MacOSX.

Minimum system requirements for OSX/Apple:

  • An Intel based Apple Macintosh computer.
  • For 32-Bit OSX PTB: OSX 10.4.11 “Tiger” and later are still supported.
  • For 64-Bit OSX PTB: Absolute minimum is OSX 10.5.8 “Leopard”, with functionality and performance restrictions.
  • For 64-Bit OSX PTB: OSX 10.6 “Snow Leopard” and later should support all functionality without restrictions.

Basic 64 Bit compatibility testing happened on 10.5.8 with Matlab R2010b-SP1, 10.6.8 with R2012a and 10.7.4 with R2012a. Future testing will happen on 10.7.x Lion with R2012a, with very infrequent basic testing on 10.5.8 Leopard with R2010b.

Support for using PTB on OSX on Apple PowerPC computers has been removed. If you want to keep your old PowerPC useable with PTB you’ll need to stick to the deprecated and unsupported V 3.0.9 PTB.

On Microsoft Windows, support for Matlab versions older than V7.4 - R2007a has been completely removed. Windows-2000 and earlier is no longer tested for compatibility with PTB.

On other systems, support for Matlab older than 7.4 - R2007a is no longer guaranteed. The mex files would still work, but we will no longer keep M-Files compatible with older Matlab versions.

If you want to use old Matlab versions, stick to the old V3.0.9 PTB, but realize that this version is no longer supported by us in any way.

You won’t be able to upgrade to 3.0.10 via UpdatePsychtoolbox. Instead you will need to download a complete fresh copy of PTB via DownloadPsychtoolbox. The updater will provide you with further instructions after a call to UpdatePsychtoolbox. Alternatively you can download a fresh DownloadPsychtoolbox script from our Wiki. A new installer script DownloadLegacyPsychtoolbox allows to downgrade to - or stick with - older PTB’s of Version 3.0.9 or earlier if you want to run on ancient hardware or Matlab versions.

PTB revision numbers, as reported by the PsychtoolboxVersion() command for an old PTB installation have no meaning once you’ve upgraded to V 3.0.10, ie., the mapping of numbers to actual code has changed. This means that the SVN revision number no longer uniquely defines the software you have installed. Instead the combination of version number, e.g., 3.0.10 and revision number does. The reason for this is that we moved our code hosting for the new 3.0.10 series from GoogleCode to GitHub, and our underlying version control system from Subversion to Git.

Psychtoolbox on 64-Bit OSX now requires the free and open-source GStreamer framework for movie playback, movie writing, video capture and video recording - “help GStreamer” for installation instructions. The 32-Bit PTB on OSX will continue to use Apple Quicktime as a default for a limited amount of time - until we have GStreamer support for it as well, after which Quicktime will become optional, with GStreamer as default. I consider Quicktime in maintenance mode from now on. Only critical bugs regarding it will be fixed, but no future enhancements or new features for it are planned

Psychtoolbox on Windows will switch to GStreamer as default with one of the next beta releases, Quicktime will be made optional or possibly completely removed on Windows if maintaining it turns out to be too much work.

Other changes in this beta release:

  • Some improvements to color and gamma calibration code by David Brainard.

  • The 64-Bit Psychtoolbox on OSX now also enables floating point textures and frame buffers for high color precision stimulus display and GPU computing on the latest generations of Intel graphics hardware, ie., the Intel HD 3000 integrated GPU’s found in recent MacBooks, MacBookPro and MacBook Air. Hardware functionality of these GPUs seems to have improved enough in the latest hardware generations to make them viable for more demanding tasks. Some of our software tests show good precision, comparable to discrete state of the art AMD or NVidia GPU’s, whereas some other tests still show some deficits, and no hardware testing with photometers etc. has been performed to see how well these gpu’s work for high precision stimuli beyond the frame buffer - ie. if the new goodness actually reaches the display correctly.

Intel HD graphics series support will be added for other operating systems and 32-Bit configurations in a future ptb release.

Much deserved credits for the OSX 64-Bit port go to:

Thanks to Prof. Heinrich Buelthoff at the Max Planck Institute for Biological Cybernetics in Tuebingen, Germany, for supporting the work on the 64-Bit port - and most other significant improvements to PTB throughout the last six years, by letting me spend some of my work time on this time intense “hobby”.

Thanks to Prof. Keith Schneider at the University of York, Canada, for donating an almost new Apple MacBookPro, thereby allowing to work on a 64-Bit OSX port in a much more pain free manner.

Thanks to Ian Andolina from UCL London for help in initial testing of the 64-Bit port.

Thanks to Linus Torvalds for inventing the wonderful Git version control system and to GitHub for our free Git hosting. Git is a wonderful tool for preventing nervous breakdowns and reducing crying fits and rage against the machine during software development.

Absolutely no thanks to various unknown people working at Apple and Mathworks for reasons too many and too horrifying to mention.

PTB beta release 2012-5-21 (SVN Revision 2580/2591)


For more details, please review the detailed change log.

This beta, nick-named “Conradine”, marks the last official Psychtoolbox release in the Version 3.0.9 series. We may or may not fix critical bugs after this release, but most likely we won’t.

This is the last release to support MacOSX on Apple PowerPC hardware, the last one to support MS-Windows 2000, and the last to support Matlab versions older than V7.4 aka R2007a

All systems:

  • PsychPortAudio: Fix sound output with dithering enabled on current 64-Bit Linux and all other future 64-Bit platforms. There was a bug in the underlying PortAudio library which caused strong white noise with dithering enabled on a 64-Bit runtime. In low latency / high timing precision output mode, dithering is disabled by default, so most demos and scripts weren’t affected. BasicSoundOutputDemo however worked in “normal mode” with dithering on by default, so the actual sound output was drowned in strong static white noise.

  • Eyelink: Fix EyelinkFixationWindow function for use with Matlab R2012a, which is case sensitive and treats wrong case in function names as errors, instead of warnings.

  • PsychHID: Add keyboard event ring buffer support. Once a keyboard queue for a specific keyboard(-like) device (mouse buttons on a mouse, joystick/gamepad buttons, etc. are treated as “mini keyboards”) has been created and started via KbQueueCreate and KbQueueStart all events (button press and release) are not only recorded between invocations of KbQueueCheck, but they are now additionally recorded in a ring buffer that can hold up to 10000 press- and release events. The buffer sequentially records all events, including a timestamp and potential additional data. The buffer can be emptied (“flushed”), checked and read out with the new functions KbEventFlush(), KbEventAvail() and KbEventGet() independent of the old KbQueueXXX functions. This should allow more convenient access to recorded subject responses, scanner triggers etc. without the need to constantly poll for key state via KbCheck, GetMouse, GamePad etc. Each queue and thereby each individual keyboard has its own buffer (although you can only address one keyboard or mouse on windows due to operating system limitations, and only have one keyboard queue on OSX due to limitations of our current PsychHID driver, so multiple queues for multiple devices is only really useful on Linux). KbQueueDemo demonstrates how to use keyboard event buffers.

  • moglmorpher: Add more strict parameter checking to subfunction moglmorpher('AddMesh') to catch some coding errors in user scripts instead of aborting with puzzling error messages.

  • Screen: Allow to disable sound decoding of Quicktime movies during playback on Windows and OSX, to match behavior on Linux and Windows when used with the GStreamer playback engine. Precisely: Sound decoding is not really disabled, as Quicktime does not allow that. Instead sound output is just muted. This way scripts behave in a compatible and consistent way, irrespective of playback engine, but users of Quicktime won’t get the benefits of reduced processor load and sound resource utilization.

  • Various performance improvements in the mex files and small bug fixes.

  • Various improvements to color correction and gamma correction routines by David Brainard.


  • Screen: Update low-level GPU detection support to work with the latest year 2012 AMD GPU’s, ie., the “Southern Islands” and “Trinity” GPU families, better known by their marketing names “Radeon HD 7000” and “AMD Fusion”. This allows our special bag of neat low-level tricks on Linux to also work with these new models of graphics hardware and expose some special features not found on other systems.

  • PsychHID: Fix default keyboard selection on Linux on some Laptops, which report the VideoBus as a keyboard. If no specific keyboard device index is given to any of the keyboard functions, PsychHID uses a heuristic to try to select the “default keyboard” as a reasonable choice. As there isn’t any real “default keyboard” on any operating system, the heuristic is a “best effort” approach which can go wrong on exotic hardware setups. On Linux, some Laptops expose some control buttons related to graphics hardware as a “one button keyboard” and the heuristic sometimes chose those buttons as default keyboard - clearly not what one would expect. Now the heuristic skips those button devices labeled as VideoBus. PsychHID on Linux selects the default device by name pattern matching, selecting the first device whose name string sounds like a real keyboard instead of something exotic. PsychHID on MacOSX selects the first HID device labelled as “HID Usage value keyboard class”, so the order in which keyboards get plugged into the computer - or detected at boot up, or the location where they get connected - determines which is the default keyboard. On Windows, PsychHID can’t discriminate keyboards due to operating system limitations, therefore it can’t choose the “wrong one” ;-)

PTB beta release 2012-4-1 (SVN Revision 2540)


For more details, please review the detailed change log.

All systems:

  • PsychPortAudio: Potential startup latency reduction on all systems as now runlevel 1 is used by default. This potentially reduces start latency for sound playback at the expense of slightly higher cpu load while playback is stopped.

  • Performance improvement to Screen('MakeTexture') via new optional specialflag 4 – Much faster for all uint8 input textures and for Luminance + Alpha and RGB8 textures as created from double() input matrices. However, mode 4 requires a GPU with shader support and may not work well with scrolling/drifting textures or on a few other special cases. It is best used for fast creation of still images.

  • Code cleanup here and there.

  • Some tiny fixes for Octave 3.6 compatibility of M-Files.

  • DaqAInScanContinue now can return “live data”. (Untested).

  • KbCheck, KbQueueCheck, KbTriggerWait et al. now support handling of mouse, joystick, gamepad and similar devices as mini keyboards: Their buttons can be treated as keys on a keyboard and queried by the KbXXX functions. This allows simplified (ab)use as response button devices.

  • Support for procedural visual noise on modern GPUs - Perlin noise for fast visual noise generation on supported gpus. Use with caution: Perlin noise is not Gaussian noise!

  • Small improvements to QuestSimulate: Can now visualize its operation.

  • Datapixx mex files updated by VPixx to support the ViewPixx device, e.g., backlight control.

  • CMUBox now handles Cedrus Lumina response boxes (Untested).

  • Various other small improvements and some new demos.

Windows & Linux:

  • GStreamer movie playback engine enhanced with many bug fixes, improved features, some new functionality, performance improvements.

OSX & Linux:

  • Improved realtime scheduling setup for increased robustness of timing when many threads are active or system is loaded. OS/X now uses Mach realtime scheduling everywhere, not only on master thread. Linux has refined priority level setup and uses mutexes with priority inheritance.


  • Screen(‘DrawText’) now obeys geometric transformations, e.g., in DrawMirroredTextDemo.

  • PsychHID HID device enumeration improved due to upgrade to latest HIDAPI.

PTB beta release 2012-2-8 (SVN Revision 2450)


For details, please review the detailed change log.


Screen() now supports frame-sequential stereo presentation on graphics card / graphics driver / operating system combos which don’t provide native OpenGL quad-buffered frame-sequential stereo support. In stereomode 1 it detects if native support is available and uses it if possible. Otherwise its own built-in implementation is used. Stereomode 11 always uses the built-in implementation.

Tested and shown to work reasonably well on WinXP, OS/X, Linux with sufficiently fast gpu & cpu under light load. Robustness of this built-in method is highly dependent on speed and timing behaviour of the underlying os and computer / gpu hardware. A native implementation (e.g., NVidia QuadroFX or AMD Fire gpu’s) is preferrable if available, but this should be good enough for not too demanding casual stereo presentation.

Bugfixes / Tweaks:

  • Fix to PsychtoolboxPostInstallRoutine by Diederick.

  • DrawFormattedText now allows wrapping of Unicode text as well.

  • Screen/Linux: Allow floating slave input devices for use with GetMouse().

  • Screen/Linux: Robustness improvement to OML timestamping for nouveau.

  • Screen: Some documentation fixes.

  • Screen/Linux: Don’t link directly against libraw1394, only indirectly through libdc1394 if libdc1394 needs libraw1394. May or may not help with broken Matlab installations on Linux.

  • PsychHID for Windows and Linux: Bugfixes to ‘GetReport’ et al. Does no longer enqueue empty hid reports – no buffer overflow anymore. Small fixes to error handling.

  • Fix documentation of Quest: Formula in help text was inconsistent with formula in actual implementation.

  • Various other small documentation fixes.

PTB beta release 2012-1-12 (SVN Revision 2434)


For details, please review the detailed change log.

Improvements to Microsoft Kinect driver for all platforms:

  • Can now handle multiple Kinects simultaneously (untested).

  • PsychKinectCore(‘GetDepthImage’) now allows return of unprocessed raw sensor data in uint16 format, for fast disc writeout. Demonstrated in very sketchy KinectRawRecordingDemo.m.

PTB beta release 2012-1-7 (SVN Revision 2423)


For details, please review the detailed change log.

All systems:

  • Bugfixes.

  • Screen(‘AsyncFlipXXX’) functions greatly improved. Now much more convenient and child-proof to use. Now allow use of almost all Screen() drawing functions in parallel to a pending async-flip – for enhanced parallelism. New implemenation can be disabled via a ‘ConserveVRAM’ preference setting. Associated tests AsyncFlipTest, MultiWindowLockStepTest demonstrate usage and performance.

  • Screen GPU rendertime measurements improved. Now more flexible (Screen(‘GetWindowInfo’, …) infotypes 5 and 6) Can start/stop/start… measurement multiple times per frame for fine-grained benchmarking.

  • Handling of window geometry in stereo modes and special display modes, e.g., Bits+/DataPixx Color++/C48 mode improved.

  • Screen now enables fast offscreen window support by default on GPUs which support it –> More efficient, flexible, robust Offscreen window support. So far this was an opt-in, now it is an opt-out via a new ‘ConserveVRAM’ setting.

  • Some improvements to video capture engine.

  • moglmorpher() can now dynamically delete meshes as well, not only add new ones.

  • PsychRTBox driver now should work with latest RTBox models & firmware, although untested.

  • Some demos refined.


A new workaround for OS/X 10.7 Lions broken vblank irq timestamping is in place. We fall back to CoreVideo display link timestamping. This doesn’t work well at all on 10.4 Tiger, which is why it gets only enabled on 10.7+ systems. All older systems use our proven and robust vblank irq timestamping. Or the even more robust and precise beamposition timestamping if it is supported by the OS or by use of the PsychtoolboxKernelDriver.


  • IOPort / PsychRTBox / CMUBox response button box drivers can now auto-enable low-latency mode on FTDI usb-serial ports, no need for user setup anymore.

  • Random improvements, also in documentation.

  • Most important: As part of an improved installer, the new function PsychLinuxSetup now configures the system (pending the users permission) for root-less operation: Psychtoolbox can use realtime-scheduling, beamposition timestamping, special GPU features, various optimizations, and access to special research hardware, e.g., the products from CRS and VPixx without the need to run Matlab or Octave as root user via “sudo”. This should remove quite a bit of headaches and increase system security considerably.

PTB beta release 2011-12-7 (SVN Revision 2386)


For details, please review the detailed change log.

The only changes in this release are performance improvements for GStreamer movie playback functionality under Linux. We now detect if the video decoder is multi-threading capable and enable multi-threaded decoding, if so. This provides some speedup, e.g., with the multi-threaded H264 decoder of the latest GStreamer versions, e.g., shipping with Ubuntu Linux 11.10. Some bits of additional performance benchmarking code for video playback was added as well.

This is mostly useful for playback of high resolution HD video (1920 x 1080p HD) at unusually high framerates (e.g., 60 fps) on powerful multi-core machines, e.g., 4 - 8 core high-end systems. Users of dual-core systems will probably not notice any difference, as the old Psychtoolbox was already able to saturate two processor cores. Also, for more usual resolutions or framerates, there probably won’t be a big benefit.

With this release, the Linux Psychtoolbox will probably significantly outperform both the OS/X and Windows Psychtoolbox for demanding video playback applications.

PTB beta release 2011-11-29 (SVN Revision 2381)


For details, please review the detailed change log.

No new features in this release, just a host of bug fixes, compatibility fixes and workarounds for broken operating systems, device drivers and other hardware.

Misc fixes:

  • PsychHID: Compatibility and performance fixes of Linux/Windows version with OS/X version. Now should hopefully behave identically and support HID Set/GetReport properly.

  • PsychRTBox: Compatibility fixes with latest boxes and firmware.

  • PsychDataPixx: Handle GPUs which have gamma tables with more than 256 slots, e.g., NVidia QuadroFX-3800 on Linux.

  • DowloadAdditionsForNeuroDebian: On Octave + Linux, also download DataPixx driver.

  • LoadIdentityClut: Handle NVidia GPUs with more than 256 gamma table slots, e.g., pro GPUs on Linux.

Screen on Linux:

  • Fix multi-display detection and setup for ZaphodHead multi-display on multi-x-screen configurations. Make a reasonable assignment of RandR crtcs and physical GPU crtcs

  • Fix tiny bugs in new RandR multi-display setup code.

  • RandR compatibility fixes for NVidia GPUs with binary blob driver: The proprietary NVidia driver lies to us: It claims full RandR V1.2 support, but only supports a subset of functions. E.g., it fails miserably with video modeline queries and get/set gamma tables. Add detection code to detect this and use a good’ol XF86VideoModeExtensions fallback.

  • Handle GPUs with gamma tables with more than 256 slots correctly. NVidia pro class GPUs, e.g., QuadroFX-3800 have 2048 slots, god knows why. Anyway…

Screen on MacOS/X

Try to work around broken VBL-IRQ mechanism on OS/X 10.7 Lion. Test by users pending. Either this fixes it, or it is “game over” for VBL-IRQ timestamping on Apple hardware.

PTB beta release 2011-11-6 (SVN Revision 2357)


For details, please review the detailed change log.

With this beta update, we changed our hosting service for Psychtoolbox from Berlios which is operated by the FOKUS institute of the german Fraunhofer society to GoogleCode, operated by Google. This migration was done because Berlios was about to shut down its operations by the end of the year 2011 due to lack of funding. Now it seems that at least Berlios basic services will be able to continue, maintained and funded by a volunteer driven non-profit organization created for the purpose of rescuing this great institution. Unfortunately these news came too late for us.

Migration of existing Psychtoolbox installations from Berlios to Google should happen automatically and mostly transparent for users during regular Psychtoolbox updates and downloads.

Good bye Berlios, and thank you for five years of great service!

Misc improvements, bug fixes, and new functions:

  • Some function and unit test updates by Diederick.
  • Improve SensorToSettings by David.

PTB beta release 2011-10-20 (SVN Revision 2337)


For details, please review the detailed change log.

Release highlights:

Misc improvements, bug fixes, and new functions:

  • New function DownloadAdditionsForNeuroDebian allows to fetch and install MEX files for Matlab on Linux on top of an existing octave-psychtoolbox3 installation from NeuroDebian This as a stop-gap measure until NeuroDebian provides support for Matlab in addition to support for Octave. Also can fetch some additional Octave mex files which can’t be distributed by NeuroDebian due to license incompatibilities, e.g., Eyelink().

  • Make Windows PTB even more robust against broken computer clocks under MS-Windows.

  • The PortAudio driver plugin DLL for Windows with compiled in ASIO backend support is now included in Psychtoolbox by default. This spares users the need to download and install the file separately from our Wiki. Possible due to our license change from GPLv2 to “mostly MIT”.

  • Fix numeric keypad mapping on Windows with PsychHID.

  • KbName now maps basically all keys on all operating systems.

  • Compatibility fixes for PsychRTBox, so it works without statistics toolbox of Matlab.

  • Compatibility fixes for Matlab R2011b

  • Improved unit tests, staircase procedures and other useful helper functions by Diederick Niehorster.

  • Improved color calibration/handling routines by David Brainard.

  • New function KbKeysAction - User contribution.

  • Various bug fixes, some performance improvements.


  • Sphereprojection shader improved for display undistortion on spherical display surfaces via image processing pipeline -> User contribution.

  • Bugfixes for text drawing in stereomodes 4,5 (Dual display / desktop spanning) on Linux and OS/X

  • Support for 16 bit signed normalized framebuffers and textures as fallback for systems which don’t have 16 bpc float support. Allows 15 bit precision for framebuffers on such systems.

  • Fix ShowCursor() / HideCursor() for Ubuntu Linux 11.10 and later.

  • OS/X Some new workarounds for Apple’s broken operating system.

  • OS/X: Screen('ConfigureDisplay', 'Brightness', ...) allows to query/set brightness of attached displays. In theory. In practice most displays don’t support this, or OS/X support is buggy to the point of being unuseable.

  • Linux: Supports now completely asynchronous flip timestamp queries and logging via use of the INTEL_swap_events extension with the FOSS graphics stack.

Linux: Large number of improvements by use of XRandR extension:

  • Multi display handling, multi display resync, multi-display timestamping and multi-display swapping improved. Various other bonus features which are not possible on other operating systems.

  • 10 Bit native framebuffer improvements on ATI FireGL series GPU’s. Allows to workaround broken proprietary ATI Catalyst drivers and enable the 10 bit framebuffers on CRT monitors.

  • Screen('ConfigureDisplay') allows fine grained low-level control over video mode, scanout viewport and other properties of video outputs. Screen(‘Resolution’), Screen(‘Resolutions’) fully implemented.

PTB beta release 2011-08-24 (SVN Revision 2193)


A summary of major improvements, features, bug fixes. For details, please review the detailed change log.

PsychHID support for Linux and Windows

  • KbQueueXXX support for both systems. Linux allows multiple keyboard queues, one for each individually adressable keyboard. Windows only allows one queue for the system keyboard. In theory it allows also multiple queues, but for that it would need to enumerate separate keyboards separately. However, Microsoft has removed this function in their DirectInput implementation for Windows-XP and later. Thanks Microsoft!

  • KbCheck support for individual keyboards on Linux.

  • GetMouse/SetMouse/ShowCursor/HideCursor support for multiple independent mice/pointers on Linux.

  • Touchpad, touch tablet, digitizer tablet, gamepad, joystick support on Linux. Tested with some usb joystick and a Wacom CintiQ tablet.

  • USB low-level control support (control transfers) for Linux and Windows. Tested with ColorCal2 driver for Linux, but not tested at all on Windows.

  • USB-HID device enumeration and control (HID transfers a la Set/GetReport) for HID devices. This should make the DAQ toolbox work cross-platform but DAQ toolbox is untested due to lack of hardware.


Some fixes for text renderer and text renderer plugin, and small improvements.


OpenAL 3D sound support now also implemented for Linux.


  • Improvements to fitting routines etc. in PsychColorimetric folder by David Brainard.

  • Fixes and improvements and some staircase functions by Diederick Niehorster.

  • Other smallish bits and bytes.

PTB beta released 4.9.2010 (SVN Revision 1783)


This summarizes all new beta features from 6.6.2010 up to 4.9.2010. The list of improvements is likely incomplete as always. For detailed logs, click this link.

This update contains a couple of bug fixes and minor improvements. Most interesting should be the improvements to the Eyelink toolbox by Frans Cornelissen.

  • Improvements and cleanup to many demos by Frans Cornelissen. Frans also enabled the video feed from the Eyelink eye camera during tracker calibration by default, so the subjects eye can be monitored during calibration procedures. The PsychHardware/EyelinkToolbox/ folder contains a file “compatibility” (help compatibility) with information on what has changed in this release of the Eyelink toolbox and how to restore the old behaviour if you don’t like the eye camera video feed to be displayed.

PsychPortAudio sound driver

  • Bugfix when used with Microsoft Windows Vista or Windows-7 on fast multi-core machines (e.g., has only been observed on a 8 core, 2.7 Ghz PC running Windows-7): Under certain circumstances the driver may falsely report your computers clock to be broken (“Time going backwards” warning) and switch to a low resolution backup clock. This is now fixed. The same fix applies to Screen and IOPort, although it was very unlikely to encounter the bug when using those mex files.

Improvements and bug fixes to Screen and other drawing functions – The Visuals

  • Updates to help texts for some functions.
  • The PsychtoolboxKernelDriver for OS/X on IntelMacs with ATI GPU’s has been refined (help PsychtoolboxKernelDriver). Now provides even more precise visual onset timestamping and removes a constant 0.4 - 0.7 msecs (depending on videomode) bias in the timestamps. Datapixx measurement confirms our timestamps are now spot-on on the two tested ATI GPU’s, a Mobility Radeon X1600 and a FireGL-V3700
  • Improvements to procedural gabor- and sinegrating rendering. Allow to specify a global contrast scaling factor as proposed by Xiangrui Li.
  • CreateProceduralSineGrating(): Add optional support for drawing procedural sine gratings with a circular aperture of selectable radius.
  • PsychImaging: Add new stereo mode 'InterleavedColumnStereo' for column interleaved stereo displays, e.g., for driving auto stereoscopic displays based on lenticular sheet lenses or parallax barriers. ImagingStereoDemo(101) demonstrates this.

Misc stuff

  • Some improvements to display calibration, gamma correction and color handling routines by David Brainard’s lab. Also improvements to the PR-650 photometer support.
  • Some improvements to general toolbox routines by Diederick Niehorster.
  • BalanceFactors: Speed optimization by David Fencsik. BalanceTrials() - New function for balancing a set of factors, contributed by David Fencsik.


PTB beta released 6.6.2010 (SVN Revision 1737)


This summarizes all new beta features from 11.1.2010 up to 6.6.2010. The list of improvements is likely incomplete as always. For detailed logs, click this link.

Some users of Microsoft Windows may encounter an error during update or download of the toolbox. On failure, the installer will give you instructions on how to download and install updated copies of the Microsoft Visual C runtime libraries to make Psychtoolbox work again. This is a required upgrade, forced by some changes in Microsofts OS.

These updates introduce various bug fixes and enhancements. Especially the Screen and PsychPortAudio and Datapixx drivers as well as the image processing pipeline and many demos and drawing functions have been improved again.

PsychPortAudio sound driver

  • Bugfix for audio artifacts due to “wraparound errors” in the Portaudio sample converters. Could cause audio artifacts if sound samples reached the (legal) signal level 1.0 and the soundcard expected audio data converted to 24 bit integer or 32 bit integer format. This mostly affected some ASIO soundcards on Windows.
  • Perform clamping of audio output signals to valid -1.0 to +1.0 range in all modes by default, instead of only in non-low-latency mode as in previous versions of the driver. Allow to change defaults for dithering and clamping in the ‘Open’ function.
  • On Windows with some ASIO soundcards and on Mac OS with some external soundcards, direct input monitoring is supported. This requires hardware support by the soundcard and allows to feed back sound from the soundcards inputs (microphone etc.) to its outputs with minimal latency. Most soundcards don’t support this feature, so you’ll need to use PsychPortAudio's software implementation which has a slightly higher latency.
  • Improved support for sound schedules: Now allows to specify and schedule onset/offset/pauses of sounds wrt. to the system clock, i.e., in the same timebase as GetSecs and all other timestamps in Psychtoolbox.
  • Support for virtual audio devices and mixing: Allows to open a physical soundcard as a master device, then create multiple “slave devices” which attach to different channels of the master device. Output of multiple slave devices is combined/merged/mixed and send to the master device. This allows to play back multiple independent soundtracks simultaneously and with independent control of content, timing and volume. Also allows to address each channel or set of channels on a card separately. New function PsychPortAudio('OpenSlave') controls this functionality.
  • Support for capturing and recording the mixed output stream as it gets sent to the real soundcard, e.g., for feedback, testing, debugging and documentation purpose.
  • Support for per device and per channel gain and volume control via the new ‘Volume’ function.
  • Support for precisely timed amplitude modulation (AM) of each virtual audio output slave device by definition of time series of gain values which can be applied with sample-accurate timing. Cfe. BasicAMAndMixScheduleDemo for demo of AM modulation, volume control, mixing and scheduling support.
  • Option to resume playback in a ‘Start’ call where it was last ’Stop’ped, instead of restarting at the beginning.

Serial port hardware support

  • Some performance improvements to IOPort and some parameters to allow to workaround operating system / serial port driver bugs on some setups.
  • CMUBox driver for serialport or USB response boxes now supports also the fORP device when connected via a serial port and to use the UBW32/Bitwhacker as a response button box.

Improvements and bug fixes to Screen and other drawing functions – The Visuals

  • Further improvements to high precision visual stimulus onset timing and timestamping. Also added new tests and workarounds for various broken graphics drivers on Windows and Mac OS.
  • Experimental support for OpenML based visual stimulus onset scheduling and timestamping for GNU/Linux. This is an opt-in, work in progress. Not yet ready for mainstream use, but will allow to take advantage of Linux special facilities, once they are completed and stable.
  • Support for NV_swap_group and SGIXX_swap_group extensions on Linux and Windows. Some professional grade graphics cards, e.g., some AMD FireGL/FirePro cards and some cards do support these extensions in hardware. These allow to perfectly synchronize bufferswaps and visual stimulus timing across multiple windows, displays, graphics cards or even different nodes on visualization clusters. Screen will automatically use these extensions if they are present and a dual-display stereo mode or other dual display / multi window mode is used.
  • Support for creation and writing of Quicktime movie files on Mac OS and Windows. Allows to create and write movie files. Currently only supports one video track per movie and doesn’t support soundtrack. Works with any codec supported by Quicktime. ImagingStereoDemo contains test- and example code to demonstrate usage. Can create a movie which records the animated stereo display.
  • Various bugfixes and help text updates.
  • The imaging pipeline PsychImaging in conjunction with PsychColorCorrection now also allows to apply automatic display vignetting correction aka shading correction to automatically compensate for spatially varying differences in luminance or per color gains of display devices, e.g., due to lense vignetting on projectors. VignetCalibration implements an interactive calibration procedure, VignettingCorrectionDemo and AdditiveBlendingForLinearSuperpositionTutorial demonstrate how a calibration is applied for realtime vignetting correction.
  • ScreenDrawDots is a reimplementation for the Screen('DrawDots') function to allow smooth dot drawing on broken Mac OS 10.6.3 systems.
  • PsychDrawSprites2D allow for drawing of large numbers of similar textures, so called Sprites. It behaves exactly like Screen('DrawDots'), except that it doesn’t draw dots, but little copies of a given texture, with selectable size, position, rotation and color. This is demonstrated in DotDemo by passing an optional flag.
  • A new Sadowski-Illusion demo.
  • Full support for the VPixx technologies DataPixx device on all platforms, except Apple PowerPC and Windows with Matlab versions before V7.4 (R2007a). All special graphics display functions (stereo, multi-display, mirroring, high precision color and luminance display) are supported via PsychImaging, e.g., demonstrated in BitsPlusCSFDemo, AdditiveBlendingForLinearSuperpositionTutorial and ImagingStereoDemo. Timestamping functionality and other convenience functions, as well as audio capture and voice keys are available via PsychDataPixx and DatapixxAudioKey, PsychPortAudioDatapixxTimingTest. See help DatapixxToolbox. All low-level features are supported via theDatapixx mex file driver.
  • OpenGL for Matlab and Octave: Add support for GLU tesselator functions.
  • New DotRotDemo for rotating dot fields by Keith Schneider.

Misc stuff

  • Many new and improved display calibration, gamma correction and color handling routines by David Brainard’s lab.
  • Some improvements to general toolbox routines by Diederick Niehorster.
  • Support for later models of the RTBox response button box in the PsychRTBox driver.
  • Bugfixes and workarounds for the latest collection of bugs in Mac OS/X Snow Leopard 10.6.3 and MS-Windows.
  • Compatibility fixes to mex files to provide good support for Ubuntu Linux 10.04 LTS “Lucid Lynx”.


PTB beta “Arrested Development” released 11.01.2010, Mario takes a break from development


Mario takes a break

The first PTB beta update for 2010, codename “Arrested Development” has been released 1 week ago. “Arrested Development” is not only the name of a medical condition, a hip-hop band and a tv series, but also the only item on my todo-list for Psychtoolbox throughout the next few months. I have to get the writeup of my thesis finished and time spent on PTB development & support is a major obstacle to this goal, although a pleasurable one.

I will continue to monitor the forum for serious problem reports but only respond to really urgent and important requests, if you make it really simple for me to help you by preparing your specific questions carefully according to the guidelines we have at the start page of the forum and on our Wiki. In short: “Careless emails do not invite careful responses.” – Other users are of course welcome to help their troubled colleagues.

A good way to help yourself is to look at the various demo scripts in the PsychDemos folder if you need help on how to implement certain things or get examples for coding, to use google to search the forum for previous answers for similar questions, to search the Wiki for information, to actually read and follow the instructions for beginners that our installers print after each single installation and update. It also helps to actually read error messages and warnings and follow the pointers to troubleshooting instructions that they quite often contain, instead of simply copy & pasting them to the forum – Although copying the output is still better than simply writing “It doesn’t work” in the most fuzzy way possible.

I’m not interested in discussing feature requests for the next months, we have a page on our Wiki where you can write those down, together with a contact address, and i’ll likely come back to you, once i have time to pick up development again. You are still welcome to submit improved code or new functionality to me or the other developers for inclusion into the toolbox, as long as you’re doing most of the work and not me.

I’m also not interested in bug reports for trivial bugs or pure annoyances. If it is trivial enough for you to fix it yourself, fix it and send me the updated files. If it is non-trivial for you to fix, write a bug report and add it to our bug reporting system, or to the proper section of our Wiki.

Reports for really serious bugs will still catch my attention if they are well written and i will do beta updates to fix such bugs should this become neccessary.

Thanks for your sympathy.

New features in “Arrested Development”:

These are the new features and improvements of the latest beta. I’ll post more details when i have time.

  • Good support for international character set handling, Unicode and Multibyte/UTF-8 text encoding and other non-ASCII scripts on all operating system platforms. Read help DrawTextEncodingLocaleSettings for further details, as well as the updated help of Screen TextBounds? and Screen DrawText?

  • High-Quality text rendering support with anti-aliasing and Unicode drawing on GNU/Linux via use of dynamically loaded FTGL text rendering plugin. Should work out of the box. For interesting options and troubleshooting if it doesn’t, read help DrawTextPlugin.

  • Support for control of power-management and dithering of modern ATI GPU’s via PsychGPUControl() + proper helper binary executables for Windows and Linux. This will require further explanations, stay tuned…

  • Workarounds in IOPort for broken USB serial drivers as reported by Xiangrui Li, see message 10537.

  • Improvements to PsychRTBox driver to expose new functionality in the latest generation of the RTBox response time box.

  • DaqDIn may be able to read from USB 1024-LS now, as requested by Thomas G. Fikes, see message 10484.

  • Improvements in visual stimulus onset scheduling, realtime scheduling and high-precision visual stimulus onset timestamping on all platforms as result of the extensive benchmarking and tuning efforts on all supported platforms. This will need further explanation in the future. If you want to take advantage of it and get best possible stimulus onset timing, make proper use of the ‘when’ parameter of Screen('Flip') and the returned timestamps, as explained in the Intro-PDF and demonstrated in a few of our demos.

  • Kbcheck, KbWait, KbQueueXXX et al. functions on MacOS/X can now also handle keypads, not only keyboards. Read their help texts for explanation. This code contributed by Roger Woods. Thanks!

  • Initial support for the VPixx Technologies "DataPixx data acquisition and graphics system for the vision sciences”. This is the first iteration, so far only on OS/X on Intel Macs under GNU/Octave is supported. This is work in progress. The basic infrastructure for good integration into PTB is implemented, tested and shown to work very well. As most of the remaining development work will be done by VPixx, e.g., support for all other operating system platforms and Matlab, i’ll probably do some beta release with an update, once all other platforms are ready. See help PsychImaging and search for Datapixx for supported high precision display video modes of the device. Most of our demos for high precision stimulus display have been updated to support the device as well. help PsychDataPixx for more interesting features. Again, this is work in progress, a somewhat functional sneak preview, not the final product.

  • Some improvements by David Brainard et al. to the PsychCal subroutines for monitor calibration and similar tasks.

  • Lots of bugfixes, small improvements.

Have fun and good luck, -mario

Stable is dead! Long live beta!


For the record: The Psychtoolbox flavor formerly known as "stable" is hereby declared officially dead! We have renamed it to unsupported to allow users with an interest in archeology or masochism to download it under that new name. Hopefully the new name leaves no room for interpretation about the level of support or sympathy you could expect from us if you’d continue to use this flavor instead of letting it r.i.p.

We have removed all references to it from the Wiki and current downloader and have no intentions of ever touching it again for any purpose. Actually we didn’t touch it for almost 2 years, so this is nothing new. The beta flavor was always more current, reliable and bug free than stable ever was.

Psychtoolbox beta updates up to and including the update from 2009-02-18 (SVN Revision 1245)


These updates introduce support for the USTC RTBox button response box, the PR-655 colorimeter, and various bug fixes and enhancements. Especially the IOPort and PsychPortAudio drivers have been improved again.

Online documenation updated

Our tireless “master of online documentation” Tobias Wolf has updated the online documentation of all PTB functions on the Wiki, so it corresponds to the state of PTB - Beta as of 21st february 2009.

New PsychRTBox driver for RTBox USB Response button box by Xiangrui Li et al.

This new driver (see PsychRTBoxDemo for demonstration of most basic functions) allows to interface with the “USTC RTBox Reaction Time Box”, a response button box for button response collection from subjects with exact button press- or release timestamping. In addition to four response buttons, the box also provides a photo-diode input (including a photo-diode) and a single BNC trigger input for reception and timestamping of external trigger signals and visual stimulus onset. The driver allows to control all features of the box and to retrieve exact timestamps in the regular Psychtoolbox GetSecs time format, so the timestamps are directly comparable to timestamps returned by Screen('Flip'), PsychPortAudio, KbCheck, KbWait, GetSecs, WaitSecs, IOPort etc., which greatly simplifies calculation of reaction times and other time related events. Most aspects of the driver and especially its timing precision have been extensively tested under a variety of Macintosh computers and PC’s under Microsoft Windows XP, Linux and MacOS/X 10.4.x and 10.5.x., so far with good results.

PsychPortAudio sound driver

  • Important bugfix for playback of short sounds (less than about 50 milliseconds) on MS-Windows and GNU/Linux. Due to a flaw in the underlying PortAudio library, trying to call PsychPortAudio('Stop') after playback of such short sounds could cause Matlab to hang until it got forcefully terminated. This is fixed. However, this bug was only present in betas released in January 2009. Older versions of the driver didn’t expose this flaw.

  • PsychPortAudio methods 'Start', 'Stop', and 'RescheduleStart' now also allow you to define a sound offset time (called ‘stop’ time) in addition to the previous ‘when’ sound onset time: This allows to schedule a sound playback which lasts until an exactly specified point in time, nearly sample accurate, ie., with sub-millisecond precision. The ‘Stop’ subfunction allows you to (re-)specify a stop time while playback is already active, for on-the-fly rescheduling of your sound timing. This is done by setting the new optional 'stopTime' parameter.

  • These routines also allow you to specifiy and respecify (while playback is already active) the repetition count ‘repetitions’ for a defined number of sound repetitions, and the repetition count can be fractional now, e.g., 1.5 for one and a half repetitions of a sound.

  • The PsychPortAudio('Stop') function can now request stop of sound playback (as mentioned above via 'stopTime' or ‘repetitions’ or immediately) without waiting for the stop to actually happen. This can avoid blocking execution of your Matlab code in the ‘Stop’ routine for a few milliseconds, should your experiments require such a non-blocking behaviour. This is achieved by setting the new optional 'blockUntilStopped' parameter to a zero value. Otherwise, the ‘Stop’ method will block until sound is really stopped as in previous driver versions.

  • PsychPortAudio('RefillBuffer', pahandle [, bufferhandle=0], bufferdata [, startIndex=0]); allows to refill portions of the sound playback buffer while playback is active, for dynamic updating of sound content in situations where the streaming refill via the PsychPortAudio('FillBuffer') command is not applicable. This is interesting when used in conjunction with the new PsychPortAudio('SetLoop') command to restrict sound playback to a subsection of the playback buffer.

  • The new subfunctions PsychPortAudio('UseSchedule') and PsychPortAudio('AddToSchedule') allow to predefine a whole sequence of precisely timed of sounds to be played according to a given playback schedule. This is similar to the playlists you can set in your favorite media player. The schedule can be extended on the fly during sound playback to allow very flexible sound playback which can concatenate different sounds with well defined gaps inbetween or completely gap-free. Unfortunately we don’t have any interesting demos for this new function yet.

  • For people with very low latency requirements, the driver can be switched into a new mode of operation, called “runmode 1” via the PsychPortAudio('RunMode') function. By default, runmode 0 is used. In runmode 1, the audio hardware, once started, keeps running all the time. This consumes more system memory and processing ressources on your computer during the runtime of your script, as processing is active even if no sound is played at all, but it allows for a faster stop and restart of playback operations, ie., it can avoid multiple milliseconds of delay, especially on Linux, but also to some lesser extent on the other operating systems. You can compare this to a strategy where you keep the engine of your car running during stops at red traffic lights or in traffic jams, as opposed to our default strategy of stopping the engine at each halt and restarting after the break.

Colorimeter Support

  • We now support the Photo Research PR-655 colorimeter via the new PR655Toolbox in the folder Psychtoolbox/Psychhardware/PR655Toolbox. This code has been contributed by Thad Czuba. You can either use the routines in that subfolder directly, or use the higher level functions like CMCheckInit, CMClose, MeasXYZ and MeasSpd by selecting the ‘metertype’ argument to be 4.

  • Both, the new PR-655 toolbox and the old PR-650 toolbox now use the new IOPort driver instead of the old operating system dependent SerialComm driver. Due to this change, both toolboxes should now work on all operating systems, not only on OS/X.

IOPort Serial port hardware support

The new IOPort driver has been refined in a few areas. The driver is still much work in progress, with a few useful features missing. However, it should be already a far superior replacement for all old serial port drivers like PsychSerial, SerialComm and Matlabs serial objects for most purposes.

  • FindSerialPort function: Now can also automatically find serial port devices for the IOPort serialport driver on all operating systems.

  • New optional parameter 'HardwareBufferSizes=in,out' for IOPort('OpenSerialPort',..); and IOPort('ConfigureSerialPort', ...); configstring parameter. This is not set by default, and only supported on MS-Windows, ignored on other platforms. It triggers the Windows SetupComm() function to set the hardware input and output buffer sizes to the requested in,out values. Hardware drivers are free to ignore the request, and it will only work if invoked after opening the device but before doing any I/O. Rationale: The operating system is supposed to choose reasonable settings for these buffersizes if not provided (according to Microsoft documentation), but the old Windows PsychSerial driver set these sizes explicitely, so we give usercode the option to do so as well, in case some buggy windows drivers misbehave if this isn’t set.

  • IOPort('OpenSerialPort'): Bugfix in configuration option parser code for all operating systems. Providing settings/options in the optional 'ConfigString' parameter which conflicted with the builtin defaults may cause wrong setup, ie. either the defaults take precedence or the users settings, but in a unpredictable way. This is fixed now. Didn’t show up in any real applications so far, because 100% of all tested devices (and probably 95% of all devices out there) are happy with our builtin defaults.

  • Help texts have been improved as well.

Improvements and bug fixes to Screen and other drawing functions – The Visuals

  • New Screen('Preference','ConserveVRAM', ...) setting 16384 on OS/X allows to force use of AGL and Carbon in non-fullscreen windowed mode, even if a fullscreen window is requested. This as another attempt to work around the broken NVidia drivers for dual-display operations on Leopard 10.5.6 with Geforce 8000 hardware, as that bug persists on OS/X 10.5.6, and Apple engineering remains silent about this major defect. This workaround provides dual-display fullscreen display on such machines, but at a horrible performance, zero timing accuracy and defunct timestamping. It may be good enough for mostly static stimulus displays though.

  • Screen('Computer') on Mac OS should not crash anymore if machine has an empty machine name or empty username.

  • Screen('GlobalRect', win) now correctly returns the global bounding box (wrt. to origin of desktop coordinate system) of a given onscreen window handle ‘win’ even if the window is a real window, not a fullscreen window.

  • Screen('FrameRect'): When providing an empty (=default) rectangle, it didn’t draw anything due to some bug in the batchdrawing processing routine. This is now fixed.

  • Screen('Resolution') now only checks for open onscreen windows when deciding to be cooperative or not, not for any window. Previously a resolution switch was also prevented when textures or offscreen windows where open, which is not neccessary.

  • Bugfix for Screen on Mac OS: When onscreen window wasn’t a fullscreen window, but a windowed AGL+Carbon window, and the imaging pipeline was off, userspace rendering via MOGL didn’t work due to a bug in the way we set up our userspace OpenGL context in the AGL setup path. This is now fixed.

  • Screen('FillOval'): Added missing documentation of 'perfectUpToMacDiameter' parameter.

  • Screen subfunctions FillOval, FrameOval and FillArc, FrameArc, et al. will now work with subpixel accurate precision instead of rounding given locations to full pixels at various occassions. The precision of positioning and sizing such drawing primitives is now only limited the the graphics hardware at use, no longer by Screen itself.

  • Screen('DrawText') on Linux: Didn’t assign proper textcolors or render text correctly if a floating point precision HDR framebuffer was enabled, and a HDR draw shader was active to work-around GPU’s without glClampColorARB() support, e.g., on Linux with current ATI driver for Radeon X1600. This is now fixed. Also made more robust against very long fontnames of more than 256 characters.

  • Bugfixes to some PsychRects functions: They didn’t handle the case of passing 2, 3 or 4 rects properly. Only the single rect and > 4 rects cases were handled correctly. This is now fixed, although the current beta still contains a glitch for the exactly 4 rects case. Bugfixes by Thad Czuba and MK.

  • BitsPlusPlus error handling improved: Restores display gamma tables on error abort.

  • DrawFormattedText: New optional ‘vspace’ parameter allows to set line spacing between consecutive lines of text. Contributed by Alex Leykin. The function also now optionally allows to draw text that is mirrored/flipped left-right and/or upside down.

  • New function AddNormalsToOBJ: Takes an obj 3D object definition, as provided by, e.g., LoadOBJFile(), and adds per-vertex surface normal vectors to it. Useful if an OBJ file doesn’t have surface normals defined. Uses cross-product computation on defining triangles to calculate normals.

  • Minor other fixes and updates to help texts.

There are still a few unresolvable serious bugs in OS/X 10.5.6, especially prominent with NVidia 8000 series hardware for which no workaround exists. E.g., multi-display operation (stereo setups) seems to be highly unreliable and dysfunctional. Frame sequential stereo on NVidia 8000 series hardware seems to be seriously broken in 10.5.5 (and maybe 10.5.6, untested). Only Apple engineering will be able to fix this.

New or enhanced demos

  • FDFDemo and moglFDF received some further improvements: The maxFGDots and maxBGDots parameters are auto-adapted to meet requirements, instead of aborting with error. The new subfunction ReinitContext allows to change context stimulus parameters without need to destroy and recreate the fdf context, this is about 4 times faster when switching between conditions with high or low dot densities, short or long dot lifetimes and other parameters. The new optional instantOn flag to the Update function allows to buildup the whole dot distribution in one single ‘Update’ call at start of a trial. Minor other fixes and improvements. Now one can regulate the signal to noise ratio within the silhouette of the animated object between 0.0 and 1.0, allowing to introduce some background noise in the silhouette area. The FDFDemo now allows to control a couple of stimulus parameters during runtime by use of the cursor keys.

  • VideoCaptureDemo Now allows video image to cover full window, by proper, aspect preserving, rescaling.

  • MinimalisticOpenGLDemo now has an optional ‘checkerboard’ mode: Setting that optional flag will texture the spinning sphere with a Matlab generated checkerboard pattern instead of an earth surface image, just to show how this is done, as well as how to apply trilinear mipmap filtering to avoid any aliasing artifacts with such high-frequency patterns.

  • SimpleMovieDemo is the new most simple demo on how to playback Quicktime movies. Not fancy, but down to the absolute basics.

  • PsychRTBoxDemo demonstrates basic use of the new PsychRTBox driver for control of the USTC RTBox button response box.

Test scripts in PsychTests

  • Minor improvements to dualhead display sync tests in GraphicsDisplaySyncAcrossDualHeadsTest and PerceptualVBLSyncTest.

  • KeyboardLatencyTest now allows some assessment of the timing accuracy of response boxes, the response box from Cedrus, and the reaction time box from Xiangrui Li et al.

Misc other stuff

  • Merged large parts of the “Bitstuff Toolbox”: This is a collection of generally useful new M-File routines in the categories PsychSignal, PsychOneliners and PsychProbability. The toolbox was written and contributed under GPL license by Diederick C. Niehorster.

  • RestrictKeysForKbCheck is a new function that allows to restrict the keys to check in KbCheck, KbWait, et al. to a subset of keys on the keyboard. This is convenient on all systems to restrict subject responses to valid response keys. On Mac OS it can also provide a significant speedup in the operation of KbCheck, reducing its execution time from 1 millisecond to a few dozen microseconds.

  • KbName now queries all connected keyboards if called via KbName from the commandline, not only the primary keyboard.

  • Improvements to geometric display calibration routines: Optionally one can load an image file as a “backdrop image” to the calibration grids in DisplayUndistortionBezier/BVL, and one can set window size to the size of those images. This allows to (mis-)use those display calibration routines for creation of generic transformations, e.g., for generic image undistortion of images or videos. The still unfinished ImageUndistortionDemo allows to apply such calibrations to loaded images from disk for the purpose of image unwarping.

  • New routines for color conversions in Munsell color space in subfolder PsychColorimetric/PsychMunsell, contributed by David Brainard.

  • Add function GetEchostring: Ported from PTB-2, contributed by yaosiang.

  • Also add functions GetNumber and GetEchoNumber from PTB-2.

  • Ask function:Strips ENTER keycode and BACKSPACE keycodes from returned replies.

  • WaitSecs('YieldSecs', seconds) is a new subfunction of WaitSecs which allows to sleep for a specified time interval seconds, but imprecisely. That is, the sleep is allowed to take a few milliseconds longer than specified. This allows to use a different waiting strategy which is not precise, but reduces the load on the computers processor. It is meant for code that wants to be nice by not taxing the cpu too much, e.g., in a polling loop where not every millisecond counts.

  • Snd: Always returns some ‘err’ status, even if it is only a zero, as this return argument is mostly meaningless in current implementation. This for backwards compatibility to old Mac OS-9 code.

  • Enhancements to GetClicks and GetMouse, as suggested by Diederick Niehorster.

  • Modified PsychtoolboxRegistration routine for online registration to use the pnet() file on Matlab runtimes to implement communication for online registration. No need to use netcat anymore, except for Octave runtimes. As netcat aka nc.exe aka is no longer needed on the MS-Windows platform it has been remove from the distribution. No problems for poor Windoze users due to idiotic virus scanners anymore.

  • The new PsychHomeDir function retrieves path to users home directory on each system, and optionally to subdirectories as well.

New download location for Portaudio driver with ASIO support

The special patched portaudio_x86.dll audio low-level driver with compiled-in support for Steinberg’s ASIO sound interface for use on Microsoft Windows systems with our PsychPortAudio driver has a new home on our Wiki. You no longer need to request the driver from Mario Kleiner via e-mail. Instead, simply download the zip file with the driver from the PsychPortAudio section of the Wiki. The zip file contains the DLL, a readme file with installation, setup and usage instructions, and the special license for use of this driver, which deviates from our normal GPL license.

Psychtoolbox beta update from 2008-11-4 (SVN Revision 1151)


This update introduces support for “formless dot field” type stimuli, and various bug fixes and enhancements. Especially the IOPort driver has been improved again.

IOPort Serial port hardware support

The new IOPort driver has been refined in a few areas. The driver is still much work in progress, with a few useful features missing. However, it should be already a superior replacement for all old serial port drivers like PsychSerial, SerialComm and Matlabs serial objects for most purposes.

  • IOPort('Write') now supports a blocking flag of 2 on all operating systems. The old Linux specific polling for “transmitter empty” has been moved to blocking = 3. A mode of 2 now polls for the number of pending bytes for writeout in the system write buffer and repeats the polling loop until pending bytes = 0. This is supported on all operating systems.

  • IOPort('Write') now returns a couple of additional optional timestamps, useful for special timing calibration routines like the upcoming PsychRTBox.m driver, and for low-level debugging: A prewrite timestamp, a postwrite timestamp and a timestamp of last poll loop iteration (if used)…

  • IOPort('Read') accepts (for blocking reads) a new optional setting PollLatency in IOPort('ConfigureSerialPort',...); The setting allows to select the idle time between unsuccessful poll iterations, to trade off the system load against time quantization in such time critical polling loops.

  • IOPort('ConfigureSerialPort') allows via new options to enable asynchronous background reading of data from the serial port via a parallel background thread on MacOSX and GNU/Linux, this feature is not yet supported on Windows. If async read is enabled, IOPort('Read') will not directly fetch data from the serial port, but it will fetch data that has been read already in the background by the reader thread. This allows to automatically collect streaming data from serial port in the background, for later retrieval via ‘Read’ calls. This feature is experimental for now, its programming interface may change!

  • Help texts have been improved as well.

Improvements and bug fixes to Screen and other drawing functions – The Visuals

  • GetMouse on OS/X fixed: If used on multi-core Macintosh computers with many cores, e.g., MacPro 8 core machines and recent multi-threaded Matlab versions, the function crashed Matlab reliably on each single invocation, unless Matlabs GUI was disabled, ie. Matlab was run in -nojvm mode! This was a classic race-condition, probably present since the very first Psychtoolbox release around 1995! This bug only gets triggered with increasing probability on machines with large numbers of processor cores and on operating systems with efficient multi-threading support, so it basically never happened on single processor machines or under Mac OS 10.3 and earlier, and only very seldom on dual-core machines with recent Mac OS versions.

  • Regression in anaglyph stereo mode fixed: Anaglyph stereo as demonstrated in StereoDemo with settings 6,7,8 and 9 didn’t work. This is fixed.

  • Robustness improvements to Screen('DrawText') on OS/X: If a corrupt text string is supplied, the function doesn’t crash anymore, but abort with a (hopefully) diagnostic error message.

  • Bugfix to Screen('DrawText') on Windows: If text is drawn into different windows (onscreen or offscreen) with different text sizes or other different font settings, text should be drawn properly, instead of sometimes applying wrong settings. This was a bug in the way textsettings are cached internally to improve speed.

  • Screen('FillPoly') received a few performance optimizations. However most of them only had a minor impact on performance. Drawing of complex, concave, potentially self-intersecting filled polygons still needs substantial processing on the CPU and is therefore much slower than drawing of simple concave polygons or simple convex polygons (which are the fastest).

  • Potential robustness improvement for Screen('FrameRect') against broken graphics drivers when setting ‘penSize’. This is a potential improvement, which may or may not help on broken drivers.

  • DrawFormattedText: No longer aborts with error on empty text string as input, but simply does nothing in that case.

  • moglmorpher: The fast 3D morpher contained special workaround code for some serious bugs in the ATI display drivers on OS/X Tiger 10.4.x. As i’ve learned, the drivers got fixed at least in Leopard 10.5.5, so when used on 10.5, the workaround caused malfunctions on the fixed drivers! Now we detect the OS/X version, and only enable the workaround on versions lower than 10.5.5. This works now on all 10.4 systems and 10.5.5. I don’t know how it behaves on 10.5.0 to 10.5.4, due to lack of a testing system.

  • Small fix to VideoDelayLoopMiniDemo for use with built-in iSight cameras of some Macintosh computers. A bug in the OS/X operating system caused wrong image display on such cams.

  • Fix a bug in PsychVideoSwitcher driver which caused the TTL trigger mechanism to fail. Also extended trigger function: One can select if trigger should happen at each ‘Flip’ until disabled, or for a predetermined number of ’Flip’s then auto-disable.

  • PsychImaging: Add support code for setup of native 10 bpc framebuffers on supported ATI FireGL/Pro and NVidia GTX cards.

  • Fix in ConvolutionKernelTest for error handling when invalid convolution kernels are passed.

  • Minor other fixes and updates to help texts.

There are still a few unresolvable serious bugs in OS/X 10.5.3, 10.5.4 and 10.5.5, especially prominent with NVidia 8000 series hardware for which no workaround exists. E.g., multi-display operation (stereo setups) seems to be highly unreliable and dysfunctional. Frame sequential stereo on NVidia 8000 series hardware seems to be seriously broken in 10.5.5. Only Apple engineering will be able to fix this.

New or enhanced demos

  • FDFDemo is a new demo: It demonstrates basic usage of the new moglFDF function, rendering an animated rotating “random dot” motion sphere. The moglFDF function allows to efficiently draw a special class of random dot “structure from motion” stimuli, so called “(F)ormless (D)ot (F)ields”. The algorithm is heavily inspired by the algorithm introduced by Jedediah M. Singer and David L. Sheinberg in their Journal of Vision paper “A method for the real-time rendering of formless dot field structure-from-motion stimuli” (Journal of Vision, 8, 1-8). It should behave mostly as the method described in that paper, but operate at a significantly higher speed if stimuli are demanding (e.g., high display resolution, large number of dots, complex underlying 3D geometry), as the moglFDF routine pushes nearly all compute intense operations onto the GPU, only random number generation and flow control are done on the CPU. However, as the paper doesn’t state actual benchmark numbers and i never had a look at their implementation, this is an unverified assumption so far. This code has been tested for multiple months in-house for complex 3D facial motion stimuli and worked well, but given its complexity there may remain more or less subtle bugs or limitations of the method for other classes of stimuli. Let me know if you find this routine useful and if you encounter limitations. One limitation is the need for half-way recent graphics hardware: Minimum requirements are a NVidia GeForce 6000 series card or later, or a ATI Radeon X1000 series card or later, more specifically hardware with support for or later and floating point framebuffers.

  • ImagingStereoMoviePlayer Minor improvements.

  • MovingLineDemo: Changed behaviour to be more useful for exposing the troubles with flat panels.

  • AdditiveBlendingForLinearSuperpositionTutorial now also demonstrates how to use the TTL trigger mechanism of the VideoSwitcher device.

  • BitsPlusCSFDemo contrary to its name now also supports optional output to VideoSwitcher device , ATI 10 bpc framebuffer and PseudoGray output (aka bit stealing). It also allows to display an intensity gradient test chart instead of a CSF chart.

Test scripts in PsychTests

  • Minor improvements to dualhead display sync tests in GraphicsDisplaySyncAcrossDualHeadsTest and PerceptualVBLSyncTest.

  • KeyboardLatencyTest now allows some assessment of the timing accuracy of response boxes, the response box from Cedrus, and the reaction time box from Xiangrui Li et al.

Misc other stuff

  • SearchGammaTable and various display calibration routines improved by David Brainard, also improvements to CalDemo

  • Fix annoying warning about unrecognized escape sequence for KbName on Linux.

  • Modifications to SerialComm to translate a hardware path, e.g. /dev/cu.usbserial, to a port name and improvements to FindSerialPort by Christopher Broussard.

Psychtoolbox beta update from 2008-08-15 (SVN Revision 1110)


This update introduces support for synchronizing the displays of ATI based dual-display setups on OS/X, experimental support for 10 bit native framebuffers on some graphics hardware, smallish fixes for demos and subroutines, and a few new demos and tests in PsychDemos and PsychTests, as well as improvements to existing demos. The new IOPort has been improved as well.

IOPort Serial port hardware support

The new IOPort driver has been refined in a few areas. The driver is still much work in progress, with a few useful features missing. However, it should be already a superior replacement for all old serial port drivers like PsychSerial, SerialComm and Matlabs serial objects for most purposes.

  • The optional nonBlocking flag of the IOPort('Write') and IOPort('Read') subfunctions is replaced by a blocking flag instead! If you didn’t specify that flag in code using that driver, you won’t need to change anything in your code, because the default behaviour is the same - and the default is pretty reasonable. If you specified that flag in your code, you’ll have to change that flag to be the opposite of what it was! If you used a setting of 0, change it to 1 and vice versa. The old flag nonBlocking used a double-negation - A setting of zero meant no non blocking operation, ie., blocking operation! Beta testing proved that this twisted definition is too hard on the brain, including the brain of the person that developed the driver ;-) – The meaning of the new blocking flag is easy to understand, so the potential of wrong use of that flag should be greatly reduced.

  • On GNU/Linux, the blocking flag in the IOPort('Write') subfunction can also be set to a setting of 2, on other operating systems a setting of 2 is treated like a setting of 1 for now. A settting of 2 requests use of an especially low-latency mode of waiting for write completion. This is useful for code that needs especially high timing precision in sending data out of the serial port, but it incurs much higher processor load, so it should be used judiciously. With some serial port hardware, it can cause a complete hang of the application due to low level driver bugs (e.g., the current FTDI serial-over-usb driver).

  • At IOPort('Verbosity',0) verbosity level zero, the driver won’t abort an [handle, errmsg] = IOPort('OpenSerialPort',...); call anymore if opening the serial port fails. Instead it returns handle to be a negative number and returns an operating system dependent error message in the optional return argument errmsg. The text string errmsg contains some specific (searchable) text tokens to signal some frequent error conditions. Specifically, the text string ENOENT is contained in errmsg if one tries to open a non-existent serial port device. Accessing a device which is already opened by some other process, or with insufficient access permissions, or opening a serial port that exists but doesn’t have an operational device connected, will return EBUSY and/or EPERM as part of the errmsg string. This behaviour and tokens allows custom written Matlab code to auto-detect and probe available and operational serial ports by trying to open known ports and checking the return codes. Useful for automatic device detection.

  • Help texts have been improved as well.

Hardware support

  • The CedrusResponseBox driver has been improved to take advantage of the improved IOPort driver for higher robustness in error handling. The overall robustness of Cedrus response box support hasn’t increased though, but we are quite certain that this is mostly due to design flaws in the response boxes. Still no response from Cedrus developer support, 4 month after an inquiry… See also Docs:CedrusResponseBox

Improvements to Screen – The Visuals

Most improvements are related to the image processing pipeline. While the detailed documentation is contained in the files referenced below, most functions are accessed and controlled by the PsychImaging function and the basic help for how to use them can be found there. Demos mentioned below demonstrate this stuff in “real world” scripts.

  • Support for native 10 bits per color component (10 bpc) framebuffers on some graphics hardware + operating system combinations:
  • On GNU/Linux and OS/X with ATI Radeon GPU’s of the consumer level Radeon X1000 series and the Radeon HD2000 / 3000 / 4000 series and later, we provide experimental support for 10 bit framebuffers with our own homegrown solution. On Linux you need to start Octave or Matlab as system administrator or via the sudo command so it has the neccessary permissions to do so. On OS/X you need to load our special PsychtoolboxKernelDriver, see help PsychtoolboxKernelDriver for how to do that. Support is experimental in the sense that we can’t guarantee that this feature will work reliable (or at all) on a given system configuration, because we use tricks that are not officially supported or recommended by ATI or Apple, so this feature may or may not work due to factors out of our control. If it works, it may break with future operating system upgrades, so if you need it, better make a backup of your operating system in case you’d need to downgrade!
  • That said, it works pretty well on the tested machines with Tiger 10.4.11, and it actually worked like that since multiple Psychtoolbox beta releases. The news is that we finally verified it really gives 10 bits resolution on consumer Radeon cards via some perceptual visual test - A nice greyscale gradient test image which shows clearly perceptible intensity steps at the expected locations in 8 bit framebuffer mode, but a smooth gradient in experimental 10 bit framebuffer mode.

  • On Microsoft Windows and GNU/Linux, the first graphics cards with native, officially vendor supported 10 bit framebuffers start to hit the market. If you happen to have such a card, Psychtoolbox will support it as well, without the need for special experimental tricks. These cards should support 10 bit reliably - assuming the vendors implementation is correct. As of now, vendors have announced some level of 10 bit support for the following cards:

  • ATI/AMD FirePro / FireGL GPU of the latest 2008 generation is advertised as supporting 10 bit on special 10 bit digital displays (e.g., high precision flat panels with DisplayPort), it may soon support 10 bit over the analog output as well (ie., VGA driven CRT monitors etc.).

  • The latest generation NVidia Quadro GPU’s on Linux (and probably Windows?) will support 10 bit output, according to this excerpt from the release notes of the latest NVidia display drivers for Linux.

  • The latest generation of NVidia Geforce GPU’s is rumored to support 10 bit natively under some circumstances as well: See this link and this link.

  • Support for 10 bpc framebuffers can be enabled via the PsychImaging('AddTask', 'General', 'EnableNative10BitFramebuffer'); subcommand, as demonstrated in the AdditiveBlendingForLinearSuperpositionTutorial demo.

  • The PsychtoolboxKernelDriver for OS/X has been refined. We’ve verified that it is able to synchronize (or resynchronize, after some change of display settings or display configuration) the video refresh cycles of two identical displays connected to the two output connectors of a dual-head graphics card. This works only on ATI Radeon graphics cards of the X1000 series (and likely later models of the HD series) and only for one single dual-head card. It has only been tested on the Radeon Mobility X1600 so far. You need to choose identical monitors and identical display settings for resolution, color depths and refresh rate if you want the monitors to stay in sync after a synchronization, otherwise they’ll quickly drift out of sync due to different timing. You need to load the kernel driver as described in help PsychtoolboxKernelDriver. Then you can issue the residual = Screen('Preference', 'SynchronizeDisplays', 1); command to trigger a resync. The optional return argument residual will contain a remaining offset in scanlines between the two displays. The driver will try up to four times to resync. We always managed to get perfect sync this way. The scripts PerceptualVBLSyncTest([0,1]) and GraphicsDisplaySyncAcrossDualHeadsTest allow you to test the sync. The first script allows for a perceptual test, the latter script for some numeric assessment.

  • The PsychtoolboxKernelDriver for OS/X also provides support for beamposition timestamping on ATI graphics cards – a feature lacking on current OS/X. This support is nothing new, just worth mentioning again.

  • We no longer unconditionally disable beamposition queries on MS-Windows with Intel GPU’s. Some modern Intel GPU’s will probably work correctly and our tests have improved so much that we should be able to detect problematic chips automatically. So some Intel GPU’s will provide more accurate stimulus timestamping.

  • Capabilities of the ATI FireGL / FirePro GPU should be now detected correctly on Windows and Linux.

  • A new image processing function AddImageUndistortionToGLOperator() plus demo ImageUndistortionDemo.m how to use it: It allows application of geometric “unwarp” transformation as created by DisplayUndistortionBVL/Bezier to textures and offscreen windows by use of Screen('TransformTexture') instead of as part of preflip operations. This allows for geometric undistortion of input images, instead of whole display devices. The demo is kind of sketchy, that’s why it is added to the PsychAlpha/ subfolder to label it as workable but immature. This method is useful if you don’t want to correct for geometric distortions of your display device (for that, see help DisplayUndistortionBVL), but if you have some optically distorted input video footage or images (e.g., from some camera) that you want to undistort, or if you want to actually apply a geometric distortion to your visual stimulus image.

  • Minor other fixes and updates to help texts.

New built-in workarounds in Screen for broken graphics drivers and operating systems

These workarounds get automatically enabled if the corresponding problem is detected on your system. Some will print out some warning messages to inform you about the problem and possible caveats related to the workaround. Remember: It’s always better to fix the system than to rely on some workaround which can only fix 90% of the problem and isn’t totally for free. Therefore stay informed about graphics driver and operating system updates if your system has problems.

  • MS-Windows with many ATI cards and recent NVidia cards/drivers: Beamposition queries fail and therefore get disabled. Certain types of failure can be auto-detected and a workaround is enabled. This workaround should reenable high-precison timestamping on such systems, at the expense of slightly increased processor load in certain cases. The warning message of Screen will tell you about more details and refer you to some help text that explains further caveats of this approach.
  • In this release we’ve increased the sensitivity of the test which is supposed to detect such broken beamposition mechanism on startup, so it is less likely to miss some broken configs. In case it still misses some bugs, you can add the new setting 4096 to a call Screen('Preference', 'ConserveVRAM', ...);, see help ConserveVRAMSettings for more info. This will unconditionally enable the special workarounds, even if our test doesn’t detect any problems.

There are still a few unresolvable serious bugs in OS/X 10.5.3 and 10.5.4, especially prominent with NVidia 8000 series hardware for which no workaround exists. E.g., multi-display operation (stereo setups) seems to be highly unreliable and dysfunctional. Certain Screen('CopyWindow') commands can caus a hard graphics system lockup for no conceivable reason. Many posts on public internet forums and the Apple mailing lists suggest many more similar serious problems. Only Apple engineering will be able to fix this. Currently we recommend to not upgrade to 10.5.3 or 10.5.4 on machines that are crucial for your productive work!

New or enhanced demos

  • AdditiveBlendingForLinearSuperpositionTutorial shows two things:
    • How to take advantage of high precision floating point textures, framebuffers and additive alpha-blending to efficiently draw mathematically correct superimposed stimuli, e.g., overlapping gratings with controllable contrast. This demonstrates a very efficient way of doing such things.
    • How to enable support for a variety of supported high precision display devices and methods. The demo shows correct setup of nearly all currently supported devices. Type help AdditiveBlendingForLinearSuperpositionTutorial for an overview. The previous demo, which was specific to the CRS Bits++ box, has been merged into this demo.
  • SimpleVoiceTriggerDemo demonstrates two different methods of implementing voice triggers via the PsychPortAudio driver. The BasicSoundInputDemo and a few other scripts demonstrate this as well, but this demo is cut down to show only the essentials of voice trigger support. Please note that this is just a simple threshold-based trigger, nothing fancy. One could implement more clever filtering to make it more robust, but the basic structure would be the same.

  • DrawMirroredTextDemo now also shows how to mirror (flip) text upside down instead of only left vs. right.

  • MovingLineDemo just shows a pair of vertical lines which move horizontally over the screen from left to right. The speed of travel can be set. Why? Because it nicely illustrates the kind of display artifacts and strong motion blur you can get for moving stimuli if you use a flat panel instead of a CRT monitor.

New test scripts in PsychTests

Two tests illustrate the accuracy, or rather inaccuracy, of keypress and mousebuttonpress timestamps. Try them yourself! There are good reasons why special response boxes are still sold and bought for precise reaction time measurements.

  • KeyboardLatencyTest: This test scripts implements a method to measure absolute keyboard or mouse latency, ie., how close the measured keypress time, e.g., via KbCheck or GetMouse is to the real keypress time on your standard keyboard, trackpad our mouse. The script relies on a properly configured PsychPortAudio driver and a sensitive microphone attached to or close to your keyboard or mouse. I’ve tested it with the built-in microphone of a MacBookPro. The measurement procedure consists of you repeatedly hitting keys on the keyboard or buttons on you mouse / trackpad. The noise made by hitting the buttons or keys gets captured by the microphone and timestamped by our audio driver + threshold based “voice trigger” implementation. Keypress / Mouse button press time is also measured via a tight KbCheck, KbTriggerWait or GetMouse loop. The script then compares the timestamps of both methods to compute average keypress latency and variability in timing, assuming/knowing that the audio measurements are usually more accurate and low latency on well working audio hardware. The method is of course not perfect, needs careful tuning of sound thresholds and a well working sound card, and you should obviously not trust the measurements down to the millisecond - or at least first verify correct working of the sound trigger method with measurement equipment before trusting it . Still it provides some quite nice illustration of how large and noisy latencies from standard keyboards and mice can be. Also with identical hardware, latencies can vary significantly depending on operating system and model of keyboard or mouse. Example: On a MacBookPro under OS/X average latencies of 16 msecs for external mouse queries and 30 msecs for internal keyboard queries have been observed. The same machine under Ubuntu Linux 7.1 showed also 30 msecs average latency for the keyboard, but 60 msecs latency for the mouse. Variability of mouse timestamps was lower than that of keyboard timestamps.

  • HIDIntervalTest: This scripts measures the sampling interval of human interface devices (HID), specifically mice and keyboards. During a measurement loop of 10 seconds duration, it asks you to randomly and furiously hit keys on the keyboard, press mouse buttons and move the mouse. Then it plots histograms with the distribution of timestamps collected from mouse button up/down, mouse movement and keypress/release events. The histograms illustrate the sampling – and therefore – quantization of HID devices. Here a few results: On the MacBookPro under OS/X 10.4.11, the internal keyboard as well as buttons on trackpad and mouse are sampled at roughly 8 msec intervals. The sampling frequency of mouse movements however is directly related to the display refresh interval: At 60 Hz refresh, 1000 / 60 = 16.6 msecs. At 75 Hz refresh, 1000 / 75 = 13.333 msecs etc. The same machine under Linux has a constant sampling interval of 8 msecs for mouse, trackpad and keyboard. Some other machine tested under WindowsXP showed a sampling interval of 16 msecs for mouse and keyboard.

Misc other stuff

  • Diederick C. Niehorster contributed a new function ShrinkMatrix and a speed improvement to the existing function Magnify2DMatrix. Both functions are used for shrinking or expanding Matlab matrices.

  • The file extensions of all MEX files for Matlab 7.4 (R2007a) and later on Microsoft Windows have been changed from .dll to .mexw32 - the preferred name extension in new Matlab releases. This to prevent unneccessary warning messages by the upcoming Matlab R2008b about deprecated file extensions.

Psychtoolbox beta update from 2008-07-12 (SVN Revision 1090)


This update, apart from work-arounds for for broken graphics card drivers mainly introduces support for anti-aliasing of visual stimuli while the image processing pipeline is used. So far, use of the imaging pipeline and of multisampled anti-aliasing where mutually exclusive. Simultaneous use of both is available on graphics hardware and operating systems that support the required OpenGL extensions EXT_framebuffer_blit and EXT_framebuffer_multisample.

Hardware support

  • Serial port support: Small improvements to “IOPort”, a new cross-platform driver for control of Input/Output ports and esp. serial ports. At verbosity level zero, the driver shut now really shut up. If opening a port fails at verbosity level zero, no abort due to error is done, instead an invalid handle -1 is returned. This allows code to probe serial ports via trial and error without cluttering the console window of Matlab/Octave. Timing behaviour of blocking writes to serial port improved: Should now really block on Windows until data has been written out the port. On Linux a new polling-for-completion mode allows to poll for write completion instead of blocking. This is useful to get lower latencies on short writes, e.g., for clock calibration routines that are used to sync PTB’s clock with external hardware clocks.

  • KbCheck(-1) now allows to treat all connected keyboards on OS/X as one single keyboard, instead of querying each keyboard in isolation (when a keyboard index of a specific keyboard is passed) or of the primary keyboard alone. Contributed by Andrew Leber.

  • CharAvail Christopher Broussard implemented some speed optimizations for that command.

Improvements to Screen – The Visuals

Most improvements are related to the image processing pipeline. While the detailed documentation is contained in the files referenced below, most functions are accessed and controlled by the PsychImaging function and the basic help for how to use them can be found there. Demos mentioned below demonstrate this stuff in “real world” scripts.

  • Support for multisample anti-aliasing when using the imaging pipeline: If the optional ‘multisample’ parameter in Screen('OpenWindow') or PsychImaging('OpenWindow') is set to a non-zero value, then multisample anti-aliasing will be used in the same way as when the imaging pipeline is disabled. This wasn’t supported up to now, because it requires a totally different internal implementation. Additionally, Screen('OpenOffscreenWindow') with imaging pipeline enabled, honors a new optional ‘multisample’ parameter, so one can enable or disable multisample anti-aliasing for offscreen windows on a per-offscreen windows basis. Please note though that anti-aliased offscreen windows can’t be directly drawn or copied around via Screen('DrawTexture') or Screen('CopyWindow'), neither can’t there images be read-back directly via Screen('GetImage'). Instead one needs to create a “normal” offscreen window of matching size and use Screen('CopyWindow') to create a copy of a multisampled offscreen window into such a normal offscreen window. The copy will be anti-aliased and drawable. This is due to the way the underlying hardware works – The use of Screen('CopyWindow') triggers an explicit multisample resolve and anti-aliasing operation for more control.

  • On MS-Windows and GNU/Linux, most recent NVidia and ATI GPU’s do support anti-aliasing with the imaging pipeline on. On OS/X, only some ATI GPU’s do support this feature when used on “Leopard” version 10.5.3 or later, but support for NVidia GPU’s on “Leopard” is expected to arrive in a future OS/X release.

  • Screen('CopyWindow') will use a new internal implementation on systems that support EXT_framebuffer_blit extension for more flexibility and speed. Should this pretty new code expose any bugs, you can use Screen('Preference', 'ConserveVRAM', 2048); setting to switch back to the old implementation, but don’t forget to report such issues to the forum, should there be any.

  • The subfunction Screen('Blendfunction') optionally allows to set a “color write mask”: You can selectively enable or disable drawing into specific color channels, in case this is of any use. E.g., you could only enable the red channel for drawing ops, so any following drawing commands only change colors in the red channel, but leave the green, blue or alpha components of the framebuffer untouched.

  • Minor other fixes or help text updates.

New built-in workarounds in Screen for broken graphics drivers and operating systems

These workarounds get automatically enabled if the corresponding problem is detected on your system. Some will print out some warning messages to inform you about the problem and possible caveats related to the workaround. Remember: It’s always better to fix the system than to rely on some workaround which can only fix 90% of the problem and isn’t totally for free. Therefore stay informed about graphics driver and operating system updates if your system has problems.

  • MS-Windows with many ATI cards and recent NVidia cards: Crash when trying to use 3D mode. Fixed: You no longer need to provide the special Screen('ConserveVRAM') flags to manually enable workarounds. Should just work, without any known limitations.

  • MS-Windows with many ATI cards and recent NVidia cards/drivers: Beamposition queries fail and therefore get disabled. Certain types of failure can be auto-detected and a workaround is enabled. This workaround should reenable high-precison timestamping on such systems, at the expense of slightly increased processor load in certain cases. The warning message of Screen will tell you about more details and refer you to some help text that explains further caveats of this approach.

  • OS/X with all graphics cards on both “Tiger” and “Leopard”: Wrong conversion of very small values in floating point textures of 16 bit float precision. Very small values (around 10e-9) which should be rounded down to zero, as they are not representable by that format, “wrap around” and result in huge numbers that create severe visual artifacts. This is an operating system bug. Our code now performs this rounding itself, restoring correct behaviour, at the cost of additional computation time in Screen('MakeTexture') when using such floating point textures. If you use 32 bpc floating point textures instead, numerical precision will be much higher, and there are no known problems with that format. 16bpc textures are accurate to 3 digits behind the decimal point, whereas 32 bpc float textures are accurate to around 7-8 digits - sufficient for any conceivable use. However such high precision textures take up twice the amount of memory and have potentially lower drawing speeds– Life is full of trade-offs…

  • Some optimizations to the internal texture creation code to allow for faster texture creation on some broken ATI drivers on Windows: Speedup can be 10x or more.

  • The timestamping code in Screen has been improved further to try to prevent false alerts wrt. broken timestamping on some slightly deficient graphics drivers under rare conditions.

  • Workaround in Screen('DrawDots') and Screen('DrawLines') to prevent hard graphics system lockups on some totally broken OS/X 10.5 systems with NVidia hardware.

  • Workaround in procedural gabor and sine grating shaders for bugs in the GLSL shading language implementation for ATI Radeon HD cards on OS/X 10.5.3 and 10.5.4. The workaround fully resolves the issue. Apple engineering confirms a fix will be available in an upcoming OS release.

  • Small fix to InitializeMatlabOpenGL, contributed by Mingjing Zhang, Vision Research Lab., University of Science and Technology of China. Had trouble loading the GL constants file if PTB was installed in a path with spaces in its name on MS-Windows.

However, there are still a few unresolvable serious bugs in OS/X 10.5.3 and 10.5.4, especially prominent with NVidia 8000 series hardware for which no workaround exists. E.g., multi-display operation (stereo setups) seems to be highly unreliable and dysfunctional. Certain Screen('CopyWindow') commands can caus a hard graphics system lockup for no conceivable reason. Many posts on public internet forums and the Apple mailing lists suggest many more similar serious problems. Only Apple engineering will be able to fix this. Currently we recommend to not upgrade to 10.5.3 or 10.5.4 on machines that are crucial for your productive work!

Misc other stuff

  • MoviePlaybackDemoOSX can now optionally the “Buy a Mac” ads from Apple’s website instead of the boring colliding discs demo movie on “OS/X”. Unfortunately movie playback from the web is only supported on “OS/X”, so the main target audience is missed ;-)
  • MinimalisticOpenGLDemo allows to set flags to demonstrate multisample anti-aliasing with/without imaging pipeline enabled.
  • Other small enhancements to demos, downloaders and installers.

Psychtoolbox beta update from 2008-06-09 (SVN Revision 1064)


This update, apart from the usual bug fixes (mostly for broken graphics card drivers, but also for a few ptb bugs) mainly improves support for high precision drawing and display of visual stimuli. Another major part is consistent support of serial port access for all operating systems and runtime environments. And then there are lots of improvements to single functions.

Hardware support

  • Experimental support for the basic functions of the USB 1024-LS digital I/O box on Apple OS/X. This is implemented but untested – no feedback was received by any of the persons who wanted to try it.

  • Support for Cedrus response boxes of the RBx30 series and compatible XiD devices. See “help CedrusResponseBox” for how to use the new CedrusResponseBox command to operate and query the box. Please note that the current driver only “sort of works” for the basic features of the box, although a lot of time has been spent by multiple people trying to make it work. More advanced features are implemented, but their reliability is low enough to render them useless for most purpose. Basic key queries and button event queries work, so you can actually get responses from your subjects. Queries of the built-in timers work, but due to some interesting design flaws in the protocol, i’m not sure what they should be good for, unless you can get external baseline signals from the TTL trigger input ports. Setup, control and query of the TTL i/o port sometimes (in about one third of all trials) works under some random and unrepeatable circumstances, so good luck if you want to use them. I am still waiting since 30th of April for any helpful comments or suggestions from Cedrus developer support about how one can make their devices more cooperative with software other than their own. Thanks to Jenny Read, Cambridge Research Systems, Jon Peirce, Thomas Tanner and Tobias Wolf for suggestions, code examples, testing or sharing the pain.

  • Improved support for the EGI/Netstation EEG system. Our old NetStation control function apparently only worked on PowerPC based Macintosh computers. The new driver works on all Apple Macintosh computers and should also work on Intel PC under Windows and Linux. Thanks to Gergely Csibra and Zhao Fan for fixing this.

  • The pnet mex file for TCP/UDP/IP support has been recompiled to allow for lower communication latency. This should improve timing for at least NetStation and the iViewX eyetrackers.

  • Serial port support: This update contains the first release of “IOPort”, a new cross-platform driver for control of Input/Output ports. The driver works with Matlab and Octave on all supported operating systems OSX, Linux and Windows. This initial release provides unified support for serial ports, both native ones and serial ports emulated over USB protocol or other protocols. Future versions of the driver are intended to provide support for other types of I/O ports, e.g., parallel ports. As of now, the driver is only used by the CedrusResponseBox M-File, but long-term all code should be switched to this unified driver, e.g., the PR-650 photometer routines etc, so we can get rid of special solutions like PsychSerial or SerialComm.

  • Mouse wheel support: On OS/X the function GetMouseWheel() allows query of the state/movement of the mouse wheels of wheel mice. However, this seems to occassionally crash after multiple “clear all” -> run script -> “clear all” cycles for yet unresolved reasons.

Improvements to Screen – The Visuals

Most improvements are related to the image processing pipeline. While the detailed documentation is contained in the files referenced below, most functions are accessed and controlled by the PsychImaging function and the basic help for how to use them can be found there. Demos mentioned below demonstrate this stuff in “real world” scripts.

  • Much improved HDR/High precision drawing support, including improved GPU capabilities detection, especially on Apple OSX: Psychtoolbox should support drawing of arbitrary color values, even ones with negative signs, on OS X as well. In the past, this feature was only available on MS-Windows and Linux due to some software design restriction in all versions of OS X. PTB can now detect such restrictions and enable a special internal workaround solution that achieves the same without relying on the operating systems support. The ability to draw “negative” color values is mostly useful for subtracting color from a given framebuffer image in combination with alpha-blending, e.g., for fast and efficient drawing of large numbers of gabor patches or superimposed patches. Examples of this technique are demonstrated in BitsPlusPlusAdditiveBlendingForLinearSuperpositionTutorial or GarboriumDemo. There is also a new but not fully finished test script HighColorPrecisionDrawingTest. It allows to get some basic measures of the accuracy (how closely does the drawn color/luminance match the requested one) of drawing commands. Some test cases sometimes give worse numbers than they should due to some quirks in some graphics cards which are unrelated to accuracy but confounded with it. E.g., if the majority of test results tells you that your system can draw with 16 bits of precision, but one or two tests tell you it only has 6 bits or 0 bits of precision, then you can assume that the 16 bits is the more correct number and the other one is the outlier.
  • This functionality is mostly controlled by the special floatprecision flags of Screen('MakeTexture',...) for drawing of high precision textures, and the Screen('ColorRange',....) command for drawing of other primitives and control over the required precision, value range and clamping behaviour of such drawing operations. General control of framebuffer precision is again done via PsychImaging and its subfunctions.

  • High precision display device drivers for most common devices, and a test to test them:
  • CRS Bits++ in all modes – Detail improvements: Support for automatic gamma correction in Mono++ and Color++ modes (see below) and for overlay windows in Mono++ mode. Some automatic fixes for some broken graphics drivers as well.
  • VideoSwitcher by Xiangru Li et al. – A video attenuator device with active amplifiers, useable with standard RGB monitors for high precision luminance output, including a single TTL trigger output port. See help for PsychVideoSwitcher.
  • Generic video attenuator support via Lookup table transforms: Allows to drive any attenuator style device. You create some Luminance to RGB lookup table for your device in a device specific manner. Our driver performs automatic mapping of luminance values to proper RGB values from the table. Supports devices with up to 16 bit luminance resolution.
  • PseudoGray shader aka BitStealing: An algorithm that tries to squeeze out a few extra bits of luminance reproduction on standard 8 bits per color component graphics cards: See help for CreatePseudoGrayLUT
  • ATI 10 bpc framebuffer refinements: See help for PsychHelperCreateARGB2101010RemapCLUT and for PsychtoolboxKernelDriver
  • BrightSideHDR refined: Support for the DR37-P high dynamic range display from BrightSide also received a few detail improvements.

The BitsPlusPlusAdditiveBlendingForLinearSuperpositionTutorial currently demonstrates how to enable and use the different drivers in its source code. While this script used to only demonstrate mode, it its now more generic and will need a new name. The HighPrecisionLuminanceOutputDriversImagingPipelineTest tests accuracy of the different output drivers, except for the CRS Bits++ which has its own test script like in the past.

  • Color management integrated into all opmodes, e.g., gamma correction: This applies only in conjunction with use of the imaging pipeline. It should work with all HDR / high precision output drivers (see above). Read help for PsychColorCorrection for an overview. Currently only a simple gamma correction is implemented, but this is easily extensible.

  • High quality spatial display calibration and geometric undistortion routines, contributed by the Banks Vision Lab at University of California, Berkeley. Read help DisplayUndistortionBVL for an overview of functionality and usage of the calibration procedure. Their website also contains some instructions. The current help text was mostly written by me, so i’m the one to blame for sloppy explanations and they are the ones to praise for high quality calibration routines ;-)

  • Some new PsychImaging subfunctions, e.g., dynamic selection of processing ROI: You can restrict image processing to some subregion of the display to save computation time if you need high redraw rates on high resolution displays, your graphics card is too slow and the stimulus only covers a fraction of the display area.

Online function reference available


Thanks to the clever and enthusiastic work of Tobias Wolf, the help texts of Psychtoolbox are now also available online:

The same link is available from the top page of the Wiki as “Function reference”.

The reference is mostly automatically generated by a clever Python script that we will occassionally run over the whole ‘beta’ distribution. The script automatically extracts, formats, hyperlinks and uploads the help content from all Psychtoolbox M-Files and the online help of most MEX files to the documentation Wiki.

The online reference is imho much more easily readable/browseable due to all the nice clickable cross-links and the much nicer formatting. The content however is almost the same as what you get from your Matlab console by typing help Psychtoolbox, help GetChar, Screen, Screen OpenWindow? etc. Unfortunately there don’t exist any scripts that automatically rewrite documentation :-(

The script is clever but it has the hard job of turning an organically grown mass of help texts, written by many different people and as many different opinions on formatting/writing style but without any formal markup language, into something half-way structured ;-) – iow. formatting glitches are to be expected. If you find small glitches, take them as beautful examples of modern art. If you are really annoyed by some formatting, feel free to find out what goes wrong and contribute fixes to the documentation or even better, volunteer to be the one with good taste and make it your personal mission to beautify our documentation.