Chapter 2 - Getting Started

This chapter tells you how to install and use the TMS340 Graphics Library. The 
installation procedures for the IBM PC (or compatible) are described. The 
procedures for installing the library on VAX, Apollo, Sun and Macintosh  
systems  are  similar,  but  the  details  are presented in the  readme.1st 
documentation files on the distribution media containing the library software.

Installation and testing of the library package should be straightforward if 
you have either of the following:

1) One of the TMS34010- or TMS34020-based graphics cards supported by 
   Texas Instruments (listed in the next section)

2) A proprietary port of the library from a graphics card manufacturer

If you are planning to port the library yourself to a proprietary card, you may 
want to begin by checking out the library on a card to which it has already 
been ported, if one is available to you.

A collection of library-based demonstration programs is included in both source 
and executable form. You can verify that your graphics card works correctly by 
running the programs on it. Once this is done, you can verify that your 
graphics library and the other TMS340 software tools are configured correctly 
by recompiling and relinking the demos. At this point, you should be ready to 
begin developing your own application programs, porting the library to a new 
graphics card, or adding proprietary functions to the graphics library.

Also described in this chapter is the organization of the library files, which 
are partitioned into several subdirectories. The library directory structure 
isolates the system-dependent library functions from the system-independent 
ones. This serves to clearly identify which files need to be modified when the 
library is ported to a new graphics card. The directory structure also allows 
the library to be used simultaneously for development with two or more 
TMS34010- or TMS34020-based graphics cards. For instance, your system might 
contain both a proprietary graphics card that you are in the process of 
developing, and a software development board from TI to support initial 
software development.

The procedure for converting bit-mapped fonts between the TIGA and TMS340 
Graphics Library file formats is described at the end of this chapter. 
Distributed with the graphics library are 108 fonts that have already been 
converted to the library's format.

2.1 Supported Graphics Cards

At the time of this writing, the distribution media for the TMS340 Graphics 
Library contain hardware-specific support for the following TMS34010- and 
TMS34020-based graphics cards from Texas Instruments:

1) TMS34010 TDB (TIGA Development Board) and compatibles. This 
   TMS34010-based PC add-in card contains a TMS34092 VGA Interface Chip,
   which is a memory and pixel pipeline peripheral
   for low-cost PC video adapters using
   the TMS34010. VGA pass-through capability is provided. The current library
   implementation supports the TDB with a minimum memory configuration of 512 
   kilobytes of video RAM (and no DRAM). The card is physically socketed for up 
   to 1 megabyte of video RAM and up to 1 megabyte of DRAM. The TDB is
   software-configurable to drive 640-by-480 and 1024-by-768-resolution analog
   RGB monitors at 1, 2, 4, and 8 bits/pixel.

2) TMS34010 SDB (Software Development Board). This PC add-in card serves 
   as a hardware platform for developing and testing TMS34010 software. It 
   contains 256 kilobytes of video RAM and 512 kilobytes of DRAM and is 
   configured to drive a 640-by-480-resolution RGB monitor at 4 bits/pixel.

3) TMS34020 SDB (Software Development Board). This PC AT add-in card 
   serves as a hardware platform for developing and testing TMS34020 software. 
   The card provides VGA pass-through capability
   and can be configured for a data bus width of
   8 or 16 bits. On-card memory consists of 1 megabyte of video RAM and 1
   megabyte of DRAM, and the video output is software-configured to drive 
   640-by-480- and 1024-by-768-resolution RGB monitors at 4 and 8 bits/pixel. 
   The card is socketed for an optional TMS34082 Floating-Point Coprocessor.

Ports to additional TMS340x0-based graphics cards may be available by the time 
you read this. Refer to the documentation files on the library distribution 
media for updates. You may also wish to consult the TMS340 Graphics Bulletin 
Board System (telephone number (713) 274-2417) or your graphics card 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.

2.2 Installation

To install the TMS340 Graphics Library on the hard disk of your IBM PC or 
compatible, create a directory named c:\glib340. (You can pick another name if 
you prefer, but you will later have to modify the makelib.bat batch file.) 
Switch to directory \glib340 and download all the files from the distribution 
floppy disks to this directory.

Among the downloaded files are several compressed archive files, identified by 
their *.zip file name extensions. The following is a list of the archive files 
and their contents:

- corprims.zip	Core Primitives Library functions

- extprims.zip	Extended Primitives Library functions

- include.zip 	Include files (with *.h and *.inc extensions)

- fonts.zip  	Bit-mapped fonts (108 fonts in 20 typefaces)

- tdb10.zip 	Support for TMS34010 TIGA Development Board

- sdb10.zip 	Support for TMS34010 Software Development Board

- sdb20.zip 	Support for TMS34020 Software Development Board

The last three 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.)

2.2.1 Library Directory Structure

Each of the *.zip archive files listed above contains not only files, but also 
the directory structure to contain the files. When dearchived, each archive 
file creates a subdirectory to the main library directory, \glib340, with the 
same name as the archive file. For example, the subdirectory contained in 
archive file corprims.zip is \glib340\corprims. When you dearchive 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
........oemprims   TMS34010 TDB hardware-dependent functions
........demos	   Demo programs for TMS34010 TDB
....sdb10	   TMS34010 SDB-specific support
........oemprims   TMS34010 SDB hardware-dependent functions
........demos	   Demo programs for TMS34010 SDB
....sdb20	   TMS34020 SDB-specific support
........oemprims   TMS34020 SDB hardware-dependent functions
........demos	   Demo programs for TMS34020 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 TMS34010- 
or TMS34020-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 directories can be used without modification.
Wherever possible, the graphics library uses the same source files as TIGA. The 
source files for all library functions that differ in implementation from their 
TIGA counterparts are isolated in the \oemprims directory. The source files for 
all the library functions contained in the \corprims and \extprims directories  
are  identical  to  their  TIGA  counterparts.  However,  the  coredefs.c 
source file in the \corprims directory, which defines the library's global 
variables env, pattern, and sysfont, differs from the TIGA version of this 
file, which defines additional variables not used in the library. 

The graphics library's \include directory contains C and assembly language 
include files (with *.h and *.inc file name extensions). Some of these files 
differ from the TIGA include files with the same names. The files in the 
\include directory are similar to the original TIGA include files but have been 
edited to eliminate references to TIGA functions and data structures not used 
in the library. These edits have been made strictly for the sake of clarity, 
and you should be able to directly replace the library's include files with the 
original TIGA files if you choose. (The exception to this statement is the 
oem.inc file, which is discussed in Section 2.5.)

The \fonts directory contains the 108 bit-mapped fonts that are distributed 
with the library. These fonts have been converted to the file format required 
for use with the library. The method for converting files between the TIGA and 
graphics library font formats is straightforward and is described in Section 
2.6.

2.2.2 Dearchiving the Library Files and Subdirectories

The procedure for dearchiving 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 dearchive the *.zip files one at a time, you may do 
so. For example, to dearchive the Extended Primitives Library (and create the 
\extprims subdirectory), enter the following MS-DOS command:

pkunzip -d -o extprims.zip

Note that the dearchiving utility pkunzip.exe used above is included in the 
distribution floppy disks containing the library. For a brief explanation of 
the capabilities of the pkunzip.exe utility, enter the MS-DOS command pkunzip 
with no command-line arguments.

2.2.3 Running the Library Demos

Once you have dearchived the subdirectories, you can test your graphics card by 
running the appropriate set of demonstration programs. The demos for a 
particular card are contained in the subdirectory for that card. For example, 
the demos for the TMS34010 TIGA Development Board reside in the subdirectory 
\glib340\tdb10\demos. You can invoke the batch file demo.bat in this 
subdirectory to run the demos for you.

In each \demos subdirectory is a copy of the COFF loader utility, gspl.exe. The 
demo.bat batch file described in the preceding paragraph uses the loader to 
download a TMS340x0 executable file in COFF format from disk to 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 TMS34010- 
or TMS34020-based graphics card. The configuration data is stored in a second 
file, gspl.ini, that resides in the same \demos subdirectory as the gspl.exe 
file. For more details on the use of the loader, refer to the description in 
the gspl.doc text file in the main library directory, \glib340.

2.3 Using and Modifying the Library

You may plan to use the TMS340 Graphics Library in some or all of the following 

ways:

- Write your own application program that calls the functions in the 
  library.

- Port the library to a proprietary graphics card.

- Write customized graphics functions to be used as extensions to the 
  standard library.

Each of these three usages of the library is discussed, in turn, below.

2.3.1 Writing Your Own Application Program

If you plan to write your own applications program to call the functions in the 
graphics library, you may want to begin by verifying that your software tools 
are configured correctly to compile and link programs that run on the TMS340 
graphics processor. A convenient way to do this is to compile and link the 
demonstration programs contained in the \demos subdirectory for the target 
graphics card. The makedem.bat batch file that resides in the \demos 
subdirectory is available to automate the process of rebuilding the demos. To 
update the demos, change to the appropriate \demos subdirectory and enter 
-makedem" at the MS-DOS command line. Running  this batch file  automatically   
compiles   and   links   any  demos that need to be  updated.  If  you  have   
just  installed  the  graphics  library  on  your  system, makedem.bat will 
update all the demos.

The makedem.bat batch file invokes the make.exe utility program that is 
distributed with the graphics library. A make program is a utility for 
automating program development. It can automatically update an executable file 
whenever changes are made to one of its source or object files. For example, if 
you make an edit to demo source file test01.c and run the makedem.bat batch 
file again, the make utility will detect the fact that the test01.c file is 
more recent than the test01.obj relocatable object file, and will update this 
file. It will then detect that the new test01.obj file is more recent than the 
test01.out executable file, and update this file as well. Specified as a 
command-line argument to the make program is the name of a make description 
file, typically with a *.mak file name extension. This file specifies to the 
make utility which modules are required to update the executable file. The 
Texas Instruments make utility is similar to the one from Microsoft but has 
some additional capabilities described in the make.doc text file that resides 
in the main library directory.

The makedem.bat batch file, which invokes the make utility, specifies the make 
description file demos.mak as the input file to the make utility. The demos.mak 
file in turn refers to the lc.cmd link command file, which directs the  linker  
to the  object  library  archive  files that need to be linked with  the demo 
program. These object  archives include the  corprims.lib, extprims.lib, and 
oemprims.lib libraries shipped with the TMS340 Graphics Library, and also the 
rts.lib and flib.lib libraries shipped with the TMS340 Family C Compiler.
At this point, you should be able to create your own C-language program 
(perhaps by modifying an existing demo program), and compile and link it. If 
you name the source file -test.c", you can invoke the maketst.bat batch file, 
which resides in the \demos subdirectory, to automatically compile, link, and 
execute the program for you. You can verify this by copying one of the demo 
source files to test.c and entering -maketst" at the MS-DOS command line.

2.3.2 Porting the Library

To port the TMS340 Graphics Library to a proprietary TMS34010- or 
TMS34020-based graphics card, you will need to modify the hardware-dependent 
functions in the Core Primitives Library. For convenience, these functions have 
been isolated in the \oemprims subdirectory corresponding to each of the 
graphics cards supported in the library. The functions located in the \corprims 
and \extprims directories do not in general require porting.

The \oemprims directory also isolates all graphics library functions that 
differ in implementation from their TIGA counterparts. The source code files 
for the functions in the \corprims and \extprims directories are identical to 
those distributed in the TIGA interface package.

As an example, the following is a list of the C and assembly-language source 
code files contained in the \oemprims directory for the TMS34010 TIGA 
Development Board:

clearfrm.asm	Source code for clear_frame_buffer routine

clearpag.asm	Source code for clear_page routine

clearscr.asm	Source code for clear_screen function

delay.asm	Called indirectly by set_config routine

getneare.asm	Source code for get_nearest_color routine

nullpatn.asm	Referred to within set_config routine

getrev.asm	Called by set_config routine

setdptch.asm	Called by set_config routine

trapvect.asm	Source code for get_vector and set_vector routines

config.c	Source code for set_config routine

getmode.c	Source code for get_modeinfo routine

getpalet.c	Source code for get_palet and get_palet_entry routines

initpale.c	Source code for init_palet routine

initvide.c	Called by set_config routine

oem.c		Data structures accessed by set_config routine

oemdata.c	Data structures accessed by set_config routine

pagewait.c	Source code for page_flip, page_busy, and wait_scan
		routines

setpalet.c	Source code for set_palet and set_palet_entry routines

oem.h		C include file containing system-dependent parameters

oem.inc 	Assembly-language include file containing system-
		dependent parameters

The lists for the TMS34010 and TMS34020 SDBs are similar.

The oem.h include file defines the hardware-dependent data structure, SETUP. 
The oemdata.c file contains an array of SETUP structures, each of which 
contains the parameters needed to configure the graphics card in a particular 
graphics mode. These parameters include screen width and height, pixel size, 
video timing, display pitch, video page (or frame buffer) addresses, and any 
card-specific initialization data. The SETUP structure for a proprietary 
graphics card may need to be customized to accommodate the proprietary features 
of that card. For instance, the SETUP structure can be modified to contain the 
initial values loaded into on-card registers.

The getrev.asm file listed above contains the getrev routine that is called by 
the library function set_config to obtain the silicon revision number of the 
TMS34010 or TMS34020 processor. Both the TIGA and TMS340 Graphics Library 
versions of getrev obtain the revision number by executing the assembly 
language instruction REV. The graphics library version of this file, however, 
differs from TIGA in that it also contains a default illegal opcode interrupt 
service routine (ISR) that is installed at the time the program is loaded into 
TMS340 graphics processor memory. The primary purpose of this ISR is to support 
the earliest versions of the TMS34010, which treat REV as an illegal opcode. If 
your graphics card contains a TMS34020, or a later version of the TMS34010 that 
recognizes REV as a valid instruction, you can delete the ISR from the 
getrev.asm file if you wish. (At the time of this writing, one potential reason 
for removing the ISR is that not all TMS34010 and TMS34020 debuggers understand 
how to deal intelligently with an ILLOP trap vector installed at load time.) If 
you delete the ISR, you will also need to modify the lc.cmd link command file 
that resides in the \demos directory. As shipped with the library, lc.cmd is 
set up to install the ILLOP trap vector at the time a library-based application 
is loaded into TMS340 graphics processor memory. Refer to the SECTIONS 
directive at the end of lc.cmd.

2.3.3 Developing Custom Graphics Functions

For the benefit of programmers who wish to modify the existing graphics 
functions or write their own custom functions, the TMS340 Graphics Library is 
distributed in both source and object form. Before undertaking development of 
new functions, you may wish to verify that the software tools are configured 
correctly by recompiling the object library files from the existing source 
files. The makelib.bat batch file in the main library directory, \glib340, 
automates the process of remaking the object libraries. This batch file creates 
the following object library archive files:

corprims.lib	Resides in \corprims subdirectory.

extprims.lib	Resides in \extprims subdirectory.

oemprims.lib	Resides in \oemprims subdirectory for specified
		target graphics card.

Each archive file is built using the gspar.exe archive utility program 
described in the TMS340 Family Code Generation Tools User's Guide. The 
makelib.bat batch file also recompiles and relinks the demo programs for the 
target graphics card. Note that the core and extended primitives contained in 
the \corprims and \extprims subdirectories are hardware-independent and run 
without modification on any of the graphics cards currently supported by the 
library. The hardware-specific core primitives are contained in the \oemprims 
directory for each supported card.

The makelib.bat batch file can be invoked from the main library directory, 
\glib340, with an MS-DOS command-line argument specifying the target graphics 
card. For example, to configure the library to run on the TMS34010 TIGA 
Development Board, the MS-DOS command is

makelib tdb10

If you intend to configure the library for one of the other supported graphics 
cards, you can obtain instructions on how to do this by entering the MS-DOS 
command makelib with no command-line arguments.

Once the object library has been remade by the makelib.bat batch file, it can 
be updated to reflect changes in the source files. For example, if you edit the 
cpw.asm  source file in the  \corprims	directory  and	 invoke  makelib.bat a
second time, the batch file will detect that cpw.asm has been updated and will 
update the corresponding object file, cpw.obj, contained in the corprims.lib 
object archive. (None of the other object files will be updated unless they 
need to be.)

The  makelib.bat   batch  file   invokes  the   make.exe  utility program,  
described  previously.  Each  of  the  object  archives-corprims.lib,  
extprims.lib, and oemprims.lib-is built by a make description file with a *.mak 
filename extension that resides in the same subdirectory as the object archive 
file. You may want to use an existing make description file as a model for 
writing a make description file to build your proprietary object library.

2.4 Symbolic Debugging

If you have access to a symbolic debugger, you may wish to try stepping through 
one or more of the demo programs provided with the graphics library. As 
distributed, the executable demo programs contain embedded symbolic information 
for the demo code itself, but not for the graphics library functions they are 
linked with.

The object libraries corprims.lib, extprims.lib, and oemprims.lib are 
distributed without embedded symbols in order to reduce the storage 
requirements of the distributed package. If you have a symbolic debugger and 
you need to access the symbols for one or more library functions, you can 
recompile the source code for those functions with the symbols option enabled 
and update the object libraries. The procedure for retaining symbolic 
information during the compilation, assembly, and linking stages is described 
in the TMS340 Family Code Generation Tools User's Guide.

If you are releasing a software product based on the graphics library, you 
should be aware that including embedded symbols in the object or executable 
files may significantly increase their storage requirements on disk and 
increase the time required to download the code to the TMS340 graphics 
processor. (The symbolic information is removed by the COFF loader, and it 
therefore has no impact either on the size of the code downloaded to the TMS340 
graphics processor for execution, or on the execution speed of the code.)

2.5 TMS34010 and TMS34020 Code Compatibility

The core  and  extended  primitives contained  in  the  \corprims and  
\extprims directories are, by default, configured to generate 
TMS34010-compatible code. Note that TMS34010-compatible code also runs on the 
TMS34020, although it does not take advantage of TMS34020 graphics acceleration 
features not available on the TMS34010.

If you desire, you can configure the core and extended primitives to utilize 
the TMS34020's graphics acceleration features, but the library thus configured 
will not execute on the TMS34010.

The mechanism for configuring the library involves conditional assembly 
constants GSP_34010 and GSP_34020, defined in the include file oem.inc, which 
resides in the \include directory. By default, this file defines GSP_34010 and 
GSP_34020 as having the values 1 and 0, respectively, which enables 
TMS34010-compatible code. (This code also runs on the TMS34020.) To configure 
the library for TMS34020-specific code, edit the oem.inc file to define 
GSP_34010 and GSP_34020 as having the values 0 and 1, respectively, and 
recompile the library using the makelib.bat batch file described previously. 
The resulting object code will execute correctly on the TMS34020, but not on 
the TMS34010.

The \oemprims directories for the various supported graphics cards also contain 
oem.h and oem.inc files that define conditional assembly constants GSP_34010 
and GSP_34020. As distributed, these files should already define the two 
constants correctly to accommodate the target graphics card, and you do not 
need to modify them. However, 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 TMS34010, the constants GSP_34010 and 
GSP_34020 in the oem.h and oem.inc files must be defined as 1 and 0, 
respectively. If the graphics card contains a TMS34020, the constants GSP_34010 
and GSP_34020 must be defined as 0 and 1, respectively. Hardware-specific 
functions configured to execute on the TMS34010 will not run correctly on the 
TMS34020, and vice versa.

2.6 Conversion Between TIGA and Library Font Formats

The bit-mapped fonts distributed with the TMS340 Graphics Library reside in the 
\fonts directory. Each font archive file is identified by its *.lib extension; 
each archive file contains all the fonts in a particular typeface. The archive 
is built with the gspar.exe archive utility program described in the TMS340 
Family Code Generation Tools User's Guide.

As described in Chapter 1, these fonts are identical to those distributed with 
the TIGA-340 Interface package, although the font file format differs from that 
of TIGA. Each TIGA font is distributed as a binary image file with a *.fnt file 
name extension. Each font in the TMS340 Graphics Library is distributed as a 
file in COFF format with an *.obj file name extension. The conversion between 
the TIGA and graphics library formats is straightforward with the binsrc.exe 
and cof2bin.exe conversion utilities that are distributed with the library and 
reside in the \fonts subdirectory. For more information on these utilities, 
refer to the binsrc.doc and cof2bin.doc documentation files in the \fonts 
subdirectory.

For example, to convert the austin25 font from graphics library format to TIGA 
format, use the following MS-DOS command to extract the austin25.obj file from 
the austin.lib font archive with the gspar.exe utility:

gspar -x austin.lib austin25.obj

Then use this MS-DOS command to convert the austin25.obj file, in COFF format, 
to binary format with the cof2bin.exe utility:

cof2bin austin25.obj austin25.fnt

where the output file, austin25.fnt, is in the binary format used by TIGA.

To continue the example, convert the TIGA font file austin25.fnt to the 
graphics library format in two steps. First, use the binsrc.exe utility to 
convert the TIGA font file to a TMS340 assembly language source file with the 
following MS-DOS command:

binsrc -a austin25.fnt austin25.asm

If you inspect the resulting source file, austin25.asm, you will notice that 
the label assigned to the font data structure is austin25, which is the file 
name as well. By convention, the file name (and the label) matches the global 
name assigned to this font within the graphics library. To convert from 
assembly source to COFF format,  invoke the TMS340 assembler in the usual 
manner:

gspa austin25.asm austin25.obj

The resulting output file, austin25.obj, is in the COFF format used for the 
fonts distributed with the graphics library.

