Skip to content

FAQ

Jump to bottom Edit New page
Thad Czuba edited this page Dec 30, 2020 · 25 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 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.

Virus?

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 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('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:

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

Managing real-time [RT] priority

For time critical code, use the Priority([newLevel]) command to raise Matlab to realtime-priority mode. Select the newLevel value via newLevel = MaxPriority(...) to get the highest suitable priority for your needs in a portable, operating system independent way.

Linux

"The 'nice' value is only used for non-realtime scheduling, to distribute cpu time fairly (on average) across non-realtime processes. Realtime [RT] scheduling plays by different rules, and higher Priority() value means higher priority." -- mario

  • tl;dr: It's safest to trust that PTB's Priority() implementation will provide the most effective & reliable solution, and to leave OS priority settings untouched.
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?

Problem:

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.

https://groups.yahoo.com/neo/groups/psychtoolbox/conversations/topics/18518

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.

This wiki is complementary to the main website at http://psychtoolbox.org
Please feel encouraged to edit these pages and add helpful content. Take care.

Clone this wiki locally