

	  ******************************************************
	  *						       *
          *              TMS340 Graphics Library               *
	  *  Installation Notes for IBM PC-Compatible Systems  *
	  *						       *
	  ******************************************************


SUPPORTED GRAPHICS CARDS
------------------------

    The distribution floppy disks for this release of the TMS340 Graphics
    Library contain hardware-specific support for the following graphics
    cards from Texas Instruments:

	1.  TMS34010 TIGA Development Board (TDB).  This PC add-in card
	    contains the TMS34092 VGA Interface Chip, which is a memory
	    and pixel pipeline peripheral for low-cost video memory
	    configurations using the 34010.  VGA pass-through capability
	    is provided.  The current library implementation supports two
	    memory configurations.  The first is a minimum-memory
	    configuration with 512K bytes of video RAM and 0K bytes of
	    DRAM.  The second is a full-memory configuration with 1M byte
            of video RAM and 1M byte of DRAM.  The TDB is capable of
            driving 640x480- and 1024x768-resolution analog RGB monitors
            at 1, 2, 4 and 8 bits/pixel.

	2.  TMS34010 Software Development Board (SDB).	This board serves
	    as a hardware platform for developing and testing 34010
	    software.  The board plugs into the IBM PC bus.  It contains
	    256K bytes of video RAM and 512K bytes of DRAM, and is
	    configured to drive a 640x480-resolution RGB monitor at 4
	    bits/pixel.

	3.  TMS34020 Software Development Board (SDB).	This board serves
	    as a hardware platform for developing and testing 34020
	    software.  The board plugs into the IBM PC bus, and provides
	    VGA pass-through capability.  It contains 1M byte of video
	    RAM and 1M byte of DRAM, and is configured to drive 640x480-
	    and 1024x768-resolution RGB monitors at 4 and 8 bits/pixel.

    Ports to additional 340x0-based graphics cards may be available by
    the time you read this.  You may wish to consult the TMS340 Graphics
    Bulletin Board System (telephone 713-274-2417) or your graphics board
    vendor for the latest developments.

    The VGA pass-through capability provided by some TMS340 graphics
    processor cards permits a single monitor to be shared between
    application programs that run through the TIGA interface and programs
    that run through the VGA.  In a graphics development environment,
    however, two monitors are virtually a necessity.  When debugging a
    program that runs on a graphics card under either the TIGA or the
    graphics library environment, one monitor is typically used to
    display the graphics card's output and a second monitor, driven by
    the PC display adapter, is used to display the debugger status.


INSTALLATION
------------

    To install the TMS340 Graphics Library on the hard disk of your
    IBM PC-compatible, create a directory named "\GLIB340".  (You can
    pick another name if you prefer, but you will later have to modify
    the first line of the MAKELIB.BAT batch file.)  Switch to directory
    \GLIB340 and download all the files on the distribution floppy disks
    to this directory.

    These are the files you have just installed in the main library
    directory, \GLIB340:

	README.1ST	 Installation instructions for graphics library
	CONFIG.BAT	 Batch file for configuring 34010/34020 code
	MAKELIB.BAT	 Batch file for building graphics library
	RELEASE.DOC	 Information about the current release
	EXAMPLES.DOC	 Copies of example programs from manual
	GSPL.DOC	 Documentation for COFF loader utility
	MAKE.DOC	 Documentation for make utility program
	MAKE.EXE	 Make utility (automates program development)
	PKUNZIP.EXE	 De-archiver utility (decompresses *.ZIP files)
	TOUCH.EXE	 Touch utility file (updates a files time stamp)
	OEM34010.INC	 Include file for 34010-compatible library code
	OEM34020.INC	 Include file for 34020-specific library code
	CORPRIMS.ZIP	 Core Primitives Library (source and object)
	EXTPRIMS.ZIP	 Extended Primitives Library (source and object)
	FONTS.ZIP	 Bit-mapped fonts and related utilities
	INCLUDE.ZIP	 Include files for C and assembly language
	SDB10.ZIP	 TMS34010 Software Development Board support
	SDB20.ZIP	 TMS34010 Software Development Board support
	TDB10.ZIP	 TMS34010 TIGA Dev. Board support (full memory)
	TDB10MIN.ZIP	 TMS34010 TIGA Dev. Board support (min. memory)

    Among the downloaded files are several compressed archive files,
    identified by their *.ZIP file name extensions.  The last four
    archive files above contain hardware-specific support for TMS34010-
    and TMS34020-based graphics cards from Texas Instruments.  If you do
    not require support for a particular card at this time, you may
    delete the corresponding *.ZIP file from your hard disk directory.
    (The file will still be on your distribution floppy disks if you
    later find that you need it.)


LIBRARY DIRECTORY STRUCTURE
---------------------------

    Each of the *.ZIP files listed above contains not only files, but
    also the subdirectory structure to contain the files.  Each file
    creates a subdirectory to the main library directory, \GLIB340, with
    the same name as the file.	For example, the subdirectory contained
    in file CORPRIMS.ZIP is \GLIB340\CORPRIMS.	When you de-archive all
    the *.ZIP files in the \GLIB340 directory, the following directory
    structure will be created:

	GLIB340 	    <-- Main library directory
	....CORPRIMS	    <-- Core Primitives Library
	....EXTPRIMS	    <-- Extended Primitives Library
	....INCLUDE	    <-- Include files (.H and .INC)
	....FONTS	    <-- Bit-mapped fonts
	....TDB10	    <-- TMS34010 TDB-specific support (full mem.)
	........OEMPRIMS    <-- Hardware-dependent functions
	........DEMOS	    <-- Demo programs for 34010 TDB
	....TDB10MIN	    <-- TMS34010 TDB-specific support (min. mem.)
	........OEMPRIMS    <-- Hardware-dependent functions
	........DEMOS	    <-- Demo programs for 34010 TDB
	....SDB10	    <-- TMS34010 SDB-specific support
	........OEMPRIMS    <-- Hardware-dependent functions
	........DEMOS	    <-- Demo programs for 34010 SDB
	....SDB20	    <-- TMS34020 SDB-specific support
	........OEMPRIMS    <-- Hardware-dependent functions
	........DEMOS	    <-- Demo programs for 34020 SDB

    The hardware-dependent functions contained in the \OEMPRIMS
    directories are really part of the Core Primitives Library, but are
    segregated from the hardware-independent core Primitives in the
    \CORPRIMS directory for convenience.  If you port the TMS340 Graphics
    Library to a proprietary 34010- or 34020-based graphics card, you
    will need to modify only the handful of hardware-independent
    functions in the \OEMPRIMS directory.  The functions in the \CORPRIMS
    and \EXTPRIMS libraries can be used as is.


DE-ARCHIVING THE LIBRARY FILES AND DIRECTORIES
----------------------------------------------

    The procedure for de-archiving the contents of all the *.ZIP files
    in the \GLIB340 directory is to enter the following single MS-DOS
    command:

		 for %x in (*.zip) do pkunzip -d -o %x

    Alternately, if you wish to de-archive the *.ZIP files one at a time,
    you may do so.  For example, to de-archive the Extended Primitives
    Library (and create the \EXTPRIMS subdirectory), enter the following
    MS-DOS command:

		 pkunzip -d -o extprims.zip

    Note that the de-archiving utility PKUNZIP.EXE used above is included
    in the distribution floppy disks containing the library.  For a brief
    explanation of the capabilities of the the PKUNZIP.EXE utility, enter
    the MS-DOS command "PKUNZIP" with no command line arguments.


RUNNING THE LIBRARY DEMOS
-------------------------

    Once you have de-archived the subdirectories, you can test your board
    by running the appropriate set of demonstration programs.  For
    example, the demos for the TMS34010 TIGA Development Board are under
    subdirectory \GLIB340\TDB10\DEMOS.	The batch file "DEMO.BAT" in this
    subdirectory will run the demos for you.  The C source code for the
    25 demo programs is contained in files TEST01.C through TEST25.C.


THE GSPL COFF LOADER UTILITY
----------------------------

    In each \DEMOS subdirectory is a copy of the GSPL.EXE COFF loader
    utility.  The DEMO.BAT batch file described in the preceding
    paragraph uses the loader to load a 340x0 executable file in COFF
    format onto the graphics card and execute it.  The GSPL.EXE loader is
    configurable, and each \DEMOS directory contains a copy of the loader
    configured for a particular 34010- or 34020-based graphics card.  The
    configuration data is contained in an accompanying file named
    GSPL.INI.  For more details on the use of the loader, refer to the
    description in the GSPL.DOC text file in the \GLIB340 directory.


RE-GENERATING THE OBJECT LIBRARY
--------------------------------

    The TMS340 Graphics Library is provided in both source and object
    form.  If you wish to generate a new object library from the source,
    you can do this by running the "MAKELIB.BAT" batch file in the
    \GLIB340 directory.  You can configure the library for the TMS34010
    SDB, TMS34020 SDB, and TMS34010 TDB by typing "MAKELIB SDB10",
    "MAKELIB SDB20", and "MAKELIB TDB10", respectively.  Note that the
    core and extended primitives contained in the subdirectories
    \GLIB340\CORPRIMS and \GLIB340\EXTPRIMS are hardware-independent, and
    should run without modification on any of the cards above.	The
    hardware- specific library functions are contained in the
    \GLIB340\???\OEMPRIMS directories, where ??? can be "SDB10", "SDB20"
    or "TDB10".  The MAKELIB.BAT batch file will also update the
    demonstration programs in the \GLIB340\???\DEMOS subdirectory.


MAKE UTILITY
------------

    A copy of Texas Instruments' MAKE.EXE utility program is distributed
    with the graphics library.	TI's make utility is similar to the one
    available from Microsoft, but has some additional capabilities
    described in the MAKE.DOC text file.  Both MAKE.EXE and MAKE.DOC
    reside in the \GLIB340 directory.  The MAKELIB.BAT batch file
    described in the preceding paragraph makes extensive use of the make
    utility to generate the object library archives and demo programs.


34010 AND 34020 CODE COMPATIBILITY
----------------------------------

    As shipped, the core and extended primitives contained in the
    \CORPRIMS and \EXTPRIMS directories are by default configured to
    generate 34010-compatible code.  Note that 34010-compatible code also
    runs on the 34020, although it does not take advantage of 34020
    graphics acceleration features not available on the 34010.	You can
    can configure the core and extended primitives to utilize the 34020's
    graphics acceleration features, but the library thus configured will
    not execute on the 34010.

    The library can be configured to generate 34020-specific code by
    invoking the CONFIG.BAT batch file in the \GLIB340 directory as
    follows:
		       CONFIG 34020
    The library can again be configured to generate 34010-compatible code
    by executing the command
		       CONFIG 34010

    The mechanism for configuring the library involves conditional
    assembly constants GSP_34010 and GSP_34020, defined in the assembly-
    language include file OEM.INC, which resides in the \INCLUDE
    directory.	By default, these files define GSP_34010 and GSP_34020 as
    having the values 1 and 0 respectively, which enables 34010-
    compatible code.  To configure the library for 34020-compatible code,
    you can edit the OEM.INC file to define GSP_34010 and GSP_34020 as 0
    and 1, respectively, and re-build the object libraries with the
    MAKELIB.BAT batch file described previously.  Again, this code will
    execute correctly on the 34020 only.

    As an alternative to the method described in the preceding paragraph,
    the CONFIG.BAT batch file automates the reconfiguration of the object
    library files in the \CORPRIMS or \EXTPRIMS subdirectories for either
    34010-compatible or 34020-specific code.  This batch file resides in
    the main library directory.  Entering "config 10" at the MS-DOS
    command line configures the library for 34010-compatible code;
    entering "config 20" configures it for 34020-specific code.  The
    TOUCH.EXE utility invoked in CONFIG.BAT merely updates the time stamp
    on the OEM.INC file copied to the \INCLUDE directory.  This is done
    for the benefit of the MAKE.EXE utility invoked later in the batch
    file.

    The \GLIB340\???\OEMPRIMS directories for the various supported
    graphics cards also contain OEM.INC and OEM.H files that define
    conditional assembly (and compilation) constants GSP_34010 and
    GSP_34020.	These include files should already define the two
    constants correctly to accommodate the target graphics card, and you
    do not need to modify them.  If you are porting the library to a
    proprietary graphics card, you should know that the role of these
    constants in the \OEMPRIMS directory is slightly different from that
    in the \CORPRIMS and \EXTPRIMS directories.  In the case of the
    \OEMPRIMS directory, the two constants are specific to the processor
    on the target graphics card.  In other words, if the graphics card
    contains a 34010, the constants GSP_34010 and GSP_34020 must be
    defined as 1 and 0, respectively.  If the graphics card contains a
    34020, the constants GSP_34010 and GSP_34020 must be defined as 0 and
    1, respectively.  OEM-specific functions configured to execute on the
    34010 will not run correctly on the 34020, and vice versa.


IF YOU NEED HELP
----------------

    Finally, if you get stuck you can always call the TMS340 Graphics
    Hotline for assistance.  The hotline telephone number is
    713-274-2340.

