Clone this wiki locally
- 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?
- How can I collect responses while repeatedly presenting stimuli?
- 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 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
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
'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).
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 end WaitSecs(0.01); % It is a good habit not to poll as fast as possible end 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:
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
...) 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 1a or method 1b (incl. Octave support) or method 2.
- 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.
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.