Don't be shocked if you find a bug. Do tell us so we can fix it, but first please execute the UpdatePsychtoolbox command to make sure that you have the most recent (and most bug-free) release. Perhaps your bug has already been fixed. Bugs get fixed in the 'beta' (i.e. current) branch of PTB.
Report your bug on the Psychtoolbox issue tracker on Github. You need to create a free account there.
The ideal bug report includes not only a terse description of the problem, the following items help to get to the bottom of the problem because PTB runs on so diverse setups
- Output of >>PsychtoolboxVersion
- Which platform (Mac OS X, Windows XP/Vista/7, Linux, …)
- Which Matlab or Octave release and architecture (32- or 64-bit)
- A minimal code snippet that exhibits the bug you found
- Warnings and Errors that were printed to the console (please read them carefully)
- Hardware setup and relevant driver versions
If you issue the command Screen('Preference', 'Verbosity', 10); before running the troublesome script, PTB will create much more output to the Matlab console, which will also aid in debugging.
More things to consider:
- If PTB aborts with error messages or outputs lots of "PTB-Warnings", please read them carefully, think about them, also read help files and documentation referenced by that messages. These texts weren't written because we like writing so much, but in order for you to read them and to speed up the troubleshooting procedure.
- If your bug is related to visual stimulation and verified to happen with our demos as well, check if the device drivers for your graphics card are up to date. Each manufacturers website has some download or support section where you can download new drivers. A driver update can fix many mysterious bugs. On Mac OS X, driver updates are shipped as part of operating system updates, so keep your OS up to date.
- Use the search function on the PTB forum and Google search to check if somebody else had similar problems, maybe a solution is already available.
- Run a few of the demo scripts in the Psychtoolbox/PsychDemos subfolder to see if problems only arise in your code or also in our demo code. In the former case it's more likely a bug in your code and you can aid diagnosis by reporting how your code behaved vs. how our code behaved. E.g., if a Quicktime movie fails to play properly with your code, check if it plays with our PlayMoviesDemoOSX script.
- Check if the FAQ section of this Wiki has to say something helpful about your problem or related problems.
- The online document How To Report Bugs Effectively is a great guide on how to report a potential bug in an effective way - one that is likely to facilitate a quick bugfix. Read it! Taking a few minutes to read and follow it will likely save you hours, days or weeks of waiting for help or a bug fix. It applies to pretty much any technical support forum, not only Psychtoolbox.
- Stimulus timestamp vbl, as reported by vbl=Screen('Flip', win), can be wrong (one video refresh too early) on Windows PCs with Intel GMA 945 and related onboard graphics chips when high precision timestamping is enabled. This is due to a driver-/ or hardware-bug in the Intel chips, but we don't have a work-around implemented in PTB yet. If PTB detects this problem, it disables high precision timestamping. The command Screen('Preference','VBLTimestampingMode',-1); at the top of your script would manually disable high precision timestamping as well. MK, found 16.12.2006, workaround in beta since 22.1.2007.
- The Nvidia Quadro FX 3000 has trouble switching to frame sequential quad-buffered stereo and back with some drivers under WindowsXP. This is a driver bug in the wglChoosePixelFormat() call when requesting stereo pixelformats, as well as an independent bug in the drivers stereo logic when shutting down stereo mode. PTB detects this and enables automatic workarounds to resolve the issue. As a side-effect of the workarounds, automatic full scene anti-aliasing via multiSample parameter of Screen('OpenWindow'); is not available in stereo mode, and graphics performance may be reduced in stereo mode due to allocation of an unneeded depth buffer to work around driver bugs. MK 8.6.2007.
- Beamposition queries are broken on Nvidia Geforce 8800 GTS under WindowsXP in some driver versions. Driver bug. Workaround is the same as for the next bugs below (Radeon 9600 beampositions broken): MK 8.6.2007 -- Workaround in PTB beta.
- Beamposition queries are broken on some ATI cards under WindowsXP in some driver versions. Driver bug. Workaround is the same as for the next bug below (Radeon 9600 beampositions broken): MK 8.6.2007 -- Workaround in PTB beta.
- The ATI Mobility Radeon 9600 on WindowsXP in some notebooks with some drivers has broken beamposition queries, which can lead to wrong timestamps being returned by Screen('Flip');. This is a driver bug. The current PTB beta may automatically detect the problem and fall back to a lower precision timestamping mechanism. If it doesn't do that, you can enforce it via a call to Screen('Preference', 'VBLTimestampingMode', -1); at the top of your script. MK 8.6.2007 -- Workaround in PTB beta.
- Some ATI and NVidia cards+drivers crash Matlab when trying to use OpenGL for Matlab und Windows XP. These are driver bugs. Workaround: Add Screen('Preference', 'ConverveVRAM', 256); to the top of your scripts and retry. If it still crashes, add a Screen('Preference', 'ConverveVRAM', 8); to the top of your scripts instead to disable OpenGL context isolation. Will not crash anymore, but make debugging and development of OpenGL4Matlab code harder for you. MK 8.6.2007, updated 7.5.2008, now also affects recent NVidia hardware :-(
- The ATI Radeon X800 creates severe tearing artifacts when running in stereomode 1 (frame sequential mode for shutter glasses) under MacOS-X 10.4.8, rendering this mode of operation virtually useless, although an older ATI Radeon 9200 works properly in the same configuration. Reported in forum message 5221. This is most likely an Apple/ATI driver bug. No fix known, bugreport filed to Apple by Stephane Rainville. MK 28.10.2006.
- Screen('GetImage') with its default setting or setting 'frontBuffer', i.e. reading from the front buffer, doesn't work properly on the Intel GMA 950 on MacOS-X as of version 10.4.8. Reported by Kevin McKenzie in forum message 6016. This is a driver bug. Read from the backbuffer instead, as demonstrated in forum message 6019.
- Screen('FillRect'), when used without a rectangle argument, or a rectangle that's the size of the window, will not obey to any alpha blending settings. Reported in message 6224 on the forum and confirmed in message 6231. As explained in the latter message, for filling full-screen rectangles, Screen uses the glClear() call which is meant for clearing the backbuffer. Clearing the backbuffer is optimized on many OpenGL implementations, so it can be a bit faster. Not obeying the blend settings was probably an unintended side effect, because blending was implemented later. In the earlier versions of PTB-3, the 'FillRect' command was the only way to select the background clear color. A relatively simple solution to make 'FillRect' use blend settings is to use 'FillRect' with a rectangle argument that's just a bit larger (or smaller) than the window size, so, e.g. Screen('FillRect', window, [255 0 0], InsetRect(Screen('Rect', window), -1 -1)).
- KbDemo. Keystrokes pass through the demo and into the command window (or whatever window has focus). Neither Roy nor I could figure out how to fix this. Noted by DHB, 10/11/06.
- This is an unfortunate "feature" of current Matlab. You can disable keyboard input to Matlab's windows by adding a ListenChar(2) command at the beginning of your script and a ListenChar(0) command at the end of your script. If your script should exit without calling ListenChar(0), Matlab will be left with a dead keyboard until you press the CTRL+C key combo. Fixed in V3.0.8 beta and stable. MK, 10/16/06.
- Screen functions for setting / getting gamma tables only accept a screenid, not a windowhandle, although the online help states they should accept both. MK 25.10.2006. Fixed in developer branch. - Modified help text to match reality.
- moglClutBlit fails on ATI hardware with a "shader compilation failed" error. Erik Flister (some time in November). Fixed in beta sometime end of November 2006 (MK)
- Screen('DrawText') function: Provided (x,y) position denotes top-left corner of text string to draw, not the position of texts baseline as in PTB-2. Denis Pelli (some time in November). Fixed since 22.1.2007 in beta: New optional flags to DrawText and new Preference settings allow to switch between old behaviour and the new behaviour. (MK)
- Screen('FrameRect') function doesn't draw correct corners when 'penwidth' parameter is greater than its default value of 1. Fixed in beta as of 22nd of May 2007.
- Screen('DrawText') function on Windows doesn't draw text in the requested size, but at some smaller size (approx. 2/3 of requested size?). MK 27.10.2006. Fixed in PTB beta as of 27th November 2007. (MK)