[At the moment, some of the VideoToolbox projects ".π5" are in version 5 and some ".π" 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. The version 5 projecs have not been updated since June '93; I suggest you upgrade to THINK C 6.01]
COMPUTER COMPATIBILITY:
Several colleagues have expressed interest in using this software on PCs and Suns. Most of the routines are built upon QuickDraw, and therefore are only useful on Macs. However, several useful packages use nothing but standard C and will work fine on any computer: Quick3 (LogLikelihood.c, MonotonicFit.c, PsychometricFit.c, etc.), Assign.c, BreakLines.c, VLambda.c, and all the statistical routines (randU.c, nrand.c, Binomial.c, ChiSquare.c, Mean.c, Normal.c, Shuffle.c, Uniform.c). The VideoToolbox.h header file defines a symbol "MAC_C" that is only true if the compiler supports the Macintosh extensions to C. For maximum portability of the VideoToolbox package, the Mac-dependent part of many of the files is only compiled if MAC_C is true. The luminance-control software in Luminance.c makes minimal use of GDHandles to designate particular video devices and load their cluts, and could be easily converted to work with some other scheme for designating video devices and loading their cluts.
68040:
Peter Lennie writes (6/23/93): "On the latest developers CD there's a note about the Quadra's use of a trap to emulate the FINTRZ instruction, which isn't built in to the 68040. This instruction is called commonly in the code generated by THINK C [5 when FPU use is enabled], and for me it became an issue in the loops that recalculate lookup tables during chromatic flicker. By rewriting the loop to avoid that instruction (using a small function supplied on the CD) I reduced the time it took to recalculate --as opposed to write-- the tables from 16msec to 1.6 msec." [NOTE: I presume that Peter is referring to the June? '93 developer CD.]
COMPILER COMPATIBILITY:
I recommend that you use the latest version of THINK C, currently 6.01. I suggest you get as much help as you can from the compiler by always enabling THINK C’s “Require prototypes” and “Check pointer types” options (under “Language Settings”) and “\p is unsigned char *” (under “Compiler settings”). I also recommend using THINK C’s universal floating point format (i.e. don’t check “Native floating point format” under “Compiler settings”), because it allows all your projects, whether or not they use the 68881/2, to use the same ANSI library and precompiled header, and the speed and space penalty is very small.
All the programs in the VideoToolbox are compatible with THINK C 6.01, but, with only three exceptions (SetEntriesQuickly.c, kbhit.c, and CopyBitsQuickly.c) do not use any features unique to the THINK compiler. SetEntriesQuickly.c and kbhit.c require THINK C. CopyBitsQuickly.c generates slower code when compiled by MPW C than when compiled by THINK C.
The Symantec THINK C and Apple MPW C compilers have two important differences.
1. THINK C has a unique scheme for including assembly code in the middle of a C program. (Unfortunately, Standard C does not specify a standard way to do this.) MPW will only allow machine code (i.e. numbers). This affects CopyBitsQuickly and SetEntriesQuickly. CopyBitsQuickly will compile under MPW C, but won’t be quite as fast.
2. By default, MPW treats “int” as long, whereas THINK treats “int” as short. (It’s a compile-time option.) When it matters, you should explicitly declare your variables as “short” or “long” rather than just “int”.
SYSTEM COMPATIBILITY:
In general, I recommend using the latest System software, currently System 7.1. Everything runs fine under Systems 6 and 7, and is compatible with 32-bit mode and virtual memory. None of the demos is “MultiFinder friendly”. They’re compatible with MultiFinder, but they all hog the machine, which I think is perfectly proper for experiments. If you want to, it would be easy to make the programs polite by adding calls to using WaitNextEvent(), following Apple’s guidelines in the "New Inside Macintosh: Memory" book.
VIDEO CARD COMPATIBILITY:
All Macintosh video cards and built-in video devices come with video drivers that conform sufficiently well to the Apple guidelines that they are compatible with the VideoToolbox, but they may be much slower than you’d guess. This is discussed in a separate file, “Video synch”. You should check out your video drivers by running the self-explanatory demo TimeVideo. (You might also want to try the more arcane demo TestGDVideo, which assumes familiarity with Apple’s Designing Cards and Drivers book.)
MAKING YOUR PROGRAMS PORTABLE:
Everything else being equal, you’d like your programs to run on as wide a variety of machines as possible, and exit gracefully (i.e. with an explanation) on the rest. The VideoToolbox is as portable as possible, given the Macintosh operating system traps that it uses. The driving force for compatibility has been TimeVideo, which has been tested on a wide variety of Macs, and now runs on any Mac with System 6.05 or better.
REQUIRE. The VideoToolbox routine Require.c will check for any required cpu, floating point chip, and level of quickdraw and quits with an explanation if they’re absent. Minimally, if your program uses Color QuickDraw (e.g. if your program uses a GDHandle) then your program should begin by calling Require(gestalt8BitQD). If you use the New Palette Manager, e.g. SetDepth, then you should use Gestalt() to require System 6.05 or better. However, offscreen GWorlds are very handy and require 32-bit QuickDraw, so for most people I’d suggest just calling Require(gestalt32BitQD). That’s enough to guarantee availability of all the QuickDraw traps in Inside Mac I-VI, except that GetPixBaseAddr() gave wrong answers in early versions of 32-bit QuickDraw, so use the VideoToolbox routine GetPixBaseAddr32() instead, in RectToAddress.c.
PIXELSIZE. Your programs should not assume any particular screen depth or size. Instead you should get them from the screen’s GDHandle, which I like to call “device”:
device=GetScreenDevice(1);
pixelSize=(**(**device).gdPMap).pixelSize;
colors=GDColors(device); // number of different colors that can be displayed
clutSize=GDClutSize(device); // number of rgb entries in the clut
rect=(*device)->gdRect; // in global coordinates
type=(*device)->gdType; // value is one of: clutType, directType, or fixedType
It’s useful to check the current device “type”; type==clutType indicates that each pixel is wholly transformed by a single programmable color lookup table; type==fixedType has a similar meaning except that the color lookup table cannot be changed; type==directType indicates that each pixel is broken up into three components that are individually transformed by three programmable lookup tables. The clutSize is always less than or equal to 256. (It’s 1<<pixelSize unless you’re in 16- or 32-bit mode, i.e. type==directType, in which case the clutSize will be 32 or 256, since the clut is then treated as three separate 32- or 256-entry lookup tables. A 16-bit pixel is broken up into three 5-bit indices, discarding the highest bit; a 32-bit pixel is broken up into three 8-bit indices, discarding the highest 8 bits.) If you prefer a particular screen depth you can try to get it by calling HasDepth() and SetDepth(), which are documented in Inside Mac VI. (Note that HasDepth and SetDepth are part of the “New” Palette Manager, which will be present only if you have Color QuickDraw and the System is at least 6.05 or you have 32-bit QuickDraw.)
24/32-bit ADDRESSING. When debugging, it’s convenient to set your Mac to 32-bit addressing (use the Memory Control Panel) since this allows the THINK C Debugger to work always, even in sections of code that are surrounded by calls to SwapMMUMode. However, bear in mind that in this congenial 32-bit addressing environment, SwapMMUMode and StripAddress don’t do anything. It’s easy to forget to call StripAddress on all the RAM addresses that you access in 32-bit-addressing mode. You may not discover such bugs in your program until you run it on a Mac set to 24-bit addressing.
