Mario Kleiner edited this page Jan 3, 2017 · 18 revisions

Downloading Psychtoolbox

Q: How do I get Psychtoolbox?

A: Follow the instructions provided on the website.

Backwards Compatibility

Q: Is PTB-3 backwards compatible with PTB-2 (Mac or Win)?

A: Not really. In developing PTB-3, it unfortunately turned out that the imaging model of PTB-2 too tied in with Apple's QuickDraw to make it work with OpenGL.

For example, in OpenGL a fundamental concept is buffer switching. The contents of a 'front' buffer are displayed while you issue commands to affect the contents of a 'back' buffer. A single command then flips the role of the two, allowing for quick updating of the entire display. This concept was not part of the PTB-2 imaging model. A consequence of this change is that if you don't insert the flip command Screen('Flip', ...) after your drawing operations, you won't see the result. This change can take a little while to get used to, if you've been programming in PTB-2.

However, if you must use old code written for PTB-2, you can switch PTB-3 into a kind of compatibility mode by adding the following command at the very top of your script:

% Enable compatibility mode to old PTB-2:
Screen('Preference', 'EmulateOldPTB', 1);

This will emulate the drawing model of PTB-2

  • All drawing commands will be directed to the visible screen immediately, without need for the Screen('Flip', ...) command.
  • The Screen('WaitBlanking', ...) command gets re-enabled to allow synchronization of Matlab to the vertical retrace.

This allows to run many old PTB-2 scripts without further modifications. However, there may be subtle differences between drawing commands on PTB-2 and PTB-3, so this approach does not guarantee backwards compatibility.

Although PTB-3 is not backwards compatible, there are many similarities between it and earlier versions. It is not too hard to convert old programs, and the ever-growing set of new demos provides examples.

Some of the comments and help text in PTB-3 explain differences between it and older versions, but at this point we are trying to streamline these in the interests of clarity.

Psychtoolbox 64-Bit support

Q: Does Psychtoolbox work with 64-Bit versions of Matlab or Octave?

A: Yes.

In fact, 32-bit support is no longer available in current Psychtoolbox releases, except for 32-Bit Octave for Linux on Debian/Ubuntu systems, but only in the releases provided by the NeuroDebian project and by upstream Linux distributions. Also for 32-Bit Octave on the RaspberryPi microcomputer under Raspbian.

Psychtoolbox R2015b support

Q: Does Psychtoolbox work with Matlab R2015b?

A: Yes, for Psychtoolbox 3.0.13 and later.

Older versions of Psychtoolbox work with Matlab R2015b almost perfectly, with one exception. If you need advanced OpenGL functionality through the mogl wrapper *so if you're calling glXxx functions directly), you may run into trouble. Code that worked on <= R2015a or Octave fails on R2015b due to incompatibilities. In general many OpenGL functions which return/query data from the system will fail/return bogus results. The OpenGL calls themselves will work, but we have a breakdown in the mex file communicating those results back to Matlab.

E.g. glGenBuffers will always return a 0 handle on 2015b, but 0 is not allowed as a handle when using glBufferData, hence the "invalid operation" error.

In summary, if you need such advanced OpenGL functionality, it is best to use Octave or any Matlab releases < 2015b. To stay informed about this, keep an eye on this issue.


Q: Why does my virus checker complain about the PTB-3 distribution on Windows?

I'm getting complaints about


A: If you see this then you use an outdated version of Psychtoolbox and should upgrade to the latest beta release.

We used to ship the netcat tool (a normal utility that some scanners were allergic to) to submit registration data with the PsychtoolboxRegistration function. This feature that helps us in finding funding is now implemented using pnet.mex.

Textures, Windows, Screens

Q: What's the difference between a texture, a window, and a screen?

See the article FAQ: Textures, Windows, Screens

Explanation of Screen('Flip') timestamps

Q: What timing information does Screen('Flip') return?

See the article FAQ: Explanation of Flip Timestamps

Close stalled full-screen windows

Q: If my script aborts with an error, I'm left with a dead Psychtoolbox window that prevents me from accessing the Matlab command window. How can I close the window in case of an error?

See the article FAQ: Exit a Crashed Screen

Verbosity and Debug Level

Q: How do I control the debugging checks when Screen starts up?

See the article FAQ: Control Verbosity and Debugging

Blue or blank screen

Q: When I call Screen('OpenWindow') my screen turns blue or white and nothing happens anymore. What's wrong?

A: A blue screen used to be the normal behaviour, nowadays it means you use an outdated copy of PTB. Nowadays you should get a graphical splash screen, or a black screen if visual debugging was disabled.

After the splash, the screen switches to your selected background color (as specified in the Screen('OpenWindow') call) immediately, and your script takes control.

Until your first call to Screen('Flip', ...) command to change it the screen stays blank. If it stays blank, your program may be stuck, waiting for something, or it might have terminated normally or abnormally (error).

See FAQ: Exit a Crashed Screen for how to get out of a stalled Screen.

You can disable the startup screen, i.e., replace it by a black display until calibration is finished, by issuing the command Screen('Preference', 'VisualDebuglevel', 3); at the beginning of your script.

See also the previous FAQ on verbosity and debugging.

Black PTB Window

Q: How do I make the initial screen black instead of white?

A: When PTB is first loading (running it's various checks, etc.) it fills the screen with a welcome screen. This can be a problem for experiments that involve dark adaptation, or eye tracking.

To make this initial screen black instead of white, add this call at the beginning of your main experiment code:

Screen('Preference', 'VisualDebugLevel', 1);

Screen captures of stimuli

Q: How do I take a screen shot of my stimuli?

See the article FAQ: Screenshots or Recordings

Image Transparency

Q: How to display images with transparent backgrounds?

A: It is possible in PTB to display PNG images with transparent backgrounds. It requires your image to have an alpha channel.

  • Save your image with a transparent background in PNG format and load it in Matlab.

    [image map alpha] = imread('filename.png');
  • image is the usual [m x n x 3] RGB image matrix

  • alpha is an [m x n x 1] matrix with the transparency (alpha) channel
  •  Stack the alpha layer on top of image as a 4th layer imagename(:,:,4) = alpha;
  •  You need to enable alpha blending, so the tranparency layer gets used, 

    Screen('BlendFunction', win, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);

Frozen Matlab Figure Windows

Q: How can I update Matlab figures during the experiment?

A: Use the drawnow Matlab command whenever you want Matlab to update it’s figure windows. This forces Matlab to redraw the handle graphics.

It is NOT recommended to use drawnow inside time critical loops (e.g., where stimulus presentation is performed).

Collect responses while animating

Q: How can I collect responses while repeatedly presenting/updating visual stimuli?

A: In general use any down time between drawing the stimuli and calling Screen('Flip') to check the keyboard state. (NB: polling the keyboard is one of the less accurate methods to measure reaction times. If accuracy matters, you should use a response box.)

Sample code is below

% Draw target, etc, then
[targetFlipStart, targetStimOnset] = Screen('Flip', window);

% Set a stop time x seconds from the execution of this line and poll the keyboard/input device until then
stop = GetSecs + x;
while GetSecs < stop
    [keyIsDown, secs, keyCode] = KbCheck;
    if keyIsDown
        break; % End the while loop
    WaitSecs(0.01); % It is a good habit not to poll as fast as possible
RT = secs - targetStimOnset;

Duplicate Offscreen Window

Q: How do you create a duplicate of an offscreen window?

A: You would first create an empty offscreen window of the same size and color depth as your original offscreen window, then copy the original windows content into the new window:

Let origWin be the offscreen window you want to duplicate, then

duplicateWin = Screen('OpenOffscreenWindow', origWin);
Screen('CopyWindow', origWin, duplicateWin);
% duplicateWin is a copy of origWin.

Multiple Offscreen Buffers

Q: Can offscreen windows (created with OpenOffScreenWindow) have multiple buffers?

A: No. It wouldn't make sense to have multiple buffers, as this concept refers to what is currently being shown on the display. Offscreen windows are not shown on the display but rather hold data that may be moved to a buffer of a display window.

Global Setting of TextSize

Q: Is there any simple way to set TextSize (or other such parameters) for all windows/screens?

A: No. You have to set it for each window via the Screen('TextSize', win, ...) command. But that's not much work, given that most people have at most two windows.

Performance and Timing tips

Q: How can I improve the drawing performance and timing of my PTB-3 code?

See the article FAQ: Performance Tuning

10-bit DACs

Q: Is it possible to get 10-bit DAC resolution with PTB-3?

See the article FAQ: 10-bit DACs

10-bit framebuffers

Q: What is the status of 10-bit frame buffer support?

See the article FAQ: 10-bit framebuffers

High Performance Video Playback

Q: How can I play back high-resolution high-speed video?

See the article FAQ: HD Video Playback

How to resolve GStreamer problems:

Q: When trying to play movies with GStreamer, Matlab crashes or gives Bus errors! What can I do?

A: Some video codecs can cause bad interactions between Matlab’s JavaVM and GStreamer on Microsoft Windows. This is currently not a solvable problem, but various workarounds are possible:

TTL triggers

Q: How to send TTL triggers?

A: For a long time, the parallel port was used for sending triggers and it is possibly still the best option regarding timing. However, parallel port solutions are very platform-dependent and might not be available anymore anyway. So the next best is to use one of the numerous USB digital I/O interfaces (see below).
If only one or two trigger lines are needed, one can get away with a serial port and toggling the control lines using IOPort. However, the electrical levels of a native serial port are not TTL-compatible, which normally is also true for USB-to-serial converters.

Issues with Windows

Q: Are there known issues with Windows Vista / 7 and how to resolve them?

See the article FAQ: Vista and Windows 7

Clock and Timer problems with Windows

Q: Psychtoolbox and GetSecsTest tell me my clock and timers are broken, What gives?

See the article FAQ: GetSecs Test Fails

Mac 10.10 VBL Sync Issues?


WARNING: Couldn't compute a reliable estimate of monitor refresh interval! Trouble with VBL syncing?!? ! PTB - ERROR: SYNCHRONIZATION FAILURE ! ----

Try the following hack:

Switch resolutions within System Preferences --> Display Panel (Scaled). Select a different resolution then reselect the required/native resolution. Repeat this hack with each system restart.


Add to the FAQ

Q: How do I add a FAQ & answer to this list?

A: It's pretty easy. Just follow the steps below.

  • First you need to create a free GitHub account and log in to edit
  • Secondly, this is a place to give answers, not to ask questions. Use the Forum for that. A FAQ is a place to list commonly requested answers, so they do not need to be repeated time and time again.
  • Next, go to the FAQ page (you are already here probably) and click the Edit button

  • You can type short entries that keep coming up directly here on the FAQ page.

    Our format looks like this

    ##### Header for the FAQ Item
    **Q:** The question in question
    **A:** The succint answer
  • Longer explanations and example scripts should go on a new page and get linked from the Cookbook

  • You can choose your preferred markup syntax, but Markdown is preferred.