{\rtf1\mac\deff2 {\fonttbl{\f0\fswiss Chicago;}{\f2\froman New York;}{\f3\fswiss Geneva;}{\f4\fmodern Monaco;}{\f5\fscript Venice;}{\f6\fdecor London;}{\f7\fdecor Athens;}{\f8\fdecor San Francisco;}{\f11\fnil Cairo;}{\f12\fnil Los Angeles;}
{\f13\fnil Zapf Dingbats;}{\f16\fnil Palatino;}{\f20\froman Times;}{\f21\fswiss Helvetica;}{\f22\fmodern Courier;}{\f23\ftech Symbol;}{\f24\fnil Mobile;}{\f25\fnil Postnet;}{\f143\fnil Goudy;}{\f151\fnil Futura Book;}{\f165\fnil B Goudy Bold;}
{\f166\fnil BI Goudy BoldItalic;}{\f167\fnil I Goudy Italic;}{\f190\fnil FranklinGothic No.2;}{\f191\fnil C FranklinGothic Condensed;}{\f192\fnil EC FranklinGothic ExtraCond;}{\f200\fnil Compton's-Superscript;}{\f209\fnil Compton's-Subscript;}
{\f557\fnil L Futura Light;}{\f1026\fnil ArenaCondensed;}{\f1298\fnil FormalScript;}{\f1495\fnil Anastasia;}{\f1654\fnil BrushHand;}{\f1815\fnil Aladdin;}{\f1844\fnil Slalom;}{\f2338\fnil Soutane;}{\f2419\fnil LiddieBlack;}{\f2498\fnil BrushScript;}
{\f2667\fnil Halloween;}{\f2705\fnil FlorentineSwashCaps;}{\f2909\fnil HobbyHeadline;}{\f2921\fnil Brandyscript;}{\f3456\fnil FrnkGothITC MdIt BT;}{\f5773\fnil HelveticaNeue LightExt;}{\f5774\fnil HelveticaNeue LightExtObl;}
{\f5775\fnil HelveticaNeue MediumExt;}{\f5776\fnil HelveticaNeue MediumExtObl;}{\f5777\fnil HelveticaNeue HeavyExt;}{\f5778\fnil HelveticaNeue HeavyExtObl;}{\f5823\fnil HelveticaNeue LightCond;}{\f5824\fnil HelveticaNeue LightCondObl;}
{\f5825\fnil HelveticaNeue MediumCond;}{\f5826\fnil HelveticaNeue MediumCondObl;}{\f5827\fnil HelveticaNeue HeavyCond;}{\f5828\fnil HelveticaNeue HeavyCondObl;}{\f6639\fnil Circus;}{\f9840\fnil Espy Sans;}{\f9842\fnil Espy Sans Bold;}
{\f12800\fnil AppleGaramond Lt;}{\f12815\fnil Futura MdCn BT;}{\f12816\fnil Futura XBlkCn BT;}{\f12857\fnil FrnkGothITC Hv BT;}{\f12899\fnil AppleGaramond LtIt;}{\f12900\fnil AppleGaramond BkIt;}{\f12901\fnil AppleGaramond BdIt;}
{\f12903\fnil AppleGaramond Bk;}{\f12904\fnil AppleGaramond Bd;}{\f13101\fnil Tekton Oblique;}{\f13102\fnil Tekton;}{\f13226\fnil Copperplate33bc;}{\f13227\fnil Copperplate32bc;}{\f13228\fnil Copperplate31bc;}{\f13229\fnil Copperplate30bc;}
{\f13230\fnil Copperplate29bc;}{\f13231\fnil Copperplate32ab;}{\f13232\fnil Copperplate31ab;}{\f13233\fnil Copperplate30ab;}{\f13234\fnil Copperplate29ab;}{\f14560\fnil AGaramond SemiboldItalic;}{\f14561\fnil AGaramond Semibold;}{\f14562\fnil AGaramond;}
{\f14563\fnil AGaramond Italic;}{\f14592\fnil HelveUltCompressed;}{\f14750\fnil D Peignot Demi;}{\f14751\fnil L Peignot Light;}{\f14809\fnil eWorld Tight;}{\f14810\fnil HelveExtCompressed;}{\f14811\fnil HelveCompressed;}{\f14841\fnil B Eurostile Bold;}
{\f14845\fnil Eurostile;}{\f14867\fnil BO Futura BoldOblique;}{\f14868\fnil B Futura Bold;}{\f14869\fnil O Futura BookOblique;}{\f14902\fnil H Tiffany Heavy;}{\f14906\fnil Tiffany;}{\f14936\fnil FranklinGothic;}{\f14976\fnil L Helvetica Light;}
{\f14991\fnil Garamond;}{\f15011\fnil Avant Garde;}{\f15418\fnil FrnkGothITC Md BT;}}{\colortbl\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;
\red255\green255\blue255;}{\stylesheet{\sbasedon222\snext0 Normal;}{\s2 \f22\fs20 \sbasedon0\snext2 FunctionLine;}{\s3\fi-2160\li2160 \f21 \sbasedon0\snext3 VariableDescribe;}{\s4\li720\tx2420\tx3600\tx6480 \f21 \sbasedon0\snext4 Mode Table;}{
\s5\tx1800\tx3600\tx6480 \f21 \sbasedon4\snext5 Mode Table 2;}}{\info{\author Thomas Jefferson}}\widowctrl\ftnbj \sectd \linemod0\linex0\cols1\endnhere \pard\plain {\outl\f21\fs48 Second Sight}{\f21 \par 
}\pard {\f21\fs28 Programmer's Library Documentation\par 
July 14, 1995}{\f21 \par 
}\pard {\f21 \par 
}\pard {\f21\fs36 Basic and Introductory Concepts\par 
}\pard {\f21 \par 
}{\b\f21 Palette}{\f21 \par 
\par 
typedef struct RGB \{\par 
    byte r;\par 
    byte g;\par 
    byte b;\par 
\} RGB;\par 
\par 
}\pard {\f21 Palette entries consist of three bytes - one byte each of value for Red, Green, and Blue. Unlike man
y PC VGA cards which only use 6 bits of each color vector, the Second Sight supports a full palette range of 16.7M colors; i.e., each R G or B value is 256 levels.\par 
}\pard {\f21 \par 
}\pard {\f21 
Palette data is required in Second Sight's 256 color modes, as well as in its text modes (which only use the first 16 palette entries).  The HighColor and TrueColor modes of the card do not use palettes, because they directly store RGB color information in
 each pixel.\par 
}\pard {\f21 \par 
}{\b\f21 Image and Pixel Buffers}{\f21 \par 
\par 
}\pard {\f22\fs20 typedef struct LocInfo2 \{\par 
\tab Word portSCB;\tab \tab \tab }{\f21\fs20 /* $5A5A to indicate a LocInfo2 record */\par 
}{\f22\fs20 \tab union \{\par 
\tab     struct \{\par 
\tab \tab Pointer ptrToPixImage;\tab }{\f21\fs20 /* these fields are the same as the */}{\f22\fs20 \par 
\tab \tab Word width;\tab \tab \tab }{\f21\fs20 /* the regular LocInfo record */\par 
}{\f22\fs20 \tab \tab Rect BoundsRect;\par 
\tab     \} li1;\par 
\tab     struct \{\par 
\tab \tab Byte flags;\tab \tab \tab }{\f21\fs20 /* 1 = VGA buffer, 0 = GS Mem buffer */}{\f22\fs20 \par 
\tab \tab Pointer ptrToPixImage;  }{\f21\fs20 /* offset in VGA memory, or IIGS address */\par 
}{\f22\fs20 \tab \tab Word width;\tab \tab \tab }{\f21\fs20 /* width of pixel map in pixels */\par 
}{\f22\fs20 \tab \tab Byte pixDepth;\tab \tab }{\f21\fs20 /* number of bits per pixel */}{\f22\fs20 \par 
\tab \tab Rect BoundsRect;\tab \tab \par 
\tab     \} li2;\par 
\tab \} info;\par 
\};\par 
}\pard {\f21 \par 
}\pard {\f21 The LocInfo2 record is a b
ackwards-compatible extension of the original QuickDraw LocInfo record. It specifies the information necessary to locate the memory address and mask of an arbitrary pixel in a pixel map, either in VGA memory or GS memory. The equation to locate the address
 of a pixel, assuming a pixel depth of 8, 16, or 24 bits, is:\par 
}\pard {\f21 \par 
}\pard {\f22\fs20     address = (Y * width) + (X * (pixDepth / 8)) + ptrToPixImage;\par 
}\pard {\f21 \par 
\par 
}\pard {\f21\fs36 Library Routines\par 
}\pard {\f21 \par 
}\pard {\f21 The library routines described below are implemented as a C-accessible library. They should be accessible from any language that can operate with the ORCA\'aa development system.\par 
}\pard {\f21 \par 
}\pard {\f21 The actual implementation of the routines is an IPC library.  This provides the most flexible (and quickest) method of accessing these routines such that the code is shared (a necessity in multitasking systems).\par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaStartup({\b void})\par 
\pard\plain {\f21 \par 
}\pard \li720 {\f21 Returns -1 if no Second Sight card is found, or if the Second Sight library is not found via IPC.\par 
}\pard \li720 {\f21 \par 
Returns 0 if the card is found, and the library is properly initialized\par 
}\pard {\f21 \par 
}\pard {\f22\fs20 vgaStartup}{\f21  does a number of things. First, it checks to see if a Second Sight card is installed in the computer. If no card is found, an error is returned.\par 
}\pard {\f21 \par 
}\pard {\f21 Second, the routine tries to locate the core Second Sight library; this is generally an INIT file which contains IPC "hooks". If this code is not found, an error is returned.\par 
}\pard {\f21 \par 
This call }{\b\f21 must}{\f21  be made before any other calls in this document.\par 
\par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaLastError({\b void})\par 
{\f21 \par 
}\pard\plain {\f21 Returns the last error code found by the VGA library. See the section on each library call for a list of possible errors.\par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaCopyPixelMap({\b int} x,{\b int} y,{\b LocInfo2 *}loc,{\b Rect *}mapRect)\par 
\pard\plain {\f21 \par 
}\pard \fi-2160\li2160 {\f21 x,y\tab x & y coordinate on VGA screen to place pixelmap\par 
}\pard \fi-2160\li2160 {\f21 loc\tab pointer to a LocInfo2 record specifying the attributes of the source pixel map.\par 
mapRect\tab pointer to a Rect structure describing the portion of the source pixelmap to copy.\par 
}\pard \fi-2160\li2160 {\f21 \par 
}\pard {\f21 This function copies a portion of a color pixelmap (the pixel depth is specified in the LocInfo2 record) to the VGA display. No clipping is performed other than insuring that no data is copied outside of the VGA memory s
pecified by the global VGA LocInfoII record.\par 
}\pard {\f21 \par 
}\pard {\f21 The pixel depths of the two bitmaps must be the same, and pixels may only be copied on at least a one-byte boundary. See the function vgaPixelMapToPort for a function which will color-expand \par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaSetMasterLocInfo({\b LocInfo2 *}loc)\par 
\pard\plain {\f21 \par 
}\pard {\f21 This function sets the master VGA LocInfo record. This record defines the characteristics of the video display, such as height, width, pixel depth, etc.\par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaSetMode({\b int} vgaMode, {\b int} shadowFlag)\par 
\pard\plain {\f21 \par 
}\pard\plain \s3\fi-2160\li2160 \f21 vgaMode\tab A VGA Mode number. See the Table below for details.\par 
\pard \s3\fi-2160\li2160 shadowFlag\tab 
Controls the Second Sight's automatic shadowing of Apple II video modes.  True (1) turns shadowing off, False (0) turns shadowing back on. If an application is going to draw directly to the screen, it must turn shadowing off.\par 
\pard\plain \par 
{\i\f21 Possible Errors}{\f21 :\par 
\tab vgaINVALID_MODE_NUM\tab 0x01\par 
}\pard\plain \s3\fi-2160\li2160 \f21 \tab An invalid video mode number was passed to vgaSetMode. The mode number given does not correspond to any supported video mode.\par 
\pard\plain \tab vgaUNSUPPORTED_MODE\tab 0x02\par 
\pard\plain \s3\fi-2160\li2160 \f21 \tab The specified video mode is not supported by the monitor currently attached to the Second Sight. This could also mean that a > 256 color mode was selected, but the DAC is not capable of High Color or True Color.
\par 
\pard\plain \par 
\par 
\par 
\pard\plain \s2 \f22\fs20 {\b int} vgaSetPalette({\b RGB} palette[], {\b int} startInd, {\b int} numEntries)\par 
\pard\plain {\f21 \par 
}\pard {\f21 Sets }{\f22\fs20 numEntries}{\f21  entries of palette data, starting at entry }{\f22\fs20 startInd}{\f21  on the Second Sight card to the values specified in the pointer }{\f22\fs20 palette}{\f21 .  \par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaSetPaletteEntry({\b RGB *}palEntry, {\b int} colorInd)\par 
\pard\plain {\f21 \par 
}\pard {\f21 Sets a single palette entry specified by }{\f22\fs20 colorInd}{\f21  to the RGB values stored at the }{\f22\fs20 palEntry}{\f21  pointer.\par 
}\pard {\f21 \par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaLockPaletteRange({\b int} startInd, {\b int} endInd, {\b word} userID)\par 
{\b int} vgaUnlockPaletteRange({\b int} startInd, {\b int} endInd, {\b word} userID)\par 
{\b int} vgaFindAndLockPaletteRange({\b int} numEntries)\par 
\pard\plain {\f21 \par 
}\pard {\f21 
Allocates a range of palette entries for the exclusive use of the calling application.  This allows an application to set aside a certain number of colors for its own use, assured that its use of that entry won't interfere with other applications' colors o
r vice-versa.\par 
}\pard {\f21 \par 
\par 
\par 
}\pard\plain \s2 \f22\fs20 {\b int} vgaMapColor({\b RGB *}color);\par 
\pard\plain {\f21 \par 
}\pard {\f21 Looks through t
he existing palette for the closest match to the specified color, and returns the index of that color.  This routine may not return an index to a color anything at all like the specified one.  If an application does not lock its colors, it may want to peri
odically redraw its windows after remapping colors with }{\f22\fs20 vgaMapColor}{\f21 .\par 
}\pard {\f21 \par 
\par 
\par 
\par 
}\pard {\f21\fs36 \page File Formats}{\f21 \par 
}\pard {\f21 \par 
}\pard {\f21 We highly recommend that only _one_ set of routines to read/write this file format be created: modules for Seven Hills' "Babelfish" product.\par 
}\pard {\f21 \par 
The requirements for an image file format for Second Sight are as follows:\par 
\par 
}\pard \fi-720\li1440 {\f21 \bullet \tab Must be able to handle images of varying pixel depths\par 
\par 
}\pard \fi-720\li1440 {\f21 \bullet \tab Should be somewhat compatible with existing software, to provide a "bridge" for users who do not yet have Second Sight.\par 
}\pard \fi-720\li1440 {\f21 \par 
\bullet \tab Should be quick to load and save.\par 
}\pard {\f21 \par 
}\pard {\f21 
To this end, we have chosen an extension to the APF (Apple Peferred Format). We have defined three new chunk types, "SVGA" to denote an 8bpp (or higher) image, "SVGC" to denote a PackBytes-compressed 8bpp image, and "SVGP", to denote an 8bpp palette.
\par 
}\pard {\f21 \par 
SVGA\par 
}\pard {\f22\fs20 \tab Word\tab pixDepth;\tab \tab }{\f21\fs20 /* number of bits per pixel in this image */\par 
}{\f22\fs20 \tab Word\tab widthPixels;\tab }{\f21\fs20 /* number of pixels wide this image is */\par 
}{\f22\fs20 \tab Word heightPixels;\tab }{\f21\fs20 /* number of pixels tall this image is */\par 
}{\f22\fs20 \tab byte image[widthPixels*heightPixels*(pixDepth/8)];\par 
\tab \tab \tab \tab \tab /* \par 
}\pard {\f21 \par 
SVGC\par 
}\pard {\f22\fs20 \tab Word\tab pixDepth;\tab \tab }{\f21\fs20 /* number of bits per pixel in this image - always 8*/\par 
}{\f22\fs20 \tab Word\tab widthPixels;\tab }{\f21\fs20 /* number of pixels wide this image is */\par 
}{\f22\fs20 \tab Word heightPixels;\tab }{\f21\fs20 /* number of pixels tall this image is */\par 
}{\f22\fs20 \tab ..scanline data..\tab \tab }{\f21\fs20 /* each scanline in turn, run through PackBytes */\par 
}{\f22\fs20 \par 
}\pard {\f21 SVGP\par 
}\pard {\f22\fs20 \tab Word\tab numEntries;}{\f21\fs20 \tab \tab \tab /* number of palette entries */}{\f22\fs20 \par 
\tab RGB palette[numEntries];}{\f21\fs20 \tab /* palette data in the form of 'RGB' struct */\par 
}{\f22\fs20 \par 
}\pard {\f21 
To aid in compatibility of new pictures with existing applications, a grayscale version of the VGA image should be stored in the standard MAIN and PALETTE chunks of the file.  Grayscale was chosen because of ease of conversion of any format picture to gray
scale in 16-colors; if the application wishes to do a complicated quantization technique to choose colors for this "compatibility" image, it may do so, but this is not required.\par 
}\pard {\f21 \par 
}\pard {\f21 
Compression is not specified for 16bpp and 24bpp images, because the only decent existing standard for compression of TrueColor and HighColor images is JPEG - an algorithm that is extremely time-consuming to execute on a IIGS.  However, we expect that JPEG
 will come into more common use on the IIGS due to SecondSight's TrueColor and HighColor capabilities.\par 
}\pard {\f22\fs20 \par 
\par 
}\pard {\f21\fs36 \page Appendix A: Supported Video Modes\par 
}\pard {\f21 \par 
}\pard\plain \s4\tx1800\tx3600\tx6480 \f21 {\fs20\ul Text Mode\tab # Colors\tab Mode Number\tab Apple RGB Compatible?\par 
}\pard\plain \s5\tx1800\tx3600\tx6480 \f21 40x25\tab 16\tab $01\tab Yes\par 
80x25\tab 16\tab $03\tab Yes\par 
80x43\tab 16\tab \tab No\par 
80x50\tab 16\tab \tab No\par 
80x60\tab 16\tab \tab No\par 
132x25\tab 16\tab $50\tab Yes\par 
132x43\tab 16\tab $51\tab Yes\par 
132x60\tab 16\tab $4F\tab No\par 
\pard\plain \par 
\pard\plain \s4\tx1800\tx3600\tx6480 \f21 {\fs20\ul Graphics Mode\tab # Colors\tab Mode Number\par 
}\pard\plain \s5\tx1800\tx3600\tx6480 \f21 320x200\tab 256\tab $13\tab Yes\par 
320x200\tab 32K\tab $70\tab Yes\par 
320x200\tab 16M\par 
640x400\tab 256\tab $61\tab Yes (interlace)\par 
640x400\tab 32K\tab $5B\tab Yes (interlace)\par 
640x400\tab 16M\par 
640x480\tab 256\tab \tab No\par 
640x480\tab 32K\tab $5A\tab No\par 
640x480\tab 16M\tab $5F\tab No\par 
800x600\tab 256\tab \tab No\par 
800x600\tab 32K\tab $60\tab No\par 
1024x768\tab 256\tab $59\tab No\par 
\pard\plain \par 
\pard\plain \s4\tx1800\tx3600\tx6480 \f21 {\fs20\ul Emulation Mode\tab # Colors\tab Mode Number\par 
}\pard\plain \s5\tx1800\tx3600\tx6480 \f21 560x192\tab 16\tab $FA\tab Yes\par 
280x192\tab 16\tab $FB\tab Yes\par 
40x24\tab 16\tab $FC\tab Yes\par 
80x24\tab 16\tab $FD\tab Yes\par 
640x200\tab 256\tab $FE\tab Yes\par 
\pard\plain \fi-1080\li1080 \par 
\par 
\par 
x256\tab 256 colors using a 256 entry palette\par 
\pard \fi-1080\li1080 x32K\tab 65536 direct colors, using 6 bits for Green, and 5 each for Red and Blue, _or_ 32768 colors direct using 5 bits each for R, G, B.\par 
\pard \fi-1080\li1080 x16M\tab 16.7Million direct colors, using 8 bits each for Red, Green, and Blue\par 
\pard \par 
}