VideoToolbox

Psychtoolbox

Eyelink

Tips

Home

Intro

Tutorial

Download

Mac OS9

OSX

Win

USB

Questions

Wiki

Forum

Help

Psychophysics Toolbox

Psychophysics Toolbox for Windows

Our goal is for both Mac and Win versions of the Psychtoolbox to work identically. Your scripts should execute on both Mac and Win with the same results. Many improvements have been made to Psychtoolbox Win since the alpha releases. The remaining differences between the Mac and Win Psychtoolboxes are of three kinds:

1. Omissions. Not all Psychtoolbox functions implemented on Mac have yet been implemented on Win. For a list of Mac features and functions not yet implemented on Windows look here.
2. Bugs. The Win Psychtoolbox is new. Heavy use by many users, an active forum, and a large test suite (PsychTests) has polished the Mac version to be nearly bug-free. It's likely that there are some latent bugs in the Win Psychtoolbox that will appear when it's used in earnest by many users. Additionally, there are some known bugs that we haven't yet eliminated. If you discover a new bug please report it to the forum. When a particular bug is fixed, we often post an updated file to the forum, for users that don't want to wait for the next full release.
3. OS Differences. A few differences between the Mac and Windows computers propagate to the Psychtoolbox. For example, Macs have a single mouse button while Windows PCs have several; GetMouse always returns a vector with one element per button. Help for Psychtoolbox functions documents any such differences between Win and Mac. For tips on how to write scripts compatible with both Mac and Win Psychtoolbox look here.

---

Version numbers

• The Psychtoolbox version is a three digit number, e.g. 0.01, but trailing zeroes may be omitted, e.g. 0.0. We bump the first digit for a major change in functionality. We bump the second digit when new features are added. We bump the third digit for each new release, mostly bug fixes. Don't be shocked if you find a bug; do tell us so we can fix it. The Win and Mac version numbers are in synch, but the Win version is currently a beta release.
• We announce new releases. If you would like to be added to the mailing list (only a few messages per year), send email to psychtoolbox@psych.nyu.edu.

Win: System requirements

The Win Psychtoolbox is developed on Windows 2000 in Matlab 6. We expect it to run under other versions of Windows and Matlab, but it has been less thoroughly tested on those. You'll need:

• Pentium CPU or greater with at least 128 MB of RAM.
• Video card that supports DirectX.
• Windows 95 or greater, such as Windows 95, 98, Me, NT, 2000 or XP.
• Direct X 3 or greater.
• Matlab version 5 or 6.
• Win Psychtoolbox version 2.5 or greater.

Matlab and the Psychtoolbox can run in very little memory, and inform you if they need more, but most users will want to create and show movies, which takes lots of memory, roughly 1 MB per frame. Memory's cheap, so splurge and buy yourself a gigabyte for a couple hundred dollars, e.g. http://www.macresource.com/mrp/ramwatch.shtml

Win: Supported hardware

• Eric Angel reports that the DOME Md2 video card provides no way to detect or wait for vertical blanking.

Backwards incompatibilities

• Changes that may break old programs are colored aquamarine.

Writing portable scripts, compatible with both Mac and Win

Most Psychtoolbox functions are identical on both Mac and Win. Many existing scripts that execute on one operating system will execute on the other with no modification.

Though some Psychtoolbox functions behave differently on Mac and Win, they can still be used in scripts compatible with both Mac and Win Psychtoolboxes. In creating a single script that executes on both Mac and Win, it's sometimes helpful to use the built-in Matlab variable "computer" to identify the run-time environment, branching to platform-specific function calls according to the value of 'computer'. For example, the fields of the structure returned by the Psychtoolbox call Screen('Computer') are different on Mac and Win. Despite this difference, the following script uses Screen('Computer') to display the version name of the operating system on either Mac or Win:

description=Screen('computer');
if strcmp('PCWIN',computer)
    fprintf('%s\n',description.OSName);
elseif strcmp('MAC2',computer)
    fprintf('%s\n',description.system);
else
    error('Unknown operating system.');
end

Here's another way to write the same thing, which you may find easier to read:

description=Screen('computer');
switch(computer)
case 'PCWIN',
    fprintf('%s\n',description.OSName);
case 'MAC2',
    fprintf('%s\n',description.system);
otherwise,
    error('Unknown operating system.');
end

[If you know C, note that the syntax of Matlab's "switch" command differs from that of the corresponding C statement. In Matlab there is an implicit "break" before each "case" statement.]

Using "computer" is an ugly hack, but you'll rarely need it. For example, GetMouse returns a vector with one element for each button on your mouse. Win mice have several buttons, whereas Mac mice generally have only one. The best way to program for this is to deal with the general case of 1 or more buttons:

[x,y,buttons]=GetMouse;
if any(buttons)
    fprintf('You''re pressing a button.\n');
end
if buttons(1)
    fprintf('You''re pressing the primary button.\n');
end
if length(buttons)>=2 & buttons(2)
    fprintf('You''re pressing the second button.\n');
end

When Mac and Win differ, you may sometimes settle for the least common denominator, but it's often easy to automatically select the best available option in each particular environment. For example, Win and Mac operating systems ship with different font sets, and this is often further customized by the computer user's idiosyncratic additions. We like the Microsoft fonts Arial and Verdana, which are available on any computer in which Internet Explorer has been installed. However, if you really care what font you get, the robust portable solution is to try several font names, using TextFont to test each attempt, until you find a match:

for font={'Arial','Geneva','Helvetica','sans-serif'}
    Screen(w,'TextFont',char(font));
    match=strcmp(font,Screen(w,'TextFont'));
    if match
       break;
    end
end

See FontDemo for a complete example.

Win vs. Mac differences

1. Bytes
   • Mac and Win versions of Bytes accept different commands. See "help Bytes".
2. GetChar
   • Returns the last character typed.
   • Mac: also, optionally, returns a "when" structure specifying when the key was struck and other info.
3. GetMouse
   • Returns a "buttons" vector with an element for each mouse button.
   • Mac: currently limited to one button.
4. Screen 'Computer'
   • Mac and Win return structures with different field names. See "Screen Computer?".
5. Screen 'OpenWindow'
   • Mac: Onscreen windows may be any size. You can use any number of displays at once.
   • Win: Currently, the onscreen window is the entire screen; the rect argument is ignored. You can use only one display.
   • Offscreen windows may be any size, and are unlimited in number.
6. Screen 'TextFont'
   • Mac and Win operating systems ship with different fonts. Use Screen TextFont to select from available fonts.
7. File paths:
   • Win and Mac file systems use different file path name separators, the colon ":" on Mac and backslash "\" on Win. To write scripts compatible with both Mac and Win versions of Matlab use the built-in Matlab file and path-specification functions FULLFILE, FILESEP, and PATHSEP.
8. End of line:
   • Text files, including Matlab M files, contain invisible characters to mark the end of each line of text. By convention, Mac text files use the CR character to mark the end of lines and Win text files use the two-character sequence CR LF. Matlab 5 for Mac and Matlab 6 for Win can understand either line ending marker, however Matlab 5 for Win does not understand the Mac end of line characters.
9. Keyboard shortcut to halt:
   • Mac: Command-period halts any program. (Type a period "." while holding down the apple-cloverleaf "command" key.) If the command-period is intercepted by any of our MEX files, all of Screen's windows will be closed, and the cursor will be shown, to allow you to work normally in the Matlab Command window.
   • Win: Ctrl-C halts any program. (Type a "c" while holding down the "Ctrl" key.) If Ctrl-C is intercepted by any of our .dll files, the .dll file should exit, returning the user to the Matlab command window. However, this feature is not yet supported by all the Win Psychtoolbox functions. Additionally, Ctrl-C fails to halt programs executing in a Matlab process run with the "nojvm" option. To halt a runaway Psychtoolbox script in Win Psychtoolbox you might resort to the Windows Task Manager to kill the Matlab process. (Use Ctrl-Alt-Delete to open a window from which you can start the Task Manager.)
10. Keyboard shortcut to bring forward the command window:
    • Mac: Command-zero brings the Matlab Command window forward. (Type a zero "0" while holding down the apple-cloverleaf "command" key.)
    • Win: Ctrl-Alt-Delete allows you to launch the Windows task manager, which reduces the Psychtoolbox onscreen windows when it opens. (Simultaneously press the "Ctrl", "Alt", and "Delete" keys.) There also simpler ways of reducing the Psychtoolbox window which are specific to particular versions of Windows:
      • Windows 2000:
        • Alt-Esc will minimize the Matlab Psychtoolbox Screen window.
        • Alt-Tab will minimize the Matlab Psychtoolbox Screen and step through a list of running applications, allowing you to choose which to bring to the foreground.
      • Windows NT: ??
      • Windows ME: ??
      • Windows 95
      • Windows 98:
        • Alt-Tab will minimize the Matlab Psychtoolbox Screen and step through a list of running applications, allowing you to choose which to bring to the foreground.

If you discover additional differences, please report them to the forum.

Win: Missing Psychtoolbox functions

1. CopyImage and PasteImage
2. Debugger
3. DoNothing is a dummy mex routine used to measure Matlab's overhead.
4. EventAvail
5. fs and FileShare
6. IccProfile
7. JOYSTICK not included in the 2.5 release because of a reported bug in loading the extensions.
8. PsychSerial 'CTS', 'DTR', 'Ports', 'Params'
9. Screen copy mode values: 'srcOr', 'srcXor', 'srcBic', 'notSrcCopy', 'notSrcOr', 'notSrcXor, 'notSrcBic', 'srcCopyQuickly', 'addOverQuickly', 'addOverParallelQuickly', 'mulOverQuickly'
10. Screen 'Dialog'
11. Screen 'GlobalRect'
12. Screen 'PeekBlanking'
13. Screen 'Preference' Mac-specific preferences available only on Mac: 'Backgrounding', 'GetSecsTest', 'UseNewHideMenuBar'
    
14. Screen 'Process'
15. Screen 'Resolutions', 'Resolution', and 'ResolutionQuickly'
16. Screen 'SaveAsEps'. Use SaveAsEps.m instead.
17. Screen 'Videocard'
18. Showtime (The Psychtoolbox function formerly known as QT)

If you discover additional omissions in Win Psychtoolbox please report them.

Win: Missing MATLAB functions

1. Speak speaks a string argument using a synthesized voice.

Win: Psychtoolbox bugs

1. Screen rejects a pointer to the Matlab command window. For example, Screen 'WindowToFront' will fail if passed a pointer to the Matlab command window.
2. Screen('Gamma') implemented but not tested.
3. Screen('GetImage') is disabled when the pixelsize is 16 bits.
4. Screen('GetClut') accepts only a window pointer, not a screen number.
5. Screen('PixelSizes') fails on some computers, reported by Emanuela Bricolo and reported by Julie Martin-Malivel.
6. Screen('PsychTableCreator') sometimes crashes.
7. Ctrl-C is the Matlab keyboard break command that immediately exits a script and returns to the Matlab command prompt. Psychtoolbox functions should detect this key combination and exit, but many fail to do this.
8. Dan Matza-Brown reports that the 3DLabs WildCatII board does not synch using the Screen('WaitBlanking') command.
9. Eric Angel has reported that the DOME Md2/PCI video card does not synch using Screen('WaitBlanking'). WaitBlanking uses the DirectX method WaitForVerticalBlank which is unsupported by the DOME video driver.
10. Windows XP will not drive some DVI displays in 8-bit pixel size mode.
11. WhiteIndex returns the value for a magenta in 16 bit mode. Reported here by Ted Wright.
12. Components of color vector arguments are misordered on some displays. Reported here.
13. ScreenTest reports impossible CopyWindow copy rates on some systems.

If you discover a bug, please report it to the forum.

Win: Changes

Version 2.55 (not yet relesed)

1. WaitSecs truncated the timing interval to seconds. This has been fixed. Before the 2.55 release you can get the new WaitSecs here.
2. The DescribeComputer, ScreenTest, and Screen('Computer') reported the DirectX version as 0.0. This has been fixed.
3. WhiteIndex and BlackIndex failed for 24-bit color mode.This has been fixed.
4. Improved Ask.m as suggested by Paul Thiem: added an example (and better argument checking) to make it clear that replyFun must be supplied as a string and rectAlign1 as a value.
5. Added defaults for all arguments to GetEchoString: .

Version 2.54 (20 February 2004)

1. Added SpriteDemo.m (formerly "TargetDemo"), which animates a moving sprite. It conserves offscreen windows.
2. Fixed: MaxPriority returned 2 for GetMouse and GetClicks, it should return 1.
3. Fixed: Screen misinterpreted the color argument at pixel depth 16. One consequence of this bug was that the value returned by WhiteIndex when passed as a color argument would not produce a white screen, which was reported by Erik Chang and Avniel Ghuman.
4. Screen could not find the Matlab command window in the Student Edition of Matlab. This has been fixed.
5. Recompiled ActiveWire mex file with latest ActiveWire libs. The Psychtoolbox ActiveWire command should now work with the latest AcriveWire drivers.
6. PsychSerial modernized to more closely resemble the Mac version.
7. Added Screen preference "DacBits". This is for compatability with Mac version and returns the number of bits the Windows Psychtoolbox supports and not the number of bits which your video card supports.
8. Fixed Screen "FrameRect" bug where it failed to use the correct default rect size.
9. Removed dependancy on the dsetup.dll file.
10. LoadClut command added.
11. ColorTest PsychTest fixed.
12. Fixed a bug in ScreenTest in calculating the copy rate.
13. Fixed a bug in the Screen 'Rect' command where it failed if passed a screen number.
14. Improved WatSecs to use the high-precision multimedia timer instead of the tick clock.
15. Converted Source to Microsoft Visual C .net.

Version 2.5 (17 June 2002)

1. Most PsychDemos and some PsychTests now work on Win. Those routines that depend on features not yet implemented on Win detect the Windows OS and issue an error message stating that they are not yet ready for Windows. Type "help psychdemos" or "help psychtests" for a table of the current status.
2. ActiveWire functions for control of the ActiveWire device.
3. Fixed: All drawing to 8-bit offscreen windows ignored the color value specified.
4. Fixed: Screen caused a segmentation fault if the onscreen window was closed while offscreen windows were still open.
5. Fixed: Screen 'Preference?' was causing a segmentation fault.
6. By default, Win Screen 'Preference' 'IgnoreCase' is now set to true as it is on Mac.
7. Screen 'GetMatlabWindow' now works in Student Matlab.
8. Screen 'Preference' has been enhanced to give clearer error messages and to accept more preference names.
9. Screen 'CopyWindow' and 'PutImage' previously accepted copyMode 'srcCopy' or 'srcCopyQuickly'. The copy mode 'srcCopyQuickly' is now disabled on Win. Screen detects when a Mac-specific copy mode is given and issues an error message.
10. Added new subfunction: Screen 'FillArc'.
11. The "buttons" return argument from GetMouse is now a vector with one element for each mouse button.
12. Removed redundant GetButton function. Use GetClicks or GetMouse instead.
13. GetMouse.mex no longer supports this obsolete usage: xy = GetMouse([windowPtrOrScreenNumber])
    where xy is a 1x2 vector containing the x, y coordinates.
14. Fixed incompatibility in GetMouse with some versions of Matlab and Windows.
15. Fixed: GetClicks failed to detect clicks if called after Screen was used to change the pixel depth.
16. Fixed: GetClicks would detect only single and double clicks. It now detects n clicks, like the Mac version.
17. GetSecsTick returns an estimate of the step size of the GetSecs timebase, as an aid to writing platform-independent code.
18. Fixed a bug in WaitSecs which caused it to wait indefinitely when passed a negative value.
19. Fixed a bug in GetSecs which could cause it to spontaneously revert to using a low-precision system ticks timer.
20. FlushEvents.dll has been added.
21. Fixed: CharAvail would report a character available but a subsequent call to GetChar would not return a character.
22. KbName now correctly interprets Win keycodes.
23. Fixed: KbCheck would report keys as pressed after they had been released.
24. Snd.m on Win has been modified to behave like Snd.mex on Mac. Both now accept row vectors specifying the waveform, have the same default sample rate, and accept the same command strings.
25. Fixed a bug in CopyText where the separation between rows in a matrix was not preserved when copying the matrix to the clipboard.
26. Fixed a bug in CopyText where it failed under Student Matlab because it could not find the command window.
27. Renamed Serial.mex to PsychSerial.mex to avoid a name conflict with the Serial function built into Matlab 6.
28. Improved SaccadeDemo.m and renamed it "FlickerTest.m." (The name has been changed on both Mac and Win but FlickerTest has not yet been modified to run on Win.)
29. Redid interface to PR650 to use generic SERIAL rather than a specialized CMETER mex file. Tried to improve logic for setting/checking PR650's synchronization feature. Added ability to read serial port name from a file. Tested in a limited manner on the Mac, not on Win.
30. MaxPriority.m has been modified to work on Win.

Version 2.45 (1 August 2001)

1. Added routines XYZToLjg, LjgToXYZ to PsychColorimetric. These convert back and forth between the OSA UCS Ljg coordinates and XYZ (10 degree).
2. FitWeibTAFC and related functions: Better initialization of parameter alpha when it is not passed explicitly. This should improve convergence of the numerical search routines. Passing good initializing values explicitly is recommended if you can determine them for your application. Thanks to Duje Tadin for pointing out the need for this improvement.
3. FitCumNormYN: Fixed bug that caused execution failures for certain data sets. Thanks to Keith Schneider for identifying the bug and the fix. See psychtoolbox forum message: http://www.yahoogroups.com/message/psychtoolbox/262.
4. PsychCal: Various changes and improvements to the calibration routines, many of them in an attempt to make them more generally compatible across different graphics cards and platforms. This effort will be ongoing.
5. Implement a PsychCalLocalData folder that lives outside of toolbox folder. Calibration routines read from and write to this folder if it is there. This makes it easier to update the toolbox without wiping out your calibration files. The folder in the toolbox, PsychCalData, has been renamed PsychCalDemoData.
6. Fix help text in Rect functions to indicate that one should type "help PsychRects" for more information.
7. Modified PsychtoolboxVersion to make it compatible with Windows. It's behavior in Mac OS is unchanged.
8. Added SetMouse, which was missing.
9. Compiled a version of Screen without the test call to "GetMatlabWindow." Note that Screen subfunctions 'MatlabToFront' and 'GetMatlabWindow' will not work in the student version.
10. Fixed screen subfunction 'GetImage' which returned incorrect values when passed a rect argument smaller than the window's rect.
11. Returned support for screen subfunction 'WaitBlanking'
12. Fixed bug where screen(...'OpenWindow'...) would incorrectly report use of an invalid pixel depth if the window size is less than the screen size.
13. Fixed bug where Screen 'Rect' would not return correct values for an offscreen window.
14. Fixed bug where FillRect and other drawing commands issued the warning "could not select
    Palette for use" if the window in which you were drawing was an offscreen window
    which had been opened using a screen number instead of a window pointer.
15. Screen(..'PixelSize'..) now correctly returns the pixel depth for all
    windows.
16. Bug fixes to Screen 'TextFont', 'OpenOffscreenWindow', 'TextSize', 'DrawText'. TextDemo.m now works. Details here and here.
17. Screen 'OpenWindow' now correctly initializes to specified color.
18. Screen bugs in 'PutImage', 'GetImage' and drawing commands such as 'FillRect' when used with 32-bit pixels have been fixed. Details are here.
19. Screen 'TextSize' returned values with inverted sign. This has been fixed.
20. Screen 'FrameRate' implemented.
21. Screen 'PixelSizes' implemented.
    

Version 2.44 (7 August 2000)

1. ScreenDemo runs on at least one Windows machine without crashing. Not all output is visually as desired, so the demo illustrates both functionality and bugs in the Windows version.
2. Changed SERIAL.dll to no longer implicitly append an EOL (end of line) character on write. This behavior was coded into the original version, as a convenience for the user, but was too clever. Now, if you want an EOL, you must explicitly append your desired EOL character at the Matlab level. So now you should write something like this
        SERIAL('Write',port,['Hello world.' char(10)])
   or
        SERIAL('Write',port,['Hello world.' char(13)])
   depending on whether the hardware you are talking to wants a linefeed (ASCII 10) or a carriage return (ASCII 13) as its EOL character.

Version 2.40 (24 January 2000)

1. Integrated with Mac version. Rough alpha quality. It has serious bugs.
2. Fixed bugs with DrawText etc. that resulted in CLUT glitch.

Version 0.05 (5 May 1999)

1. Small changes for compatibility with Matlab 5.3.

Version 0.04 (10 April 1999)

1. Serial port read routines now work, fixing CMETER MEX file.

Version 0.03

1. Fix bugs introduced in 0.02.

Version 0.02

1. Should be more stable.
2. Better accuracy in count returned by PeekVBL
3. M files added to provide help, modified to be Windows-compatible.
4. Minor changes.

Version 0.01

1. Added a missing file (ScreenDrawLine.cpp) to the archive.
2. A short bug list is included in the archive, at the end of the readme001.m file.
3. Minor changes.
   

Credits

• The Windows version is based on the Mac version. See credits for the Mac version.
• Xuemei (Mei) Zhang created the alpha version of the Psychophysics Toolbox for Windows.
• Elliott Waldron did the initial development of PsychTable code for Windows and other enhancements; early testing. He also integrated Mei's work with the Mac version.
• Allen Ingling fixed the DrawText bug and released versions 2.45 and 2.5 updates.
• Jerry Tietz helped with SERIAL and CMETER.
• Peyma Oskoui tested a pre-alpha version of the toolbox.
• Russell Iimura helped with debugging.
• Christian van den Branden Lambrecht helped with debugging.
• Andy Patti helped with debugging.
• Sophie Chantrenne provided sample code to open DirectDraw windows.
  

48567 visitors between 20 March 2000 and October 4, 2006.

David Brainard, Denis Pelli, Allen Ingling
psychtoolbox@yahoogroups.com
Updated