SuperGen Programmer's Toolkit ============================= Copyright (C) 1987-1992 Digital Creations, Inc. v3.1 - 06 Aug 1992 Contained here is a set of files to help you write programs in C or Assembly language to control both the original SuperGen (SG-10) and the SuperGen 2000s. This version is a slightly revised version of the kit shipped originally only with SG-2000s disks. It is fully compatible with SG-10's, though (more on this below). This release has been completely generalized for all SuperGens and is now shipped with all models. Those familiar with supergen.library v2.0 should read the REVISIONS section to learn what has changed. Those familiar with the original SuperGen's DCInterface programmer's kit and (lack of?) documentation will find that release 2.0 and subsequent releases contains several improvements over the original release: . new include files . new glue libraries . improved documentation . new functions . example programs Even if you've been programming using the old DCInterface stuff for a while, it's well worth your time to read through the example programs and documentation as there is a lot of new information. The following files are included: doc - library documentation copinit.doc - copinit.library documentation supergen.doc - supergen.library documentation example - programming examples for both the SG-10 and SG-2000s Dissolve.c - performs a user selectable dissolve effect ToggleFade.c - 2 second fade in or out Notch.c - turn on or off the Notch Filter (SG-2000s only) Notify.c - watch for register changes using notification SetCPhase.c - set the chroma phase register (SG-2000s only) ShowReg.c - show the contents of the SG-2000s register set include - include files supergen - C and Assembly include files for supergen.library and copinit.library clib - supergen and copinit C function prototypes aztec_pragmas - supergen and copinit C function #pragmas for Aztec C 5.0 sas_pragmas - supergen and copinit C function #pragmas for SAS/C 5.1 glue - glue libraries and .fd files for supergen.library & copinit.library aztec - glue libraries for Aztec C 5.0 sas - glue libraries for SAS/C 5.1 NEW PROGRAMMERS --------------- Those who are new to the SuperGen programming environment should study the example programs and then read through the function documentation and include files. There should be sufficient information in the examples to tutorially guide you through typical SuperGen programming practices. We have tried to include at least one example for all of the commonly used functions. There are a few omissions to the examples, however. There are no examples for the following functions due to their unsuitability for most applications: AddCopinit() DelCopinit() SGForceRegister() Also, there is no example for SGSetNotify(). The documentation for this function should be sufficient once you have investigated the rest of the notification system. All of the other functions are used at least once in the examples. COMPILER ENVIRONMENTS --------------------- The C examples and include files assume that you have an ANSI C compiler (require new style function declarations and prototypes as described in K&R 2nd edition). Both SAS/C 5.1 and Aztec C 5.0 are directly supported for the examples. Other ANSI C compilers (if there are any) will probably work if they support either of the current #pragma formats. The assembly include files are created such that any Motorola/MetaComCo compatible assembler should be able to read them. This includes at least SAS Asm, MCC Assem, Manx AS, and C.A.P.E. Linker libraries are included in AmigaDOS (ALink/BLink compatible) and Manx formats. Also, it is assumed that you have at least v37.1 of the AmigaOS include files. All of the examples depend on these files. LIBRARIES --------- There are two libraries associated with the SuperGen: supergen.library and copinit.library. The latter is accessed by supergen.library to perform the voodoo necessary to control SuperGen during vertical blanks. Unless you plan on doing some Copper list voodoo yourself, you probably will never need to mess with copinit.library directly. supergen.library contains all the functions necessary to control both the SG-10 and SG-2000s genlocks. The dissolve functions (SuperGen(), etc.) work on both genlocks. The SG-2000s has enhanced software controllability and therefore required the addition of functions specifically geared to controlling those functions: SGSetRegister() and SGForceRegister(). The v2.0 dissolve functions make it easy to do synchronous effects (e.g. waiting for a dissolve effect to finish). The v1.0 SuperGen() function started an effect and returned immediately while the effect continued in the background. By using SuperGenSignal() or SuperGenWait() functions you can be informed of the completion of your dissolve effects. doc/supergen.doc contains a complete description of each of the functions contained in supergen.library. Both of these libraries can be found in the libs directory of the disk that came with your genlock or in the electronic distribution file. INSTALLATION ------------ Libraries Both supergen.library and copinit.library must reside in your LIBS: directory in order to use the software interface to the SuperGen. Configuration Files The file devs:supergen-configuration, if present, is read by supergen.library when it first opens. This file determines both the type of genlock that the library should configure itself for and the initial register values (i.e. user's preferred settings). If this file doesn't exist, supergen.library defaults to SG-10 configuration. The SGSetup (2000s disks only) program is used to customize the contents of this file. Include Files Contents: supergen copinit.h - C include file for copinit.library supergen.h - C include file for supergen.library copinit.i - Assembly include file for copinit.library supergen.i - Assembly include file for supergen.library clib - ANSI C function prototypes copinit_protos.h - prototypes for copinit.library supergen_protos.h - prototypes for supergen.library aztec_pragmas - function pragmas for Aztec C 5.0 copinit_pragmas.h - #pragmas for copinit.library supergen_pragmas.h - #pragmas for supergen.library sas_pragmas - function pragmas for SAS/C 5.1 copinit_pragmas.h - #pragmas for copinit.library supergen_pragmas.h - #pragmas for supergen.library The include files in the supergen directory should be accessed by lines like: #include /* in C */ or include "supergen/supergen.i" ; in assembly just like the rest of the system include files. This will require that you make a directory called "supergen" in your include directory and copy these files there. The include files in the clib directory are for use with ANSI C compilers such as Aztec C 5.0 and SAS/C 5.1. They contain ANSI function prototypes for the functions in copinit.library and supergen.library. Copy them to the clib include directory. Example usage: #include The aztec_pragmas and sas_pragmas directory contains #pragma statements for inline calls to these supergen and copinit libraries for Aztec C 5.0 and SAS/C 5.1 respectively. Create a pragmas directory (if you don't already have one) and copy the appropriate files into it. For the supported compilers, you can use the pragmas in place of glue libraries. Example usage: #include NOTE: SAS/C expects the Library Base to be declared somewhere within the module that accesses the pragmas, so if you are writing modular code you'll need to add: extern struct Library *SuperGenBase; somewhere prior to accessing a #pragma'd function. Glue Libraries These object code libraries permit you to call supergen.library and copinit.library functions from C. Copy the appropriate glue libraries to the directory where you keep other such libraries (like c.lib, amiga.lib, etc). Aztec C libraries are contained in lib/aztec: sg.lib - small code/data sgl.lib - large code/data The SAS/C glue library is contained in lib/sas. This library may be used by for any language that is linked using ALink or BLink. It is also compatible with Manx ln v5.2. If you're using the pragmas you probably won't need to link with a glue library. COMPATIBILITY WITH v1.0 ----------------------- The SG-2000s vs. SG-10 From the software point of view, the SuperGen 2000s (SG-2000s) is essentially a superset of the original SuperGen (SG-10). The same version of supergen.library is used for the SG-10 and SG-2000s. In order to determine which registers are supported by the currently attached SuperGen, an application may call SuperGenType(). The information returned is ultimately based on user settings, but at least it's a way for an application to know what's legal. The default configuration (in the absence of a devs:supergen-configuration file) is that of an SG-10. The SGSetup program (2000s disks only), in addition to its other functions, allows the user to switch between SG-10 and SG-2000s configurations. SG-2000s registers will only be sent to the genlock when the library is configured for an SG-2000s. Otherwise, attempts to set SG-2000s registers will be ignored by the library (no signatures foreign to an SG-10 will be sent). There is essentially no harm in having supergen.library mistake an SG-10 for an SG-2000s since the SG-10 will simply ignore any signatures other than the dissolve signature. However, the SG-10 will revert to manual mode briefly when any register other than the Dissolve register is updated. Make sure you open the version of supergen.library required for the functions you are using. Functions requiring supergen.library versions newer than 1.0 are so noted in supergen.doc. supergen/supergen.h contains a SUPERGEN_Minimum constant indicating the minimum library version currently supported by Digital Creations. example: #include SuperGenBase = OpenLibrary ("supergen.library", SUPERGEN_Minimum); Priority The Priority system for SuperGen() was removed as of v2.0 since it was more a source of confusion than a usable feature. The function SuperGenPriority() has been replaced by a stub function in supergen.library to retain compatibility with existing software. This function no longer has a glue routine, so if you compile a program that calls SuperGenPriority(), it will no longer link successfully. Additionally, the Flags argument to SuperGen() was replaced by the Mode argument in v2.0. SuperGen() ignores the upper word of Mode (where the priority field used to be) so that a non-zero priority will not be misinterpreted as SGM_Software. SuperGenBase SuperGenBase changed significantly from v1.0 to v2.47 of supergen.library and is now a private structure (i.e. it may continue to change). If you were looking at this structure you will now break. Interrupts Only the following functions may be called from interrupt code: SGForceRegister() SGReadNotify() SGStatus() The rest must be called from a Task or a Process. Shared Access SuperGen can be shared among several applications, but it can only perform one dissolve effect at a time and has only one set of registers. This can cause some problems when the SuperGen is shared. There is currently no way to gain exclusive access to SuperGen. Notification As of v2.0 there is a system that permits your task to be signalled when any combination of the SuperGen registers is updated. The relevent functions are SGAddNotify(), SGRemNotify(), SGReadNotify() and SGSetNotify(). DOCUMENTATION ------------- supergen.doc contains detailed descriptions of the supergen.library functions. supergen.h contains a number of handy macros, constants, descriptions of the SG-2000s registers, and other miscellaneous documenation. Also the examples contain additional information about the usage of most of the supergen.library functions. copinit.doc contains descriptions of the copinit.library functions. OTHER STUFF ----------- We've tried to make the programming environment as usable as possible. If you find omissions, errors, bugs, or blatant oversights, please don't hesitate to contact us. Electronic mail can be sent to: BIX: peabody Physical mail or phone calls can be directed to: Digital Creations P.O. Box 97 Folsom, CA 95763-0097 (916) 344-4825 CATS (Commodore Applications and Technical Support) can be contacted for Amiga technical docs, include files, etc: CATS 1200 Wilson Drive West Chester, PA 19380 (215) 431-9180 LEGAL STUFF ----------- The Programmer's Support information is Copyright (C) 1987-1991 Digital Creations Inc. All rights reserved. It is freely distributable as long as it is distributed intact and contains the above copyright notice. This kit may not be included with any commercial software without written permission from Digital Creations. REVISIONS --------- v3.1 - 06 Aug 1992 - library and toolkit rev . Examples . changed CXBRK() -> chkabort() and __chkabort() . misc Aztec C and SAS/C compatibility changes . Libraries: . supergen.library 3.37, copinit.library 2.7 . fixed a race condition in supergen.library initialization. . builds copper lists in a more system friendly manner. . Programmer.doc . new address v3.0 - 13 Dec 1991 - 2000s and SG10 disk update . Library . added ARexx function library support (see separate ARexx doc) . Created prototype files that resemble v37.1 Amiga system includes: . clib/supergen_protos.h . clib/copinit_protos.h . supergen/supergen.h . Removed old function declarations. . Removed a bunch of 'L's from constants. These were mainly for pre-ANSI compilers using 16-bit int's. With prototypes, this is no longer necessary or desirable: results in far less bizarre casting in examples. . SGGetRegister() macro added. . Dropped SuperGenName . Changed SuperGenVersion -> SUPERGEN_Minimum . supergen/supergen.i . Dropped SuperGenName . Changed SuperGenVersion -> SUPERGEN_Minimum . Created separate pragmas files for Aztec C 5.0 and SAS/C 5.1. . Examples . Updated for ANSI C. . Updated to use #pragmas for both Aztec C and SAS/C. . Updated for v37.1 include files. v2.1 - 18 Jul 1990 - Updated for Aztec C 5.0 and some AmigaDOS 2.0 compatibility. v2.0 - 19 Oct 1989 - First 2000s release