{\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 \sbasedon222\snext2 Calling;}{\s3 \f22 \sbasedon0\snext3 Addr;}{\s4\tx1800\tx3600\tx6480 \f21 \sbasedon0\snext4 Mode Table 2;}}{\info{\author Thomas Jefferson}}
\widowctrl\ftnbj \sectd \linemod0\linex0\cols1\endnhere \pard\plain {\outl\fs36 SecondSight VGA\par 
}\pard {\f21 Low-Level Command Interface & Firmware Documentation\par 
July 14, 1995\par 
\par 
}\pard \brdrt\brdrs {\b\f21 GetStatus}{\f21 \par 
}\pard {\f21 \par 
}\pard {\f22 C:\tab }{\f22\fs20 int _GetStatus(vga_status_rec *stat_rec)}{\f22 \par 
}\pard {\f21 \par 
Size: $01 bytes\par 
\par 
$00: $00\tab Command Code\par 
\par 
}{\b\f21 Return data}{\f21 :\par 
(the following data is stored starting at the pointer stat_rec)\par 
\par 
$00:\tab 'G'\tab Ascii values of the letters, used as an identification\par 
$01:\tab 'S'\tab that a GSVGA card is in fact installed in this machine\par 
$02:\tab 'V'\par 
$03:\tab 'G'\par 
$04:\tab 'A'\par 
$05:\tab size_rec\par 
\tab \tab Number of bytes of record data that follow\par 
$06:\tab GS/VGA Firmware Version Number\par 
\tab \tab bits 7-4: major revision number\par 
\tab \tab bits 3-0: minor revision number\par 
\tab \tab (Example: version 1.0 is $10, version 4.6 = $46)\par 
$07:\tab emul_status\par 
\tab \tab 0 = emulating, !0 = not emulating\par 
$08:\tab vga_mode\par 
\tab \tab Mode number of last set video mode\par 
$09:\tab video_ram\par 
\tab \tab 0 = 512K, 1 = 1MB\par 
$0A:\tab monitor_type\par 
\tab \tab IS_VGA (0x10)\tab VGA monitor\par 
\tab \tab 0x00\tab \tab \tab AppleColor RGB monitor\par 
\par 
}\pard {\f21 Looks for a Second Sight video card in the current system. If no card is found, this routine returns a -1.\par 
}\pard {\f21 \par 
}\pard \brdrt\brdrs {\b\f21 SetMode}{\f21 \par 
}\pard {\f21 \par 
}\pard {\f22 C:\tab }{\f22\fs20 void _SetMode(int modeNum, int emulFlag)}{\f22 \par 
}\pard {\f21 \par 
Size: $03 bytes\par 
\par 
$00: $01\tab \tab Command Code\par 
$01: $XX\tab \tab Screen Mode to Switch To\par 
\tab \tab \tab (VGA BIOS Screen Mode Parameter)\par 
\par 
\tab \tab \tab $01 - 40x25\par 
\tab \tab \tab $03 - 80x25\par 
\tab \tab \tab $53 - 640x480x256\tab (VGA only)\par 
\tab \tab \tab $13 - 320x200x256\par 
\tab \tab \tab $61 - 640x400x256\par 
\tab \tab \tab $FA - 560x192x16\par 
\tab \tab \tab $FB - 280x192x16\par 
\tab \tab \tab $FC - 40x24\par 
\tab \tab \tab $FD - 80x24\par 
\tab \tab \tab $FE - 640x200\par 
\par 
$02: $EE\tab \tab Emulation Flag\par 
\tab \tab \tab $01 = Do not emulate the current Apple II video mode\par 
\tab \tab \tab $00 = Emulate current Apple II video mode\par 
\par 
\par 
}\pard \brdrt\brdrs {\b\f21 Upload Code/Data\par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 _UploadData(int flag, void *dst, longword len, void *src)}{\f22 \par 
}{\f21 \par 
Size: $0B bytes\par 
\par 
$00: $02\tab \tab Command Code\par 
$01: $XX\tab \tab Code/Data Flag\par 
$02: $0ABBCC\tab Address in Z180 memory to put data\par 
$05: $0LLLLL\tab Length of data block to transfer\par 
$08: $AABBCC\tab Address in IIGS memory to take data from\par 
\par 
Flags: }{\f22 FL_CODE = 0}{\f21 , }{\f22 FL_DATA = 1}{\f21 \par 
\par 
}\pard {\f21 
Transfers a block of data from the IIGS memory address src, and length len, to the Second Sight card. If the "Code/Data" flag is FL_DATA, the dst address refers to an offset in the VGA controller's video memory. If the "Code/Data" flag is FL_CODE, the dst 
is a direct Z180 address.\par 
}\pard {\f21 \par 
}\pard {\b\f21 Caution}{\f21 !: Due to the fact that the 1MB of video memory is bank switched in two 512K pieces during thhis operation (at address 0x08000
0), you cannot transfer data across the 512K boundary.  If you do transfer data across this boundary, the Z180's DMA controller will wrap around to address zero, overwriting the firmware, and you will crash the Second Sight (and thus the IIGS).\par 
}\pard {\f21 \par 
}\pard {\f21 For example, if you wanted to transfer 768K of data from the IIGS to address 0x010000 in the VGA memory, you would need to do two transfers:\par 
}\pard {\f21 \par 
    0x070000 bytes at address 0x010000\par 
    0x050000 bytes at address 0x080000\par 
\par 
}\pard {\f21 Second Sight will see that the first transfer
 starts at less than bank 08, and will set the low VGA memory bank. On the second transfer, it will see that the bank is 08 or above and set the high VGA memory bank. Second Sight cannot switch banks in the middle of a transfer, thus the need for you to br
eak up the transfer.\par 
}\pard {\f21 \par 
}\pard {\f21 (In the future, the _UploadData command may handle this automatically, in which case the two separate transfers would still be compatible, but just an extra step).\par 
}\pard {\f21 \par 
\par 
}{\b\f21 Upload Bitmap (Not currently implemented)}{\f21 \par 
\par 
Size: $08 bytes\par 
\par 
$00: $0\par 
$01: $LLLL\tab \tab \tab Number of lines in the bitmap\par 
$03: $WWWW\tab \tab Width (# bytes wide screen is, minus # bytes pixmap)\par 
$05: $0AAAAAA\tab \tab Starting address in VGA memory (vga memory only)\par 
\par 
}\pard \brdrt\brdrs {\b\f21 Scroll Screen}{\f21 \par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _ScrollScreen(void *src, void *dst, longword length)}{\f21 \par 
\par 
Size: $0A bytes\par 
\par 
$00: $03\tab \tab Command Code\par 
$01: $0SSSSS\tab Offset in VGA memory to begin move at\par 
$04: $0DDDDD\tab Destination of copy command\par 
$07: $0LLLLL\tab Number of bytes to move\par 
\par 
}\pard {\f21 Scrolls the entire contents of the screen in a direction specified by the two parameters. The caller is responsible for clearing the sections of the screen that should be cleared.\par 
}\pard {\f21 \par 
}\pard {\f21 Effectively, to scroll the screen by pixel values, the final offset to use in the memory copy command is:\par 
}\pard {\f21 \par 
  v * num_pixels_per_line + h\par 
\par 
}\pard \brdrt\brdrs {\b\f21 Screen Off}{\f21 \par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _ScreenOff(void)}{\f21 \par 
\par 
Size: $01 bytes\par 
\par 
$00: $04\tab \tab Command Code\par 
\par 
}\pard {\f21 Disables screen output.  This can be useful for those situations where you want to "smoothly" change the screen mode, or fill the screen with data, and then show it all at once.  Also, since screen output i
s disabled, accesses to the video memory will not have to wait for video refresh cycles, speeding up throughput somewhat (at a 1MB/sec maximum DMA transfer speed, this shouldn't really affect throughput much, if at all).\par 
}\pard {\b\f21 \par 
\par 
}\pard \brdrt\brdrs {\b\f21 Screen On}{\f21 \par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _ScreenOn(void)}{\f21 \par 
\par 
Size: $01 bytes\par 
\par 
$00: $05 \tab \tab Command Code\par 
\par 
Reenables screen output.\par 
}{\b\f21 \par 
\par 
}\pard \brdrt\brdrs {\b\f21 SetPalette}{\f21 \par 
}\pard {\f21 \par 
}\pard\plain \s2 \f22\fs20 {\plain \f21 C:\tab }void _SetPalette(rgb_24 *palette)\par 
\pard\plain {\f21 \par 
Size: $04 bytes\par 
\par 
$00: $06\tab \tab Command Code\par 
$01: $AABBCC\tab Address in IIGS memory of palette data\par 
 \tab \tab \tab 256 entries of 3 bytes each, or 768 bytes\par 
\par 
}\pard {\f21 Uploads a complete new palette to the VGA controller. The palette consists of 256 palette entries, each three bytes. The bytes are:\par 
}\pard {\f21 \par 
   $00: Red\par 
   $01: Green\par 
   $02: Blue\par 
\par 
}\pard {\f21 The RGB values have a full 8-bit width, so there are a maximum of 16 million colors to select from.\par 
}\pard {\b\f21 \par 
\par 
}\pard \brdrt\brdrs {\b\f21 SetPaletteEntry}{\f21 \par 
}\pard {\f21 \par 
}\pard\plain \s2 \f22\fs20 {\plain \f21 C:\tab }_SetPaletteEntry(int entry, rgb_32 triplet)\par 
\pard \s2 \par 
\pard\plain {\f21 Size: $05 bytes\par 
\par 
$00: $07\tab \tab Command Code\par 
$01: $PN\tab \tab Palette entry number to change\par 
$02: $AABBCC\tab One RGB triplet\par 
\par 
}\pard {\f21 Modifies a single VGA palette entry in the VGA controller. The palette entry consists of three bytes:\par 
}\pard {\f21 \par 
   $02: Red\par 
   $03: Green\par 
   $04: Blue\par 
\par 
}\pard {\f21 The RGB values each have a full 8-bit width, so there are a maximum of 16.7 million colors to select from.\par 
}\pard {\b\f21 \par 
\par 
}\pard \brdrt\brdrs {\b\f21 SetBorder}{\f21 \par 
}\pard {\f21 \par 
}\pard\plain \s2 \f22\fs20 {\plain \f21 C:\tab }_SetBorder(int entry)\par 
\pard\plain {\f21 \par 
Size: $02 bytes\par 
\par 
$00: $08\tab \tab Command Code\par 
$01: $XX\tab \tab Palette entry color used to describe the border color\par 
\par 
\par 
}\pard \brdrt\brdrs {\b\f21 Run Code}{\f21 \par 
}\pard {\f21 \par 
Size: $07 bytes\par 
\par 
$00: $09\tab \tab Command Code\par 
$01: $AA\tab \tab Value of CBR register\par 
$02: $BB\tab \tab Value of CBAR register\par 
$03: $CC\tab \tab Value of BBR register\par 
$04: $0ABBCC\tab Address in Z180 memory to CALL to\par 
\par 
\par 
}\pard \brdrt\brdrs {\b\f21 Clear Screen}{\f21 \par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _ClearScreen(int color, void *dst, longword len)}{\f21 \par 
\par 
Size: $08\par 
\par 
$00: $0A\tab \tab Command Code\par 
$01: $CC\tab \tab Color to set the pixels to\par 
$02: $0ABBCC\tab Address to start setting pixels at\par 
$05: $0LLLLL\tab Number of bytes to set to that value\par 
\par 
}\pard {\f21 Sets the range of video memory starting at address }{\f22 dst}{\f21  and of length }{\f22 len}{\f21  to }{\f22 color}{\f21  (a byte value).\par 
}\pard {\f21 \par 
}{\b\f21 \par 
}\pard \brdrt\brdrs {\b\f21 SetShadow\par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _SetShadow(int flag)}{\f21 \par 
\par 
Size: $02\par 
\par 
$00: $0B\tab \tab Command Code\par 
\par 
$01: $XX\tab \tab 0 = GS Video shadowing will occur\par 
\tab \tab \tab 4 = do not shadow GS video data writes\par 
}{\b\f21 \par 
}\pard \brdrt\brdrs {\b\f21 SetVGAReg\par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _SetVGAReg(int idx, int idxval, int reg, int val)}{\f21 \par 
\par 
}\pard {\f21 An index/register pair is specified, as well as a value to store into that VGA register.\par 
}\pard {\f21 \par 
Size: $07\par 
\par 
$00: $0C\tab \tab Command Code\par 
$01: $IL\tab \tab low byte of index register\tab \par 
$02: $IH\tab \tab high byte of index register\par 
$03: $II\tab \tab Index register value\par 
$04: $RL\tab \tab Low byte of register address\par 
$05: $RH\tab \tab high byte of register address\par 
$06: $VV\tab \tab Value to store into register\par 
\par 
}{\b\f21 GetVGAReg\par 
}{\f21 \par 
C:\tab }{\f22\fs20 int _GetVGAReg(int idx, int idxval, int reg)}{\f21 \par 
\par 
An index/register pair is specified, and the value of the register is returned.\par 
\par 
Size: $06\par 
\par 
$00: $0D\tab \tab Command Code\par 
$01: $IL\tab \tab low byte of index register\tab \par 
$02: $IH\tab \tab high byte of index register\par 
$03: $II\tab \tab Index register value\par 
$04: $RL\tab \tab Low byte of register address\par 
$05: $RH\tab \tab high byte of register address\par 
\par 
Return value:\par 
$00: $VV\tab \tab Value returned from register\par 
\par 
\par 
}\pard \brdrt\brdrs {\b\f21 SetUserMode}{\f21 \par 
}\pard {\f21 \par 
C:\tab }{\f22\fs20 void _SetUserMode(vga_mode_rec *table)}{\f21 \par 
\par 
Size: $01\par 
\par 
$00: $0E\tab Command number\par 
\par 
Followed by 84 bytes of mode selection data (see }{\b\f22 vga_mode_rec}{\f21 ).\par 
\par 
}\pard {\f21 WARNING: Some cheap VGA monitors can actually blow up their circuit boards if you pass bogus data to this routine and then call _SetMode(0xFF,1).  }{\b\f21 
BE SURE YOU KNOW WHAT YOU ARE DOING!! IF YOU DON'T KNOW WHAT YOU'RE DOING, STICK WITH THE PROVIDED VIDEO MODES. Sequential Systems will accept no responsibility for monitors damaged in this way.}{\f21 \par 
}\pard {\f21 \par 
}\pard {\f21 Multi-Sync monitors and the AppleColor RGB monitor are robust enough to handle garbage mode settings appropriately (the AppleColor will shut down, MultiSyncs will try to sync and if they fail will do nothing).\par 
}\pard {\f21 \par 
}\pard {\f21 This routine will checksum the mode data as an aid to preventing accidentally passing bad data through should the machine crash or what-not.\par 
}\pard {\f21 \par 
\par 
}\pard \brdrt\brdrs {\b\f21 SetTextFont\par 
}\pard {\f21 \par 
Size: $04\par 
\par 
$00: $0F\par 
$01: $XX\tab \tab Font number to select\par 
\par 
}\pard {\f21 Sets the current text font used by the Second Sight. The values for XX are as follows:\par 
}\pard {\f21 \par 
  $00:\tab \tab Standard ROM font\par 
  $01:\tab \tab Alternate ROM font\par 
  $02:\tab \tab Standard PC ANSI Font\par 
  $03:\tab \tab User Uploaded Font (must be at address $00F000 in the SRAM)\par 
\par 
If a text mode is currently active, the font change takes place immediately.\par 
\par 
\par 
}\pard \fi-2880\li2880\tx2880 \par 
{\outl\fs28 \page }{\outl\fs28 Z180 Memory Map}\par 
\pard \fi-2880\li2880\tx2880 {\f22 \par 
}\pard The following two tables diagram the Second Sight's memory map as seen by the Z180 processor.{\f22 \par 
}\pard \fi-2880\li2880\tx2880 {\f22 \par 
}\pard \fi-2880\li2880\tx2880 {\f22 $000000}\par 
   .\par 
\pard \fi-2880\li2880\tx2880    .   \tab 128K SRAM - IIGS video shadowing, program storage (see diagram below)\par 
\pard \fi-2880\li2880\tx2880    .\par 
{\f22 $01FFFF }    \par 
{\f22 $040000}\par 
   .\par 
   .   \tab a softswitch - {\b\i do not modify}!!!\par 
   .\par 
{\f22 $0}{\f22 5}{\f22 FFFF}\par 
{\f22 $0}{\f22 6}{\f22 0000}\par 
   .\par 
   .   \tab 128K EPROM - \par 
   .\par 
{\f22 $07FFFF}\par 
{\f22 $080000}\par 
   .\par 
   .   \tab VGA Video Memory\par 
   .\par 
{\f22 $0FFFFF}\par 
\par 
\par 
{\outl\fs28 SRAM Map}\par 
\par 
Bank 0\par 
{\f22 $0000 - $03FF}\tab misc. code, interrupt vectors, stack\par 
{\f22 $0400 - $0BFF}\tab Text pages 1 and 2 shadow buffers\par 
\pard \fi-2880\li2880\tx2880 {\f22 $0C00 - $1FFF}\tab Command handler firmware, interrupt handlers\par 
\pard \fi-2880\li2880\tx2880 {\f22 $2000 - $5FFF}\tab Hires Page 1 and Page 2 shadow buffers\par 
{\f22 $6000}\tab Misc. Shadowing code\par 
{\f22 $C000 - $CFFF}\tab Video mode table storage\par 
\pard \fi-2880\li2880\tx2880 {\f22 $FFFF}\tab \tab \tab \par 
\pard \fi-2880\li2880\tx2880 \par 
Bank 1\par 
{\f22 $0000}\tab free space\par 
{\f22 $2000 - $9FFF}\tab Super Hires/Double Hires Shadow buffers\par 
\pard \fi-2880\li2880\tx2880 {\f22 $A000 - $BFFF}\tab SHR Shadowing code (only when SHR Shadowing is active and running)\par 
\pard \fi-2880\li2880\tx2880 {\f22 $C000}\tab Free Space\par 
\pard \fi-2880\li2880\tx2880 {\f22 $FFFF}\par 
\pard \par 
\pard If you can guarantee that a particular IIGS video page will not be written to by your program, you can put code there.  Otherwise, to use the video page areas for program storage you must make the {\f22 _SetShadow} c
all and disable video shadowing (Second Sight V1.1 EPROM {\b and} Lattice or greater).  With shadowing inactive, you may use much of Bank 0 (both hires pages, and $D000-$FFFF) and all of Bank 1.\par 
\pard \par 
\pard The SHR Shadowing code is copied to its running place when emulation is enabled and SHR mode is turned on. When SHR mode is off, or emulation is disabled, the area from $A000 - $BFFF in bank 1 is unused.\par 
\pard {\f21 \par 
}}