Chapter 3 - Graphics Library Overview

The TMS340 Graphics Library is a collection of software functions for drawing 
text and graphics on a bit-mapped display controlled by a TMS340 Family 
Graphics System Processor. The library represents a subset of the core and 
extended primitives available to applications running under the TIGA-340 
Interface environment, as described in the TIGA-340 Interface User's Guide. The 
TMS340 Graphics Library package currently supports two software-compatible 
TMS340 graphics processors, the TMS34010 and TMS34020. Full source code is 
provided for all library functions. Also distributed with the library are a 
number of demonstration programs and a collection of bit-mapped fonts. The 
library can easily be ported to run on display systems spanning a broad range 
of display resolutions and pixel depths.

The graphics library is intended to be used with Release 4.00 or above of the 
TMS340 Family Code Generation Tools from Texas Instruments, as described in the 
TMS340 Family Code Generation Tools User's Guide. These software development 
tools include a C compiler, assembler,  linker, archiver, and additional 
utilities.

The library, as distributed, is configured to run on several TMS34010- and 
TMS34020-based graphics boards, including the TMS34010 and TMS34020 Software 
Development Boards available from Texas Instruments. An up-to-date list of 
display hardware to which the library has already been ported is available in 
the documentation files on the magnetic media on which the library is 
distributed. Porting the library to additional TMS340 graphics processor-based 
displays is straightforward; the system implementation issues involved in 
porting or extending the library are addressed later in this chapter.

The TMS340 Graphics Library contains all of the extended primitives distributed 
with the TIGA-340 Interface package, but only a subset of the TIGA core 
primitives. This is due to the differences between the TIGA environment and 
that of the graphics library. TIGA provides a convenient interface for dividing 
processing tasks between the TMS340 graphics processor and a host processor. 
Graphics applications executing through TIGA can improve their performance by 
utilizing the processing power of the host and the TMS340 graphics processor 
together in parallel. Refer to the TIGA-340 Interface User's Guide for details.

In contrast to TIGA, the TMS340 Graphics Library is designed to support the 
development both of applications that reside completely on the TMS340 graphics 
processor and of applications that rely on proprietary software interfaces for 
TMS340 graphics processor communications with other processors.

The environment of the TMS340 Graphics Library is simpler than TIGA's in two 
respects:

1) TIGA executes on two processors, the host and the TMS340 graphics 
   processor, which operate in parallel. The graphics library, on the other 
   hand,
   executes on the TMS340 graphics processor alone.

2) TIGA utilizes interrupts, whereas the graphics library does not. Where 
   necessary, graphics library functions poll interrupt requests, but the 
   interrupts are disabled.

The TMS340 Graphics Library offers the following benefits:

- Convenient access to TMS340 graphics processor capabilities and 
  performance for evaluation by potential developers

- A simple, single-processor environment for learning about and 
  prototyping with the TMS340 graphics processor

- Working examples of graphics functions written in assembly code for the 
  TMS340 graphics processor

- An easily portable software package for shaking out new TMS340x0-based 
  hardware designs

- Library routines that can be utilized as defined, or adapted to serve 
  proprietary needs

- A library of graphics functions that run independently of the TIGA 
  dual-processor environment

- A simplified environment for initial development and debugging of 
  software that executes under the TIGA Graphics Manager

Regarding the last item above, developers of proprietary graphics extensions to 
the standard TIGA primitives may find the simpler environment of the TMS340 
Graphics Library to be more convenient for the initial testing and debugging of 
customized code. Once a proprietary graphics function has been successfully 
tested within the library environment, it can be subjected to further testing 
within the more complex TIGA environment. Porting a function from the graphics 
library to TIGA is in most cases trivial because of the similarity of the two 
graphics environments.

3.1 Graphics Capabilities

The functions in the TMS340 Graphics Library are designed to execute over a 
wide range of display resolutions and pixel depths. The range of screen 
resolutions supported by the library spans the available raster display 
technology. The pixel sizes supported by the library are 1, 2, 4, 8, 16, and 32 
bits.

The library achieves this level of display independence by exploiting the 
inherent graphics capabilities of the TMS34010 and TMS34020 graphics 
processors. Software executing on a TMS340 processor can configure display 
parameters such as display dimensions and pixel size by simply loading the 
parameters into dedicated hardware registers. The processor's graphics 
instructions automatically make the adjustments necessary to accommodate the 
parameters of the display.

By default, library functions that output graphics to the display simply 
overwrite destination pixels with source pixels. The library, however, supports 
several optional methods for combining source and destination pixel values to 
produce the final pixel values written to the screen:

- A variety of Boolean and arithmetic operations are supported for 
  combining source and destination pixels.

- Designated bits within pixels can be masked off to protect the bits 
  against modification during writes.

- Objects written to the screen can contain transparent regions through 
  which the original background is visible.

The three capabilities above are not mutually exclusive. They can be configured 
independently by calls to library functions, and used in any combination when 
drawing to the display.

The library has been carefully designed to make the behavior of the graphics 
functions predictable in all cases. The library follows well-defined 
conventions for mapping pixels to x-y coordinates, for determining which pixels 
are contained within the boundaries of filled regions, and for selecting thin, 
but connected, sets of pixels to approximate lines and arcs.

All graphics output is automatically clipped to the boundaries of the display. 
A clipping window can be defined that restricts graphics output to a 
rectangular region of the display.

3.2 Core and Extended Primitives

The TMS340 Graphics Library is divided into two sub-libraries, the Core 
Primitives Library and the Extended Primitives Library. TIGA similarly divides 
the library functions into a set of core primitives that are permanently 
installed as part of the Graphics Manager, and a set of extended primitives 
that can be installed as an extension to the core primitives. The distinction 
between core and extended primitives is of less importance in the TMS340 
Graphics Library environment than in TIGA but is maintained for the sake of 
uniformity with the TIGA environment and documentation.

Within the graphics library environment, the differences between core and 
extended primitives are primarily functional. The core primitives are, in 
general, dedicated to initializing, configuring, and interrogating the graphics 
environment but provide only rudimentary capabilities for drawing to the 
display. The extended primitives provide a broader range of text and graphics 
output capabilities, including the abilities to draw text in a variety of 
proportionally spaced fonts and to draw graphics objects such as lines, 
ellipses, arcs and polygons.

Table 3-1 is a comprehensive, alphabetical listing of the functions available 
in the 
TMS340 Graphics Library. The rightmost column identifies the function as 
belonging to either the core or extended primitives. The Core Primitives and 
Extended Primitives Libraries are described in Chapters 6 and 7 of this user's 
guide as separate, but related libraries.

Table 3-1. Summary of Library Functions

Function Name		Description				Type

bitblt			Transfer bit-aligned block		Ext

clear_frame_buffer	Clear frame buffer			Core

clear_page		Clear current drawing page		Core

clear_screen		Clear screen				Core

cpw			Compare point to clipping window	Core

cvxyl			Convert x-y position to linear address	Core

decode_rect		Decode rectangular image		Ext

delete_font		Delete font				Ext

draw_line		Draw line				Ext

draw_oval		Draw oval				Ext

draw_ovalarc		Draw oval arc				Ext

draw_piearc		Draw pie arc				Ext

draw_point		Draw point				Ext

draw_polyline		Draw polyline				Ext

draw_rect		Draw rectangle				Ext

encode_rect		Encode rectangular image		Ext

field_extract		Extract field from TMS340		Core
			graphics processor memory

field_insert		Insert field into TMS340 graphics 	Core
			processor memory

fill_convex		Fill convex polygon			Ext

fill_oval		Fill oval				Ext

fill_piearc		Fill pie arc				Ext

fill_polygon		Fill polygon				Ext

fill_rect		Fill rectangle				Ext

frame_oval		Fill oval frame 			Ext

frame_rect		Fill rectangular frame			Ext

Table 3-1. Summary of Library Functions (Continued)

Function Name		Description			       Type

get_colors		Get colors			       Core

get_config		Get hardware configuration information	Core

get_env 		Get graphics environment information	Ext

get_fontinfo		Get font information		       Core

get_modeinfo		Get graphics mode information	       Core

get_nearest_color	Get nearest color		       Core

get_offscreen_memory	Get off-screen memory		       Core

get_palet		Get entire palette		       Core

get_palet_entry 	Get single palette entry	       Core

get_pixel		Get pixel			       Ext

get_pmask		Get plane mask			       Core

get_ppop		Get pixel processing operation code 	Core

get_textattr		Get text attributes			Ext

get_text_xy		Get text x-y position			Core

get_transp		Get transparency flag			Core

get_vector		Get trap vector 			Core

get_windowing		Get window clipping mode		Core

get_wksp		Get workspace information		Core

gsp2gsp 		Transfer from one location to		Core
			another within TMS340 graphics
			processor memory

in_font 		Verify characters in font		Ext

init_palet		Initialize palette			Core

init_text		Initialize text 			Core

install_font		Install font				 Ext

lmo			Find leftmost one			Core

move_pixel		Move pixel				Ext

Table 3-1. Summary of Library Functions (Continued)

Function Name		Description			      Type

page_busy		Get page busy status		       Core

page_flip		Flip display and drawing pages	       Core

patnfill_convex 	Fill convex polygon with pattern	Ext

patnfill_oval		Fill oval with pattern			Ext

patnfill_piearc 	Fill pie arc with pattern		Ext

patnfill_polygon	Fill polygon with pattern 		Ext

patnfill_rect		Fill rectangle with pattern		Ext

patnframe_oval		Fill oval frame with pattern		Ext

patnframe_rect		Fill rectangular frame with pattern	Ext

patnpen_line		Draw line with pen and pattern		Ext

patnpen_ovalarc 	Draw oval arc with pen and pattern	Ext

patnpen_piearc		Draw pie arc with pen and pattern	Ext

patnpen_point		Draw point with pen and pattern 	Ext

patnpen_polyline	Draw polyline with pen and pattern	Ext

peek_breg		Peek at B-file register 		Core

pen_line		Draw line with pen			Ext

pen_ovalarc		Draw oval arc with pen			Ext

pen_piearc		Draw pie arc with pen			Ext

pen_point		Draw point with pen			Ext

pen_polyline		Draw polyline with pen			Ext

poke_breg		Poke value into B-file register 	Core

put_pixel		Put pixel				Ext

rmo			Find rightmost one			Core

seed_fill		Seed fill				Ext

seed_patnfill		Seed fill with pattern			Ext

select_font		Select font				Ext

Table 3-1. Summary of Library Functions (Continued)

Function Name		Description			       Type

set_bcolor		Set background color		       Core

set_clip_rect		Set clipping rectangle		       Core

set_colors		Set foreground and background colors 	Core

set_config		Set hardware configuration		Core

set_draw_origin 	Set drawing origin			Ext

set_dstbm		Set destination bit map 		Ext

set_fcolor		Set foreground color		       Core

set_palet 		Set multiple palette entries		Core

set_palet_entry 	Set single palette entry		Core

set_patn		Set fill pattern			Ext

set_pensize		Set pen size				Ext

set_pmask		Set plane mask				Core

set_ppop		Set pixel processing operation code	Core

set_srcbm		Set source bit map			Ext

set_textattr		Set text attributes			Ext

set_text_xy		Set text x-y position			Core

set_transp		Set transparency mode			Core

set_vector		Set trap vector 			Core

set_windowing		Set window clipping mode		Core

set_wksp		Set workspace information		Core

styled_line		Draw styled line			Ext

styled_oval		Draw styled oval			Ext

styled_ovalarc		Draw styled oval arc			Ext

styled_piearc		Draw styled pie arc			Ext

swap_bm 		Swap source and destination bit maps	Ext

text_out		Output text				Core

Table 3-1. Summary of Library Functions (Concluded)

Function Name		Description			       Type

text_outp		Output text at current x-y position	Core

text_width		Get width of text string		Ext

transp_off		Turn transparency off			Core

transp_on		Turn transparency on			Core

wait_scan		Wait for scan line			Core

zoom_rect		Zoom rectangle				Ext

3.3 Differences Between TIGA and TMS340 Graphics Library
      Routines

The list of functions in  is a subset of the functions available in the TIGA 
environment. Not included in the TMS340 Graphics Library are the TIGA functions 
for managing host-to-TMS340 graphics processor communications, interrupts, 
cursors, dynamic linking, and dynamic memory management. The TIGA memory 
management functions are distinguished by their names from the host processor's 
ANSI-standard C memory management functions. Because of the single-processor 
environment of the TMS340 Graphics Library, however, library-based software 
applications can simply call the standard memory management functions 
distributed with the C compiler for the TMS340 graphics processor.

The source code for the following six functions differs between the TIGA and 
the TMS340 Graphics Library implementations:

- get_config

- get_modeinfo

- page_busy

- page_flip

- set_config

- wait_scan

The get_config function retrieves system configuration information in the form 
of a CONFIG data structure. The TIGA version of the function includes the size 
of TIGA's communications buffer as part of the CONFIG structure. The buffer 
size is obtained from a global communications structure that is defined in 
TIGA's environment but not in the TMS340 Graphics Library's environment. The 
graphics library version of get_config sets the communications buffer size in 
the CONFIG structure to null.

The get_modeinfo function returns a block of information characterizing the 
designated graphics mode in the form of a MODEINFO data structure. The TIGA 
version implements this function entirely on the host processor, whereas the 
graphics library version runs entirely on the TMS340 graphics processor.

The set_config function configures the display hardware and initializes the 
graphics software environment. Typically, this function should be called before 
any of the other library functions are called. The TIGA and graphics library 
versions of set_config differ somewhat because of the differences between the 
TIGA and graphics library environments. For example, the TIGA version of 
set_config initializes the cursor management parameters; the graphics library 
does not include cursor management functions.

The page_flip, page_busy, and wait_scan routines in TIGA and the graphics 
library are functionally equivalent but differ in the way that they respond to 
display interrupt requests. The TIGA implementations rely on an interrupt 
service routine invoked by the TMS340 graphics processor's display interrupt. 
The graphics library implementations of these functions poll the display 
interrupt request and assume that the display interrupt is disabled.

3.4 Graphics Library Environment

The global variables maintained within the TMS340 Graphics Library are a subset 
of those maintained within the TIGA Graphics Manager, which is the TMS340 
graphics processor-resident portion of the TIGA software interface. These 
variables are accessible by the functions within the library. If developers add 
proprietary functions to the library, the new functions can access the 
library's global variables as well.

A list of global variables is presented in Table 3-2.
The corresponding type definitions
for the variables are given in Appendix A.

Table 3-2. Library Global Variables

Type			Global Name		Description

CONFIG			config			Current configuration

PALET			DEFAULT_PALET[16]	Default color palette

ENVIRONMENT		env			Graphics environment

ENVTEXT 		envtext 		Text environment

MODEINFO	       *modeinfo		Graphics mode
						information

OFFSCREEN_AREA		*offscreen		List of off-screen buffers

PAGE			*page			List of video pages

PALET			palet[--]		Palette currently in use

PATTERN 		pattern 		Current area-fill pattern

FONT			*sysfont		System font

TMS340 graphics processor-based applications linked with the TMS340 Graphics 
Library can access these globals directly or, if emulation of the TIGA 
applications environment is important, indirectly. Host-resident applications 
running through TIGA have no direct access to the global variables on the 
TMS340 graphics processor. TIGA provides indirect access to the globals in the 
TMS340 processor's environment through functions such as get_config, 
get_fontinfo, and get_env. The same functions provided by TIGA to indirectly 
access the TMS340 graphics processor environment are available in the TMS340 
Graphics Library.

The entire graphics environment is initialized by the set_config function, 
which must be called before any of the other functions in the graphics library 
are called. The initial call to set_config should specify a nonzero value for 
the second argument; this causes the drawing environment to be initialized. 
Refer to the description of the set_config function in Chapter 6 for more 
information.

3.5 Bit-Mapped Fonts

A total of 108 bit-mapped fonts are distributed with the TMS340 Graphics 
Library for use with the text functions in the library. The font package 
distributed with the library consists of 20 different typefaces, each of which 
is available in a variety of font sizes.

Table 3-3 is a list of the fonts distributed with the library. Most of the 
typefaces are 
proportionally spaced, although a few have uniform horizontal spacing. The 
global symbol  is the external name of the font, and the xx appended to each 
symbol is replaced with the font size. For instance, global symbol arrows25 
refers to Arrows font size 25.

Table 3-3. Summary of Available Fonts

Face Name	Global Symbol	Number of Font Sizes	Horizontal
							Spacing

Arrows		arrowsxx			2	uniform

Austin		austinxx			6	proportional

Corpus Christi	corpusxx			5	uniform

Devonshire	devonsxx			3	proportional

Fargo		fargoxx 			3	proportional

Galveston	galvesxx			6	proportional

Houston		houstnxx			6	proportional

Luckenbach	luckenxx			1	proportional

Math		mathxx				6	proportional

San Antonio	sanantxx			3	proportional

System		sysxx				2	block

Tampa		tampaxx 			4	proportional

TI Art Nouveau	ti_artxx			5	proportional

TI Bauhaus	ti_bauxx			9	proportional

TI Cloister	ti_cloxx			2	proportional

TI Dom Casual	ti_comxx			5	proportional

TI Helvetica	ti_helxx			12	proportional

TI Park Avenue	ti_prkxx			8	proportional

TI Roman	ti_romxx			12	proportional

TI Typewriter Elite   ti_typxx			 8	 uniform

Two VGA-style block fonts are provided for emulating cell-mapped text generated 
by a CRT controller with a character ROM. These are the System fonts listed 
near the middle of Table 3-3.

The fonts in  are identical to the ones distributed with the TIGA-340 Interface 
package. In the case of TIGA, the fonts are stored as binary files with .fnt 
file-name extensions. The .fnt files can be downloaded to buffers in the TMS340 
graphics processor's local memory at runtime. In the TMS340 Graphics Library, 
the fonts are distributed as COFF object files with .obj file-name extensions 
that can be linked with programs that execute on the TMS340 graphics processor.

The conversion between the TIGA .fnt and graphics library .obj formats is 
straightforward using the binsrc and cof2bin utilities discussed in Section 
2.6.

3.6 Application Programming Issues

Some of the issues that may be of interest to you if you are planning to write 
application programs based on the TMS340 Graphics Library are discussed below. 
These issues include source code portability, stack growth, and library code 
size.

3.6.1 Specifying Complete Argument Lists

As a general rule-and in particular, to ensure portability to the TIGA 
applications environment-the application program should explicitly specify all 
arguments to library functions, even if some of those arguments are ignored.

For example, the set_dstbm (set destination bit map) library function accepts 
five arguments. If the first argument is 0, however, the function ignores the 
values of the remaining four arguments. The recommended practice in a case such 
as this is to specify all arguments, although dummy values can, of course, be 
used for those arguments that are ignored:

       set_dstbm(0, 0, 0, 0, 0);

While a function call such as

       set_dstbm(0);   /*wrong*/

that omits the last four arguments may execute correctly in some instances, 
this approach is discouraged for the sake of broader portability.

3.6.2 Library Globals

As described in Section 3.4, if emulation of the TIGA applications environment 
is seen as important, the global variables defined within the library should 
not be accessed directly by application programs. Both TIGA and the TMS340 
Graphics Library provide the same functions for accessing the contents of these 
variables indirectly.

3.6.3 Portability of C Source Code

Some forethought may be required to ensure that C code written for the TMS340x0 
is portable. This may be an issue, for instance, to an applications programmer 
who plans eventually to port C routines developed in the TMS340 Graphics 
Library environment to TIGA.

As an example, the TMS340 Family C Compiler defines an integer of type int as 
32 bits. A TIGA application program, however, may be compiled to run on a PC by 
the Microsoft C Compiler, which defines an  int  as 16 bits. Fortunately, both 
the TMS340 and Microsoft compilers define types short and long as 16 and 32 
bits, respectively. Specifying all integers as type short  or  long greatly 
enhances portability between the two environments. This is the main reason that 
TIGA (and the TMS340 Graphics Library) specifies all integer function 
arguments, return values, and structure members as being of type short or long, 
rather than of type int.

3.6.4 Stack Growth

Probably the worst potential offenders in the library in regard to stack growth 
are the fill_polygon and patnfill_polygon functions. These functions allocate 
temporary storage on the system stack, and the amount of storage increases with 
the number of edges in the polygon. The actual amount of stack space allocated 
for each edge is 16 bytes. If the number of edges is quite large, the stack may 
overflow.

At the time of this writing, the size of the default stack allocated by the 
TMS340 Family C Compiler is 4000 bytes. This should be sufficient to handle 
polygons having in excess of 200 edges each.

3.6.5 Library Code Size

The TMS340 Family Linker is intelligent enough to link in only the object 
modules it requires from the library archive files. Some customers, however, 
ask how large the object code is for the entire library. Presumably, they plan 
to place the entire library in ROM.

The precise memory requirement varies from one system to another because of 
differences in the size of the system-dependent code and data. At the time of 
writing, the TMS340 Graphics Library occupies roughly 35 kilobytes of TMS340 
graphics processor memory in machine code form. This figure includes all 
routines in the library and other data such as graphics mode initialization 
structures-but excludes the fonts. The breakdown for the current port of the 
library to the TMS34010 Software Development Board is as follows:

 function code	=  25.6 	kilobytes
 other data	=    9.3 	kilobytes
 TOTAL		=  35.0 	kilobytes

As you might expect, the 108 bit-mapped fonts take up a lot of storage:

bit-mapped fonts  =  729.2 kilobytes

The worst memory hogs are the fonts with the largest point sizes. If memory 
space requirements are tight, you may need to select with care the fonts you 
use.

3.7 System Implementation Issues

The TMS340 Graphics Library can be easily customized for proprietary software 
applications and hardware systems based on the TMS340 graphics processor. This 
section explains how to port the library to proprietary hardware systems, add 
proprietary functions, or reconfigure the library for other purposes. These 
topics are covered:

1) Register Usage Conventions

2) Interrupts

3) System-Level Hardware Functions

4) Functions with System Dependencies

5) TMS34010 and TMS34020 Code Compatibility

6) Floating-Point Compatibility

7) Silicon Revision Number

3.7.1 Register Usage Conventions

To use proprietary assembly language functions in conjunction with the library 
functions, follow the library's conventions regarding usage of the TMS340 
graphics processor's registers.

When an assembly language routine is called from a program compiled with the 
TMS340 Family C Compiler, certain registers are in known states. Here are 
descriptions of those known states:

- System Stack Pointer

   The SP points to the top of the system stack.

- Status Register

  The C environment always leaves the field-1 sign and extension parameters in
  the status register defined as follows:

	FE1 = 0 (field 1 is zero-extended)
	FS1 = 0 (field 1 is 32 bits in length)

The field-0 parameters FE0 and FS0 are undefined.

- A-File Registers

  Register A14 points to the top of the C program stack.

- B-File Registers

 DPTCH-Contains screen pitch (difference in starting memory addresses of any two
 successive scan lines in display memory).

  OFFSET-Contains memory address of pixel at top left corner of screen.

  WSTART-Contains screen coordinates of pixel at top left corner of current
  clipping window.

  WEND-Contains screen coordinates of pixel at bottom right corner of current
  clipping window.

  COLOR0-Contains current background color (pixel-replicated to 32 bits).

  COLOR1-Contains current foreground color (pixel-replicated to 32 bits).

- I/O Registers

  CONTROL-The PPOP field contains the current pixel processing code. The T field
  is a 1 if transparency is enabled, and 0 otherwise. The W field is always set
  to 3 (clip to window, no WV interrupt request). The PBH and PBV bits are
  always 0.

  CONVDP-Corresponds to screen pitch in DPTCH register.

  PMASK-Contains current plane mask (pixel-replicated to 16 bits for a TMS34010
  and to 32 bits for a TMS34020).

  PSIZE-Contains current pixel size for screen.

The above assumptions apply to functions called from C programs. They do not 
apply to interrupt service routines, because such routines may interrupt a 
function that is using one of these registers for another purpose.

Prior to returning, a function called from a program compiled with the TMS340 
Family C Compiler must restore the following registers to their original state 
at entry:

- Status register fields FE1 and FS1 must be restored. Fields FE0 and FS0 
  need not be restored.

- All A-file registers except A8 must be restored. Register A14, the C 
  program stack pointer, must be updated to point to the top of the current
  program stack. Refer to the description of the function calling conventions in
  the TMS340 Family Code Generation Tools User's Guide.

- In general, all B-file registers must be restored. Certain B-file 
  registers, however, may be altered by attribute control functions. For
  instance, the set_colors function alters the contents of B8 (COLOR0) and B9
  (COLOR1), set_clip_rect alters B5 (WSTART) and B6 (WEND), and page_flip alters
  B4 (OFFSET).

- In general, I/O registers such as CONTROL, DPYCTL, CONVDP, and INTENB 
  should be restored before returning to the calling program. The contents of
  certain I/O registers, however, may be altered by attribute control functions.
  For instance, the set_ppop function alters the PPOP field in CONTROL, the
  transp_on and transp_off functions alter the state of the T bit in CONTROL,
  and set_pmask alters the contents of PMASK. As a rule, these registers are not
  modified by graphics output functions.

Take care when you write graphics routines that modify only bits 5-14 of the 
TMS340 graphics processor's CONTROL register. These 10 bits are identical in 
the TMS34010 and TMS34020, and software that accesses only these bits can 
safely ignore the differences between the two processors. The same cannot be 
said of the other 6 CONTROL bits, which control disabling of the
processor's instruction cache, the TMS34010's DRAM refreshing, and the
TMS34020's transparency mode. TI recommends that when you write to a part of 
the register, you first set the appropriate field size in the status register 
to only the portion of the register that is actually to be modified. This 
avoids disturbing the other CONTROL bits. TI discourages reading the entire 
CONTROL register, modifying a selected field, and writing back the entire 
register. While the latter method may appear to operate correctly in some 
environments, the resulting code will not be as portable or robust as code that 
uses the recommended method.

Refer to the TMS340 Family Code Generation Tools User's Guide for a description 
of the rules imposed by the TMS340 Family C Compiler on function calls.

3.7.2 Interrupts

The assembly language routines within the library use the TMS340 graphics 
processor's A14 register as general-purpose, temporary storage. Interrupt 
service routines should make no assumptions regarding the state of A14 at the 
time an interrupt occurs. In particular, they should not assume that A14 points 
to the top of the C program stack. An interrupt service routine written in C 
must allocate its own program stack. This can be done in one of several ways. 
For instance, the ISR can temporarily allocate extra space on the system stack, 
and utilize this space as program stack. Alternately, a temporary program stack 
for interrupts can be allocated statically as a global array. The latter method 
is suitable only if the ISR code is not required to be reentrant.

The library routines themselves do not use interrupts. Several library 
functions make use of the TMS340 graphics processor's WV (window violation) 
interrupt request, but they assume that the WV interrupt is disabled.

Similarly, the library's page_flip, page_busy, and wait_scan functions poll the 
DI (display interrupt) request but assume that the display interrupt is 
disabled. (In other words, the DIE bit in the INTENB register should be 0 if 
the library implementations of these functions are used.) An operating 
environment or application program that includes a display interrupt service 
routine may have difficulty coexisting with these three functions as currently 
implemented in the library.

The TIGA implementations of the page_flip, page_busy, and wait_scan functions 
are functionally equivalent to those in the TMS340 Graphics Library but rely on 
interrupts rather than polling. This is because the TIGA versions of these 
functions must share the TMS340 graphics processor's display interrupt with 
other features such as real-time cursor management. Refer to the TIGA-340 
Interface User's Guide for more information on the TIGA versions of these 
functions.

3.7.3 System-Level Hardware Functions

Several TMS340 graphics processor hardware functions are most appropriately 
controlled by systems-level software such as an operating system or control 
program, if one is present. The graphics library as distributed, however, 
assumes that no such software is present. Based on this assumption, when the 
set_config function initializes the drawing environment, it also initializes 
the following hardware functions:

1) The IE (interrupt enable) bit in the status register is set to 0.

2) The INTENB (interrupt enable) register is set to 0.

3) The CD (cache disable) bit in the CONTROL register is set to 0.

4) The DRAM refresh rate and refresh mode are initialized. This involves 
   loading the RM and RR fields in the TMS34010's CONTROL register, or the RR
   field in the TMS34020's CONFIG register.

If the library is ported to an environment in which these hardware functions 
are controlled outside of the graphics library, the code for initializing the 
parameters above should be deleted from the set_config routine.

3.7.4 Functions with System Dependencies

Most of the functions in the TMS340 Graphics Library are independent of 
system-specific features such as pixel size, frame buffer dimensions, and color 
palette hardware. This is true of all functions in the Extended Primitives 
Library. Several functions in the Core Primitives Library, however, perform 
system-dependent operations and must be ported from one TMS340 hardware 
configuration to another. The system-dependent library functions are listed 
below according to the types of hardware dependencies they have.

First, the following function performs all the hardware-specific initialization 
of the video timing registers, screen refresh, DRAM refresh, pixel size, screen 
dimensions, and so on:

- set_config

These six functions depend on the hardware palette configuration:
- get_nearest_color

- get_palet

- get_palet_entry

- init_palet

- set_palet

- set_palet_entry

The implementation of these two functions depends on whether the TMS340 
graphics processor's interrupt vectors are mapped into RAM or ROM:

- set_vector

- get_vector

The following functions may use the bulk initialization capability of some 
video RAMs:

- clear_frame_buffer

- clear_page

Bulk initialization is a method of rapidly clearing a portion of a display 
memory that is composed of video RAMs that support both 
memory-to-serial-register and serial-register-to-memory cycles. First, a single 
row is loaded from the memory array within each video RAM to the serial 
register; this is accomplished with a single memory-to-register cycle. Next, 
the contents of the serial register are rapidly copied to a series of rows; 
this is accomplished with a sequence of register-to-memory transfers.

The next function is typically implemented with a FILL instruction in a 
TMS34010-based system but may use the faster VFILL instruction if implemented 
in a TMS34020-based system with video RAMs that support block write cycles:

- clear_screen

The following functions need to be recompiled for the target processor 
(TMS34010 or TMS34020), but the source code does not require porting:

- page_flip

- wait_scan

Finally, these routines are included for convenience with the system-dependent 
functions, even though they are themselves system-independent:

- get_config

- page_busy

3.7.5 TMS34010 and TMS34020 Code Compatibility

Conditional assembly statements embedded in the assembly code for certain 
graphics functions control whether the functions are assembled to execute 
TMS34010 or TMS34020 code. The details of how to configure the library at 
assembly time are described in Section 2.5.

By default, the library as distributed is configured to generate 
TMS34010-compatible code. This code is upward-compatible with the TMS34020. 
That is, it will run correctly on the TMS34020 as well as on the TMS34010, 
although it may not take full advantage of certain graphics acceleration 
features unique to the TMS34020. Guidelines for writing upward-compatible 
TMS340 graphics processor code are given in the user's guides for the TMS34010 
and TMS34020.

If you prefer, however, the library can easily be configured to generate 
TMS34020-specific code. The current library contains implementations of a 
number of graphics functions that can be configured to take advantage of 
graphics acceleration features available only on the TMS34020. These features 
are unavailable on the TMS34010, and the code that uses these features does not 
execute correctly on the TMS34010.

If you write your own processor-dependent functions, you have an alternative to 
the conditional assembly method currently used to statically configure the 
library. The software can perform a runtime check to dynamically determine 
whether it is running on a TMS34010 or TMS34020 and can execute the appropriate 
TMS34010- or TMS34020-specific code. This approach is typically used in 
instances in which the code that performs the run-time check is not 
speed-critical. Moving a runtime check inside the inner loop of a 
speed-critical assembly-coded graphics function, for instance, would probably 
be inappropriate.

If you are writing a proprietary function as an extension to the existing 
graphics library,  you  can  perform  a runtime  processor check by reading  
the device_rev  field of the global structure config. The same information is 
available to application programs in the device_rev  field of the CONFIG 
structure retrieved by the get_config function.

3.7.6 Floating-Point Compatibility

Versions 4.0 and above of the TMS340 Family C Compiler can be configured to 
generate either TMS340-compatible or IEEE-compatible floating-point values, as 
described in the TMS340 Family Code Generation Tools User's Guide. The graphics 
library does not utilize any of the floating-point math routines distributed 
with the C compiler. The applications programmer can configure proprietary code 
to use either of the two floating-point formats without concern for the effect 
this choice will have on the graphics library functions.

The IEEE-compatible format is defined in the IEEE Standard 754 for Binary 
Floating-Point Arithmetic. The TMS340-compatible format is similar to the IEEE, 
except that it uses an explicit leading 1 in the mantissa in place of the 
implicit leading 1 used in the IEEE format. For more information, refer to the 
TMS340 Family Code Generation Tools User's Guide.

3.7.7 Silicon Revision Number

The TMS340x0 REV assembly-language instruction generates a silicon revision 
number that identifies the processor as a TMS34010 or TMS34020 and also 
indicates the silicon revision. One of the initialization operations performed 
by the library's set_config function  is to load the revision number into the 
device_rev field of the global structure config mentioned earlier. (Refer to 
the description of the CONFIG data structure in Appendix A.)

The earliest TMS34010 devices do not recognize the REV instruction; they treat 
it as an illegal opcode. To permit the TMS340 Graphics Library to run without 
mishap on these early devices, the library includes an illegal opcode interrupt 
service routine that emulates execution of the REV instruction.

If your graphics card contains a TMS34020, or a later version of the TMS34010 
that recognizes REV as a valid instruction, you may choose to delete the 
illegal opcode ISR from the library. Please refer to subsection 2.3.2 for 
details.

