Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
- How do I get PTB-3?
- Is PTB-3 backwards compatible with PTB-2?
- Does Psychtoolbox work with 64-bit versions of Matlab or Octave?
- Does Psychtoolbox work with Matlab R2015b?
- Windows: Why does my virus checker complain about the PTB-3 distribution?
- What's the difference between a texture, a window, and a screen?
- What do the timestamps returned by Screen('Flip') mean?
- How do I close a screen window and return to the command line?
- How can I skip the verbose checks that Screen performs
- Psychtoolbox shows a blank screen and then nothing happens?!?
- How do I make the initial screen black instead of white?
- How can I take a screenshot of or record my stimuli?
- How to display images with transparent backgrounds?
- How can I update Matlab figures during the experiment?
- Which function should I use for collecting keyboard (and mouse) input?
- How do I duplicate an offscreen window?
- Can offscreen windows have multiple buffers?
- Can I set TextSize (and other parameters) for all windows/screens?
- How can I try to improve timing and performance of PTB-3 code?
- Is it possible to get 10-bit DAC resolution with PTB-3
- What is the status of 10-bit framebuffers?
- How can I play back high-resolution high-speed video?
- When trying to play movies with GStreamer, Matlab crashes! What can I do?
- How to send TTL triggers?
- Are there known issues with Windows Vista and how to resolve them?
- Psychtoolbox tells me that the clock and timers on my computer are broken! What now?!?
- Mac 10.10 VBL Sync Issues?
- How do I add a FAQ & answer to this list?
Q: How do I get Psychtoolbox?
A: Follow the instructions provided on the website.
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('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?
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 versions 3.0.13 and later.
On older versions of Psychtoolbox, if you needed advanced OpenGL functionality through the mogl wrapper (calling OpenGL glXXX() functions directly), code failed on R2015b due to Matlab bugs. PTB 3.0.13 and later work around those Matlab bugs, so advanced OpenGL functionality works again.
Another limitation is that "matlab -nojvm" mode, ie. running with Java JVM and desktoop GUI disabled, may make Psychtoolbox unusable due to another set of Matlab bugs, which prevent OpenGL from working.
One way to side-step many of these issues caused by Matlab bugs is to use the free GNU/Octave as a free and open-source Matlab replacement instead.
Q: Why does my virus checker complain about the PTB-3 distribution on Windows?
I'm getting complaints about
Psychtoolbox\PsychContributed\.svn\text-base\nc111nt.zip.svn-base\nc.exe Psychtoolbox\PsychContributed\.svn\text-base\nc.exe.svn-base Psychtoolbox\PsychContributed\.svn\text-base\nc111nt.zip.svn-base Psychtoolbox\PsychContributed\nc111nt.zip\nc.exe Psychtoolbox\PsychContributed\nc111nt.zip
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
function. This feature that helps us in finding funding is now implemented
Textures, Windows, Screens
Q: What's the difference between a texture, a window, and a screen?
See the article FAQ: Textures, Windows, Screens
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
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
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');
imageis the usual
[m x n x 3]RGB image matrix
[m x n x 1]matrix with the transparency (alpha) channel
Stack the alpha layer on top of
imageas a 4th layer
imagename(:,:,4) = alpha;
You need to enable alpha blending, so the tranparency layer gets used,
Screen('OpenWindow'); 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).
Keyboard (and mouse) input functions
Q: Which function should I use for collecting keyboard (and mouse) input?
A: PTB offers quite a zoo of keyboard input functions, but which one to use best depends on the application scenario.
See the article FAQ: Processing keyboard input
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:
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
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
Q: Is there any simple way to set
TextSize (or other such parameters) for
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
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
Q: Is it possible to get 10-bit DAC resolution with PTB-3?
See the article FAQ: 10-bit DACs
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
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:
- Try a different operating system. Linux is strongly recommended.
- Use GNU/Octave instead of Matlab on Windows.
- Run Matlab
-nojvmmode, ie. with the
matlab.exe -nojvmcommand line switch.
- For another workaround, click this link to a message on the Psychtoolbox forum.
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.
- USB interface: FAQ: TTL Triggers via USB.
- Parallel port (Linux): method 1 (incl. Octave support) - Recommended in most cases or method 2 or method 3.
- Parallel port (Win 2k/XP/Vista/7): FAQ: TTL Triggers in Windows.
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,
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.
Similar (and worse) errors are present in Mac OS 10.11, 10.12. On 10.10/10.11 almost all NVidia cards are unfixably broken wrt. reliable visual stimulation timing. On 10.12, additionally to the broken NVidia cards, many modern AMD cards are also broken. On 10.13, many (all?) Intel chips are broken as well, so that 10.13 "High Sierra" is essentially unusable for visual stimulation with trustworthy timing.
Use of Apple macOS is therefore strongly discouraged for actual research data collection if you value the quality and reproducibility of your scientific studies.
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.