The VideoToolbox is a collection of two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file "Video synch" discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). (D.G. Pelli and L. Zhang, 1991, Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.) In particular, GetPixelsQuickly and SetPixelsQuickly peek and poke pixels in bitmaps and pixmaps, CopyBitsQuickly copies bit/pixmaps to the screen, and SetEntriesQuickly and GDSetEntries load the screen's color lookup table, all without any of QuickDraw's color translations. High-level routines help analyze psychophysical experiments (e.g. graphing or maximum-likelihood fitting of psychometric data). Assign.c is a runtime C interpreter for C assignment statements, which is useful for controlling experiments and sharing calibration data. This collection has been continually updated since 1991. Many colleagues have indicated that they are using the software in their labs. Documentation is in the source files themselves. Many of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, maximum-likelihood fitting algorithms, and the runtime interpreter are written in Standard C and will work on any computer.
Denis Pelli
Professor of Neuroscience
Institute for Sensory Research
Syracuse University
Syracuse, NY 13244-5290
denis_pelli@isr.syr.edu
CHANGES DURING 12/93:
*Finished upgrade to THINK C 6.01. Nearly all of the VideoToolbox projects appear twice. Files with the extension ".π5" are in version 5 format, and those with the extension ".π" are in version 6 format. THINK C 6 will read either format of project file (converting it to the new format), but THINK C 5 will say "Unknown error ID=-192" if you try to open a version 6 project. In either case, follow the instructions in VideoToolbox.c to produce the precompiled header "VideoToolbox.pre", since it must be produced by your version of the compiler. (Note that the THINK C 5 project files have not been updated since June '93, and are becoming seriously out of date.) I suggest all users of the VideoToolbox upgrade to THINK C 6.01.
*Added GetVersionString.c, based on Joseph Laffey's GetVersStr.c, which gets the application's version from its 'vers' resource. Thanks!
*Added new sections on "HIGH FRAME RATES" and "MORE THAN 8-BIT DACS" to the "Video synch" file.
*Corrected capitalization of all textual references to the commercial "MATLAB" program. Renamed MatlabMain.h to MATLABMain.h and ReadMatLabFile.c to ReadMATLABFile.c. These changes are innocuous because only the filenames were changed and the only change was in the capitalization, which is ignored by the file manager.
*The demo Quitter now goes away quietly if you hit Cancel.
CHANGES DURING 11/93:
*Added new section on "SYNCHING MULTIPLE VIDEO CARDS TO EACH OTHER" to the "Video synch" file.
CHANGES DURING 10/93:
*Updated Quick3 to use either the old CricketGraph or the new CA-CricketGraphIII.
CHANGES DURING 9/93:
*Added PixMapToPICT.c, which saves a section of a PixMap as a PICT file.
*Renamed TranslateText.c to TranslateLinefeeds.c and enhanced it to work with arbitrarily large text strings and to implement macros as inline code.
*Added MATLABMain.h, which should be #included in the main C file of your THINK C MATLAB project.
*Deleted Assign.h, after merging its contents into VideoToolbox.h.
*Added symbol MAC_C to VideoToolbox.h to allow VideoToolbox.h (and many C files) to be compiled even on non-Macintosh computers. MAC_C is true only if the compiler supports the Macintosh extensions to C, e.g. the keyword "pascal".
*Added GetTimeDateString.c.
*Moved Require() from PrintfExit.c to Require.c. Enhanced Require.c to check for consistency of sizeof(int) among Require(), the (possibly precompiled) VideoToolbox.h header, and the Standard C library.
*Renamed the precompiled header from "VideoToolbox" to "VideoToolbox.pre". Think of ".pre" as standing for both "precompiled" and "prefix", which is the window you type the #include command into. You should use VideoToolbox.c to create "VideoToolbox.pre". You may use VideoToolboxMATLAB.c to create "VideoToolboxMATLAB.pre".
*Added PrintWrappedText() and PrintWrappedTextToFile() to BreakLines.c.
*Enhanced Assign.c by adding new routines written by David Brainard: OpenCalFileWrite, OpenCalFileRead, OpenCalFileReadAndCheck, AppendDescriptions, CopyDescriptions, AllocateDescriptions, FreeDescriptions, NumberOfDescriptions, NullDescription, and IsNullDescription.
CHANGES DURING 8/93:
*Enhanced Assign.c to support arrays with an arbitrary number of dimensions (up to ASSIGN_DIMS) and dynamic dimensioning and allocation of arrays based on the assignments that appear in the assignment file. Renamed "Variable" to "Description". Renamed most of the routines. The header file Assign92.h provides for backward compatibility.
*Polished GetWindowDevice(), based on answer from DEVSUPPORT, for better compatibility with future versions of 32-bit QuickDraw.
CHANGES DURING 7/93:
*The MATLAB symbol is now defined as 1 or 0 instead of being defined or left undefined. The advantage of this approach is that the MATLAB symbol can now be used as an argument in an ordinary if statement, which is much more readable than #if.
*All routines now call SwapMMUMode() only if gestalt32BitCapable is true.
*Enhanced GDDacSize() in GDVideo.c to return 8 unless the driver provides a valid gamma table, for compatibility with video drivers, e.g. the Radius PowerView, that return invalid gamma tables.
*TimeVideo 2.5.2 recompiled with new GDDacSize().
CHANGES DURING 6/93:
*Upgraded to THINK C 6.
*Assign.c: Removed all Macintosh dependencies, leaving pure Standard C. Added support for shortDoubleType and arrays of stringType.
*New IsCmdPeriod.c accepts an event record and returns true or false, indicating whether the user has hit command period. Should work even on international systems that do keyboard remapping.
*New OpenPreferencesFolder.c opens the Preferences folder in the System Folder, creating it if necessary.
*PixMapToPostScript.c now accepts a pixmap handle instead of a pointer, relieving the user of the responsibility of making sure that the handle was locked before being dereferenced. Fixed silly bug, introduced 5/27/93, that suppressed all hex data.
*In ReadMatLabFile.c: Added LoadNamedMatIntoShorts and LoadNamedMatIntoDoubles. Renamed LoadMatShorts and LoadMatDoubles to LoadNextMatIntoShorts and LoadNextMatIntoDoubles.
*SetPixelsQuickly.c is now callable as a MatLab resource, thanks to detective work and tricky work-around by David Brainard.
CHANGES DURING 5/93:
*Due to a reorganization of the info-mac ftp site, the latest VideoToolbox is now at info-mac/Development/SourceCode/.
*Assign.c is the new name for the former ReadAssignments.c, which has been significantly enhanced. This runtime C interpreter reads and executes any text "assignment" file that contains only C assignments and comments. It can also write an assignment file, making the assignment file a portable way of recording calibrations and experimental parameters. New features include optionally ignoring unknown variables, support for arrays, optional return of an error code in place of calling PrintfExit, and checking of name syntax.
*Added MultipleChoice.c, accepts one character response (with default) and spells out whole answer. YesOrNo(), formerly in kbhit.c, accepts y/n and spells out "Yes" or "No".
*Enhanced GetWindowDevice() to support GWorld's.
*Updated Quick3 and CalibrateLuminance to use version 2 of Numerical Recipes in C.
*TimeVideo 2.5 tests all video devices on any Mac running System 6.05 or later. It tests gray and color modes, and measures and reports the gray-mode color-transformation matrix. It no longer assumes any particular correspondence between the video mode number and the pixel size. Many small bug fixes.
*SetEntriesQuickly.c now respects the setting of the device's gray/color mode, and maps to gray when appropriate. Changed prototype of macltset to specify the red, green, and blue arrays as "unsigned short" instead of "short".
*Luminance.c: If the driver is in gray mode (i.e. not color) then LoadLuminances maps rgb to gray by simply copying the green component to the red and blue components.
*GDVideo.c: Changed GDPrintGammaTable() to accept a simple file pointer instead of an array of two file pointers.
*GrabSlotDrivers now checks for presence of the Slot Manager, in response to bug report by Jonathan Brecher.
CHANGES DURING 4/93:
*Updated all projects and "Read me".
*Added explanation of tiling to PixMapToPostScript.c.
*GetPixBaseAddr32(PixMap **pm) returns the 32-bit address of the pixels/bits in a pix/bitmap. In RectToAddress.c.
*SetEntriesQuickly.c no longer requires a 68020.
*MaximizeConsoleHeight.c now fully supports 1-bit QuickDraw.
*Deleted obsolete AddressToSlot and AddressToScreenDevice from GetScreenDevice.c.
*Merged GDFrameRate.c and GDTimeClut.c to produce GDTime.c. Deleted obsolete GDFramesPerClutUpdate, GDClutUpdateRate, and GDTimeClutUpdate.
*TimeVideo will test all video devices on any Mac running System 6.05 or later. It tests gray and color modes, and measures and reports the "gray" color-transformation matrix. It no longer assumes any particular correspondence between the video mode number and the pixel size.
*GDCOLORS(device) is gone because its answer was misleading when in 16-bit or 32-bit mode. Instead, use either GDClutSize(device) or GDColors(device), in GDVideo.c, but take care to choose the right one, since they're not equivalent when in more-than-8-bit modes.
*GDVideo.c: Removed assumption, in all routines, that there is any particular correspondence between the video mode number and the pixel size. New GDHasMode(device,mode,&pixelSize,&pages) tells you whether a particular video mode is supported by your video device. Added GDPrintGammaTable(). Deleted GDModeName().
CHANGES DURING 3/93:
*Made RectToAddress compatible with the initial versions of 32-bit QuickDraw, in which GetPixmapBaseAddr() did not work.
*Enhanced TimeVideo, producing a more comprehensive and intelligible report, and subsuming the former TestCluts, which is now gone.
* GDSetEntriesByType(device,...) checks the (**device).gdType field and calls GDSetEntries, GDDirectSetEntries, or nothing, as appropriate. In GDVideo.c.
*GDSetEntriesByTypeHighPriority does the same, but at high processor priority, forcing the driver to behave synchronously. In GDVideo.c.
*GDInfo.c collects useful information about a video device. In GDVideo.c
*IdentifyVideo(device) returns a descriptive C string. In Identify.c,.
*Added the constant MAX_SCREENS=8 to VideoToolbox.h
*GDSaveGamma(device) saves a copy that GDRestoreGamma(device) later uses to restore the gamma table. In GDVideo.c.
*Added UnclipScreen(device), RestoreScreenClipping(device), SquareCorners(device), and RestoreCorners(device) to HideMenuBar.c, to extend the clipping region to include the WHOLE screen.
*GDOpenWindow/GDDisposeWindow call GDSaveGamma/GDRestoreGamma and UnclipScreen/RestoreScreenClipping.
CHANGES DURING 2/93:
*Fixed endless loop in PatchMacIIciVideoDriver in GDVideo.c that hung up any program that called GDGetEntries, including the demos TestGDVideo and TestSetEntriesQuickly.
*Enhanced PatchMacIIciVideoDriver to deal with ROM- as well as RAM-based video drivers.
*Fixed SetEntriesQuickly to work correctly on Toby Video Card, Macintosh Display Card 8*24, and to work in 16-bit mode on Quadra.
*VideoToolbox.c explains how to create a precompiled header, for tenfold faster compiles.
*Greatly increased the number of headers included by VideoToolbox.h, so that most C files can now include just the VideoToolbox.h header.
*Added tiny new demo, Grating.c, that shows how to load the clut and display a grating.
*Added SetPixelsQuickly.c to quickly peek or poke a row of pixels, bypassing the color tables. It's more than ten times faster than using SetOnePixel.c, which is now obsolete. This is the fastest way to get at the pixels in an image, for image processing or synthesis. Works with bitmaps and pixmaps and any size of pixel. Try the demos Grating and FlickeringGrating.
*GDOpenWindow now creates a full-screen window even on the main screen.
*Added window=GDOpenWindow1(device) and GDDisposeWindow1(window), which work with a WindowPtr instead of a CWindowPtr, for less hassle with casting.
*AddExplicitPalette(window), in GDOpenWindow.c, adds a palette with all colors marked as explicit, so that you can use PmForeColor and PmBackColor to specify literally what numbers you want to put into your pixels in drawing operations like EraseRect() and DrawString().
*Added PrintfExit.c, which prints out an error message and exits. Replaced all calls to exit() in the VideoToolbox by calls to this routine, so many projects will need to add it.
*Require(), in PrintfExit.c, tests for any required fpu, cpu, and version of QuickDraw, and fails gracefully if they're absent.
*All demos now call Require() in PrintfExit.c to test for presence of any required fpu, cpu, and version of quickdraw, instead of crashing.
*Enhanced GDUncorrectedGamma() in GDVideo.c to work correctly with video devices that use any version of the gamma table. This might have caused TestCluts to report spurious driver errors.
*Replaced IdentifyCompiler.c and IdentifyMachine.c by the new Identify.c. Added IdentifyVideo(device) and IdentifyModel().
*Renamed TestSetEntriesQuickly to TestCluts, and enhanced it to save detailed results in file.
*Enhanced CopyBitsQuickly to return a nonzero int if an error occurred.
*Added an image-multiplication mode to CopyBitsQuickly, and enabled it on 2/18/93.
*Added SwapPriority() to SetPriority.c, to be used just like SwapMMUMode().
*ConvolveX.c now rounds to nearest integer, and supports 32-bit video addressing.
*Renamed the file MatLab.c to ReadMatLabFile.c, though the functions themselves are unchanged.
*Introduced MATLAB conditional into VideoToolbox.h, to support creation of MatLab external code resources, as implemented by David Brainard.
