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.

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.

Linux:

• 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” ;-)

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.

Windows:

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

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

For details, please review the detailed change log.

Highlight:

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.

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.

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.

OS/X:

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.

Linux:

• 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.

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.

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.

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.

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.

Screen

• 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.

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.

Screen

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

OpenAL

OpenAL 3D sound support now also implemented for Linux.

Other

• 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.

Significant changes have been added in the past year, though the online documentation has not yet caught up. For details, please review the detailed change log.

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.

Eyelink toolbox

• 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.

Enjoy!

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”.

Enjoy!

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, http://developer.berlios.de/bugs/?group_id=5064 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

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.

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 nc111nt.zip 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.

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.

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.

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.

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.

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

http://docs.psychtoolbox.org

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.